Skip to content

Deployment

This guide covers everything you need to deploy a Cello application in production: server configuration, worker processes, Docker packaging, TLS/HTTPS, reverse proxy setup, health checks, and monitoring.

Production Settings

Command-Line Options

python app.py \
  --host 0.0.0.0 \
  --port 8000 \
  --env production \
  --workers 4 \
  --no-logs
Flag Default Description
--host 127.0.0.1 Bind address. Use 0.0.0.0 in containers.
--port 8000 Listening port
--env development Set to production to disable debug mode
--workers CPU count Number of worker threads
--debug Off in prod Enable verbose error pages
--no-logs Off Disable request logging

Programmatic Configuration

app.run(
    host="0.0.0.0",
    port=8000,
    env="production",
    workers=8,
    logs=False,
)

Workers Configuration

Cello uses Tokio worker threads inside Rust. The --workers flag controls how many OS threads handle requests concurrently.

Rule of thumb: Set workers to the number of CPU cores.

python app.py --workers $(nproc)

For I/O-bound workloads (database queries, external API calls), you can increase workers to 2x the CPU count.

Environment Variables

Use environment variables for configuration that changes between environments.

export CELLO_ENV=production
export DATABASE_URL=postgresql://user:pass@db:5432/app
export JWT_SECRET=$(python -c "import secrets; print(secrets.token_urlsafe(64))")
export WORKERS=4

Read them in your application:

import os

app.run(
    host=os.environ.get("HOST", "0.0.0.0"),
    port=int(os.environ.get("PORT", "8000")),
    env=os.environ.get("CELLO_ENV", "production"),
    workers=int(os.environ.get("WORKERS", "4")),
)

TLS / HTTPS

Cello supports TLS natively through Rustls (no OpenSSL dependency).

from cello import App, TlsConfig

app = App()

tls = TlsConfig(
    cert_path="/etc/ssl/certs/server.crt",
    key_path="/etc/ssl/private/server.key",
)

app.run(host="0.0.0.0", port=443, tls=tls)

For Let's Encrypt certificates, point cert_path and key_path to the fullchain and private key files.

Docker Deployment

Dockerfile

# Build stage
FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Runtime stage
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY . .

EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health/live')"

CMD ["python", "app.py", "--host", "0.0.0.0", "--env", "production", "--workers", "4"]

docker-compose.yml

version: "3.8"
services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      CELLO_ENV: production
      DATABASE_URL: postgresql://user:pass@db:5432/app
      JWT_SECRET: change-me-in-production
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Reverse Proxy (nginx)

In production, place nginx in front of Cello for TLS termination, static files, and load balancing.

nginx.conf

upstream cello {
    server 127.0.0.1:8000;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate     /etc/ssl/certs/fullchain.pem;
    ssl_certificate_key /etc/ssl/private/privkey.pem;

    location / {
        proxy_pass http://cello;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /ws/ {
        proxy_pass http://cello;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Note

The /ws/ location block is required for WebSocket connections. Without the Upgrade headers, WebSocket handshakes fail.

Health Checks

Enable health check endpoints for orchestrators like Kubernetes and Docker.

from cello import HealthCheckConfig

app.enable_health_checks(HealthCheckConfig(
    base_path="/health",
    include_system_info=True,
))

This registers:

Endpoint Purpose
GET /health/live Liveness probe -- is the process alive?
GET /health/ready Readiness probe -- is it ready for traffic?
GET /health/startup Startup probe -- has initialization completed?
GET /health Full health report with system info

Monitoring

Prometheus Metrics

app.enable_prometheus(endpoint="/metrics")

Scrape /metrics from your Prometheus server. The endpoint exposes request count, latency histograms, and error rates.

OpenTelemetry

For distributed tracing across microservices:

from cello import OpenTelemetryConfig

app.enable_telemetry(OpenTelemetryConfig(
    service_name="my-service",
    otlp_endpoint="http://collector:4317",
))

See the OpenTelemetry guide for details.

Pre-Deployment Checklist

  • Set --env production
  • Configure --workers based on CPU count
  • Enable TLS (directly or via reverse proxy)
  • Set JWT_SECRET and other secrets via environment variables
  • Enable health checks
  • Enable Prometheus metrics
  • Enable rate limiting on public endpoints
  • Enable security headers
  • Test with production-like load before going live
  • Set up log aggregation (stdout logs are collected by Docker/K8s)

Next Steps