Service: Python Runner - EyevinnOSC/community GitHub Wiki
Python Runner (serviceId eyevinn-python-runner) deploys a Python web application directly from a GitHub repository (or an S3 zip archive) and runs it as a managed service. OSC clones the source, installs dependencies from requirements.txt and starts the application automatically. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance. License: MIT. Source: Eyevinn/python-runner.
- Run Flask (with Gunicorn), FastAPI/Starlette (with uvicorn) or plain Python applications, with framework auto-detection.
- Take source from a public or private GitHub repository (optionally a branch) or from a zipped project in S3 or S3-compatible storage such as MinIO.
- Inject environment variables at startup from an Application Config Service instance.
- Install OS-level packages with a
setup.sh(My App deployments) or a customDockerfile.osc(direct service instances).
Call create-service-instance with serviceId: "eyevinn-python-runner". The instance name must be alphanumeric and at most 20 characters. No other OSC service is required; an Application Config Service instance (eyevinn-app-config-svc) is only needed to inject environment variables, and it must be running first. Your app needs a requirements.txt at the repository root and must listen on $PORT (default 8080).
{ "name": "myapp", "SourceUrl": "https://github.com/myorg/myapp" }Private repository, with the token stored first via create-service-secret (serviceId eyevinn-python-runner, name githubtoken):
{ "name": "myapp", "SourceUrl": "https://github.com/myorg/myapp", "GitHubToken": "{{secrets.githubtoken}}" }Verify with wait-for-service-ready or get-instance-status; describe-service-instance returns the URL and get-logs-for-instance shows clone, install and run output.
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Alphanumeric, at most 20 characters. |
| SourceUrl | Yes | string | Where the application source is. Either a GitHub repository URL (https://github.com/org/repo, append #branch for a specific branch) or an S3 URL to a zipped application (s3://bucket/app.zip). |
| GitHubToken | No | string, sensitive | GitHub personal access token (repo scope) for private repositories. Not needed for public repositories or S3 sources. |
| AwsAccessKeyId | No | string, sensitive | Access key ID for S3 or S3-compatible storage (AWS S3, MinIO). Needed when the source is S3. |
| AwsSecretAccessKey | No | string, sensitive | Secret access key; pair it with AwsAccessKeyId. Needed when the source is S3. |
| AwsRegion | No | string | Region of the S3 bucket. May not be needed for S3-compatible services with a custom endpoint. |
| S3EndpointUrl | No | string | Custom endpoint for S3-compatible storage other than AWS S3, for example http://minio:9000. |
| OscAccessToken | No | string, sensitive | OSC personal access token, used for the OSC config service integration and by applications that call other OSC services. |
| ConfigService | No | string | URL of the config service endpoint (an Application Config Service instance) from which environment variables are loaded at startup. Used together with OscAccessToken. |
| ConfigApiKey | No | string, sensitive | Optional API key; when set together with OscAccessToken and ConfigService, secret parameters are decrypted before being injected as environment variables. |
| SubPath | No | string | No catalog description. The name suggests a subdirectory of the source to use. |
Sensitive options should be stored as service secrets and passed as {{secrets.NAME}}, which only works as the entire field value. Overwriting a secret does not restart a running instance.
Service eyevinn-app-config-svc (MIT), a configuration store backed by Redis or a Redis-compatible store such as Valkey (valkey-io-valkey, associated with RedisUrl). It has a Swagger API at /api/docs and a frontend for managing configuration. Create the Valkey instance first and confirm it is running.
| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. |
| RedisUrl | Yes | string, sensitive | Connection URL of the Redis-compatible store holding all configuration key/value pairs, for example redis://<ip>:<port>. |
| ParameterEncryptionKey | No | string, sensitive | Encryption key for sensitive configuration parameters stored in the service. |
| ConfigApiKey | No | string, sensitive | API key securing access to the configuration endpoints. |
The runner examines your dependencies and repository root. Rules are evaluated in this order:
| Detected condition | What the runner does |
|---|---|
flask AND gunicorn in requirements.txt
|
Runs python -m gunicorn <module>:app --bind 0.0.0.0:${PORT}
|
gunicorn in requirements.txt AND gunicorn.conf.py or gunicorn_config.py at repo root |
Runs python -m gunicorn -c <config_file> <module>:app
|
fastapi or starlette in requirements.txt (with uvicorn) |
Runs python -m uvicorn <module>:app --host 0.0.0.0 --port ${PORT}
|
| None of the above | Runs python app.py or python main.py
|
-
gunicornalone, withoutflaskand without a config file, does not start Gunicorn; the runner falls through to plain Python. - FastAPI and Starlette apps use uvicorn directly, even if
gunicornis listed. - Only
--bind(Flask path) or-c(config-file path) is passed. No workers, timeout or log-level settings are injected. - Use a supported entry point name (
app.py,wsgi.pyormain.py). - A
Procfileis not supported and is silently ignored. - The port is
8080by default (ENV PORT=8080); listen on$PORT.
Dockerfile.osc is supported only when eyevinn-python-runner is provisioned as a direct catalog service instance, and is only needed when auto-detection cannot handle your startup (a non-standard entry point, a multi-stage build). My App deployments (create-my-app) do not read Dockerfile.osc; use setup.sh instead (below).
By default Gunicorn runs with its built-in defaults (one worker, 30-second timeout). Place a gunicorn.conf.py at the repository root; it is passed with -c on both the Flask+Gunicorn and config-file paths.
import os
bind = f"0.0.0.0:{os.environ.get('PORT', '8080')}"
workers = 2
timeout = 120
accesslog = "-"
errorlog = "-"
loglevel = "info"Always read the port from the environment; a hardcoded port conflicts with the --bind the runner passes for Flask apps. workers = 2 is a starting point; each instance runs in a container with limited CPU. accesslog = "-" and errorlog = "-" send logs to stdout/stderr so they appear in the instance logs. See the Gunicorn configuration reference.
Gunicorn configuration does not apply to FastAPI and Starlette; a gunicorn.conf.py is ignored there. Configure uvicorn through a custom Dockerfile.osc (direct instance) or setup.sh (My App).
You can also pass settings with the GUNICORN_CMD_ARGS environment variable, injected from an Application Config Service instance: add the key GUNICORN_CMD_ARGS with a value such as --workers=4 --timeout=60 and set ConfigService. GUNICORN_CMD_ARGS takes precedence over the same option in gunicorn.conf.py.
Files app.py and requirements.txt (flask, gunicorn); no Procfile or Dockerfile needed.
# 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)))The runner starts it with python -m gunicorn app:app --bind 0.0.0.0:8080.
Files main.py and requirements.txt (fastapi, uvicorn[standard]).
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get('/')
def root():
return {'message': 'Hello from Python Runner!'}The runner starts it with python -m uvicorn main:app --host 0.0.0.0 --port 8080.
cd myproject && zip -r ../myproject.zip ./Upload the zip to your bucket, set SourceUrl to s3://mybucket/myproject.zip and provide AwsAccessKeyId, AwsSecretAccessKey and AwsRegion (or S3EndpointUrl for MinIO).
Create an Application Config Service instance, add key-value pairs, and set ConfigService (with OscAccessToken) on the Python Runner. The values are loaded as environment variables before the application starts.
For My App Python deployments needing OS packages such as ffmpeg, libsrt or gcc, place a setup.sh at the repository root. It runs as root at container start. With a direct service instance you can also use Dockerfile.osc.
Execution order: (1) config-service environment variables are loaded, so they are available during pip install; (2) pip install (from requirements.txt, pyproject.toml or setup.py); (3) setup.sh runs as root, no sudo needed; (4) the application starts.
setup.sh runs after pip install, so it cannot provide C headers or shared libraries that a wheel needs at compile time; use it for runtime binaries.
#!/bin/bash
set -e
apt-get update -qq
apt-get install -y --no-install-recommends ffmpeg
apt-get clean && rm -rf /var/lib/apt/lists/*Each instance pod exposes HOSTNAME (the Kubernetes pod name, stable for the pod's lifetime and shared by Gunicorn workers, changes on restart) and PORT (always 8080). Use HOSTNAME to correlate log lines from the same pod:
import os
pod_name = os.environ.get('HOSTNAME', 'unknown')There is no persistent instance ID that survives pod restarts; store your own if you need one.
osc create eyevinn-python-runner myapp \
-o SourceUrl="https://github.com/myorg/myapp"
# Private repository
osc create eyevinn-python-runner myapp \
-o SourceUrl="https://github.com/myorg/myapp" \
-o GitHubToken="{{secrets.githubtoken}}"-
Procfileis ignored. -
setup.shcannot install build-time dependencies for wheels. -
Dockerfile.oscis read only for direct service instances, not My Apps.