Getting Started

Python Runner lets you deploy a Python web application directly from your GitHub repository (or an S3 zip archive) and run it as a managed service in Open Source Cloud. OSC clones your repository, installs dependencies from requirements.txt, and starts your application automatically.

Prerequisites

  • An OSC account. Sign up here.
  • A Python web application in a GitHub repository (public or private) or packaged as a zip file in an S3 bucket.
  • Your application must listen on port 8080 (the default port used by the Python runner).

Create a Python Runner instance

Navigate to Python Runner in the OSC web console, click Create python-runner, and fill in the fields:

Field Required Description
name Yes Unique name for this instance. Alphanumeric and underscores only.
SourceUrl Yes GitHub repository URL (e.g. https://github.com/org/repo) or S3 URL to a zip archive (e.g. s3://bucket/app.zip). Append #branch to target a specific branch.
GitHubToken No Personal access token for private GitHub repositories. Store as a service secret and reference it as {{secrets.mytoken}}.
AwsAccessKeyId No AWS access key for S3 sources.
AwsSecretAccessKey No AWS secret key for S3 sources. Use a service secret reference.
AwsRegion No AWS region for S3 access.
S3EndpointUrl No S3-compatible endpoint URL (e.g. a MinIO instance URL).
OscAccessToken No OSC personal access token, required if your application calls other OSC services.
ConfigService No Name of an Application Config Service instance used to inject environment variables at startup.

Click Create. OSC clones the repository, installs dependencies, and starts your application. Once the status shows Running, click the generated URL to reach your app.

How auto-detection works

The Python runner automatically detects your application type and starts it without any configuration file. The following table describes what happens for each detected pattern:

Detected condition What the runner does
requirements.txt present Runs pip install -r requirements.txt before startup
gunicorn in requirements.txt AND app.py or wsgi.py present Runs python -m gunicorn <module>:app --bind 0.0.0.0:${PORT}
uvicorn in requirements.txt AND app.py or main.py present Runs python -m uvicorn <module>:app --host 0.0.0.0 --port ${PORT}
None of the above Runs python app.py (falls back to direct script execution)

Important: Procfile is NOT supported. The Python runner does not parse or honor a Procfile. If your repository contains a Procfile, it is silently ignored. Use the auto-detection patterns above instead.

Port: the runner uses port 8080 by default (ENV PORT=8080 in the runner Dockerfile). Your application must listen on $PORT (or hardcode 8080).

Custom Dockerfile: a custom Dockerfile.osc is only needed when auto-detection cannot handle your startup requirements (for example, a non-standard entry point name or a multi-stage build). For standard Flask and FastAPI apps, auto-detection works without any extra files.

Minimal Flask example

This example requires no Procfile, no Dockerfile, and no extra configuration:

myapp/
├── app.py
└── requirements.txt

# app.py
import os
from flask import Flask

app = Flask(__name__)

@app.route('/')
def index():
    return 'Hello from Python Runner!'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=int(os.environ.get('PORT', 8080)))

# requirements.txt
flask
gunicorn

The runner detects gunicorn in requirements.txt and app.py, then starts the app with python -m gunicorn app:app --bind 0.0.0.0:8080.

Minimal FastAPI example

myapi/
├── main.py
└── requirements.txt

# main.py
import os
from fastapi import FastAPI

app = FastAPI()

@app.get('/')
def root():
    return {'message': 'Hello from Python Runner!'}

# requirements.txt
fastapi
uvicorn[standard]

The runner detects uvicorn in requirements.txt and main.py, then starts the app with python -m uvicorn main:app --host 0.0.0.0 --port 8080.

Application requirements

To summarise, OSC expects your Python application to:

  1. Include a requirements.txt at the repository root listing all dependencies.
  2. Listen on port 8080 (or read from the PORT environment variable).
  3. Use a supported entry point name (app.py, wsgi.py, or main.py) so auto-detection can locate your app object.

Do not add a Procfile — it will be silently ignored by the runner.

Using a private GitHub repository

  1. Create a GitHub personal access token with repo scope.
  2. Go to Python Runner → Service Secrets → New Secret. Name it (e.g. githubtoken) and paste the token.
  3. When creating the instance, set SourceUrl to your private repository URL and GitHubToken to {{secrets.githubtoken}}.

Using Application Config Service

To inject runtime configuration as environment variables, create an Application Config Service instance first, add your key-value pairs, and set the ConfigService field to the name of that instance when creating the Python Runner. OSC loads the config values as environment variables before starting your application.

Source code from S3

Package your project as a zip file:

cd myproject && zip -r ../myproject.zip ./

Upload to your S3 bucket, then set SourceUrl to s3://mybucket/myproject.zip and provide AwsAccessKeyId, AwsSecretAccessKey, and AwsRegion (or S3EndpointUrl for MinIO).

CLI usage

osc create eyevinn-python-runner myapp \
  -o SourceUrl="https://github.com/myorg/myapp"

With a private repository:

osc create eyevinn-python-runner myapp \
  -o SourceUrl="https://github.com/myorg/myapp" \
  -o GitHubToken="{{secrets.githubtoken}}"

Resources