Configuration

Configure your self-hosted Runtime instance with environment variables.

Required Variables

These must be set for Runtime to function:

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection	`postgresql://user:pass@host:5432/runtm`
`REDIS_URL`	Redis connection	`redis://localhost:6379/0`
`FLY_API_TOKEN`	Fly.io deploy token	`FlyV1 xxx...`
`RUNTM_API_SECRET`	API authentication secret	Random 32+ char string

All Variables

Database

Variable	Default	Description
`DATABASE_URL`	Required	PostgreSQL connection string
`DATABASE_POOL_SIZE`	`5`	Connection pool size
`DATABASE_MAX_OVERFLOW`	`10`	Max overflow connections

Redis

Variable	Default	Description
`REDIS_URL`	Required	Redis connection string
`RQ_QUEUE_NAME`	`runtm`	Job queue name

API Server

Variable	Default	Description
`RUNTM_API_SECRET`	Required	Auth secret (32+ chars)
`API_HOST`	`0.0.0.0`	Bind host
`API_PORT`	`8000`	Bind port
`CORS_ORIGINS`	`*`	Allowed CORS origins
`LOG_LEVEL`	`INFO`	Logging level

Worker

Variable	Default	Description
`FLY_API_TOKEN`	Required	Fly.io deploy token
`ARTIFACT_STORAGE_PATH`	`/tmp/artifacts`	Local artifact storage
`BUILD_TIMEOUT_SECONDS`	`2400`	Max build time (covers the whole remote build + rolling update)
`DEPLOY_TIMEOUT_SECONDS`	`600`	Max deploy time

Token Security

Variable	Default	Description
`TOKEN_PEPPER_V1`	Required	Pepper for token hashing
`CURRENT_PEPPER_VERSION`	`1`	Active pepper version
`PEPPER_MIGRATION_VERSIONS`	-	Versions during rotation

Custom Domains (Optional)

Variable	Default	Description
`DNS_ENABLED`	`false`	Enable auto DNS management
`DNS_PROVIDER`	-	DNS provider (`cloudflare`)
`CLOUDFLARE_API_TOKEN`	-	Cloudflare API token
`CLOUDFLARE_ZONE_ID`	-	Cloudflare zone ID
`BASE_DOMAIN`	-	Base domain for subdomains

Limits (Optional)

Variable	Default	Description
`MAX_ARTIFACT_SIZE_MB`	`20`	Max upload size
`MAX_DEPLOYMENTS_PER_HOUR`	`10`	Rate limit per token
`MAX_CONCURRENT_DEPLOYS`	`5`	Per-tenant limit

Example Configuration

Development (.env)

# Database
DATABASE_URL=postgresql://runtm:runtm@localhost:5432/runtm

# Redis
REDIS_URL=redis://localhost:6379/0

# API
RUNTM_API_SECRET=dev-secret-change-in-production-123

# Worker
FLY_API_TOKEN=FlyV1_your_token_here
ARTIFACT_STORAGE_PATH=/tmp/runtm-artifacts

# Token Security
TOKEN_PEPPER_V1=dev-pepper-change-in-production-456

# Logging
LOG_LEVEL=DEBUG

Production (.env)

# Database (managed PostgreSQL)
DATABASE_URL=postgresql://runtm:[email protected]:5432/runtm?sslmode=require
DATABASE_POOL_SIZE=10
DATABASE_MAX_OVERFLOW=20

# Redis (managed Redis)
REDIS_URL=rediss://user:[email protected]:6379/0

# API
RUNTM_API_SECRET=generated-64-char-random-string
API_HOST=0.0.0.0
API_PORT=8000
CORS_ORIGINS=https://app.runtm.example.com

# Worker
FLY_API_TOKEN=FlyV1_production_token
ARTIFACT_STORAGE_PATH=/data/artifacts
BUILD_TIMEOUT_SECONDS=2400
DEPLOY_TIMEOUT_SECONDS=600

# Token Security
TOKEN_PEPPER_V1=generated-32-char-pepper

# Custom Domains (optional)
DNS_ENABLED=true
DNS_PROVIDER=cloudflare
CLOUDFLARE_API_TOKEN=your_cf_token
CLOUDFLARE_ZONE_ID=your_zone_id
BASE_DOMAIN=apps.example.com

# Logging
LOG_LEVEL=INFO

Generating Secrets

API Secret

openssl rand -base64 48

Token Pepper

openssl rand -base64 24

Security Considerations

Never commit .env files to version control. Add .env to .gitignore.

Best Practices

Use strong secrets

Generate all secrets with openssl rand:

openssl rand -base64 48

Use TLS in production

Set ?sslmode=require on DATABASE_URL. Use rediss:// (with SSL) for Redis.

Restrict CORS origins

In production, set CORS_ORIGINS to your specific domains.

Secure the Fly.io token

Create a deploy-only token, not a full access token:

fly tokens create deploy -n runtm-worker

Pepper Rotation

To rotate the token pepper (e.g., after a breach):

Add new pepper:

TOKEN_PEPPER_V2=new-pepper-value
PEPPER_MIGRATION_VERSIONS=1,2

Wait for old tokens to expire or be revoked

Remove old pepper:

CURRENT_PEPPER_VERSION=2
# Remove TOKEN_PEPPER_V1
# Remove PEPPER_MIGRATION_VERSIONS

See admin commands for the guided rotation process.

Validating Configuration

After setting up, verify your configuration:

# Check API health
curl http://localhost:8000/health

# Check database connection
docker compose exec api python -c "from runtm_api.db import engine; print(engine.execute('SELECT 1').scalar())"

# Check Redis connection
docker compose exec api python -c "from redis import Redis; print(Redis.from_url('$REDIS_URL').ping())"

Open Source

Guides

Features

OSS Templates

CLI Reference

Self-Hosting

OSS API

Deployments

Logs

Domains

User

Configuration

Configuration

Required Variables

All Variables

Database

Redis

API Server

Worker

Token Security

Custom Domains (Optional)

Limits (Optional)

Example Configuration

Development (.env)

Production (.env)

Generating Secrets

API Secret

Token Pepper

Security Considerations

Best Practices

Pepper Rotation

Validating Configuration

Next Steps

Admin Commands

Docker Compose

​Configuration

​Required Variables

​All Variables

​Database

​Redis

​API Server

​Worker

​Token Security

​Custom Domains (Optional)

​Limits (Optional)

​Example Configuration

​Development (.env)

​Production (.env)

​Generating Secrets

​API Secret

​Token Pepper

​Security Considerations

​Best Practices

​Pepper Rotation

​Validating Configuration

​Next Steps

Admin Commands

Docker Compose

Configuration

Required Variables

All Variables

Database

Redis

API Server

Worker

Token Security

Custom Domains (Optional)

Limits (Optional)

Example Configuration

Development (.env)

Production (.env)

Generating Secrets

API Secret

Token Pepper

Security Considerations

Best Practices

Pepper Rotation

Validating Configuration

Next Steps