Service: Python Runner - EyevinnOSC/community GitHub Wiki

Python Runner

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.

What it can do

  • 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 custom Dockerfile.osc (direct service instances).

Creating an instance

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.

Options

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.

Application Config Service options

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.

Using the instance

How auto-detection works

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
  • gunicorn alone, without flask and without a config file, does not start Gunicorn; the runner falls through to plain Python.
  • FastAPI and Starlette apps use uvicorn directly, even if gunicorn is 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.py or main.py).
  • A Procfile is not supported and is silently ignored.
  • The port is 8080 by default (ENV PORT=8080); listen on $PORT.

Custom Dockerfile.osc

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).

Configuring Gunicorn

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.

Minimal Flask example

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.

Minimal FastAPI example

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.

Source code from S3

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).

Application Config Service

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.

System dependencies (setup.sh)

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/*

Runtime identity

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.

CLI

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}}"

Limitations

  • Procfile is ignored.
  • setup.sh cannot install build-time dependencies for wheels.
  • Dockerfile.osc is read only for direct service instances, not My Apps.

Resources

⚠️ **GitHub.com Fallback** ⚠️