Production Deployment

What this page is

A Chirp app deploys as a single ASGI app served by Pounce, Chirp's production server. There is one server and one app — no separate API tier, no worker queue to stand up.

In development you run one auto-reloading worker. In production you turn on multiple workers, metrics, and rate limiting, wire the secure-by-default stack, and gate the deploy on a contract preflight. This page is the operator's path from a working app to a hardened launch.

Reach for it when you are shipping. For what the contract checks actually enforce, see the contract category reference; for the full server-flag and freeze map, see the [deployment overview].

Configure the app

The only difference between dev and prod isAppConfig. Pick the form you run with — all three start the same app.

from chirp import App, AppConfig

app = App(AppConfig(debug=True))

@app.route("/")
def index():
    return "Hello!"

app.run()  # single worker, auto-reload

import os
from chirp import App, AppConfig

config = AppConfig(
    env="production",
    debug=False,
    secret_key=os.environ["CHIRP_SECRET_KEY"],
    workers=4,
    metrics_enabled=True,
    rate_limit_enabled=True,
)

app = App(config=config)

@app.route("/")
def index():
    return "Hello, production!"

app.run()  # multi-worker

chirp run myapp:app --production --workers 4 --metrics --rate-limit

AppConfig.from_env() reads CHIRP_*environment variables for you, so you can keep config out of code entirely:

config = AppConfig.from_env(env="production", worker_mode="async")

Deploy

What the server gives you

Pounce handles these for every Chirp app, no configuration required:

• HTTP and WebSocket compression — ordinary responses are compressed;text/event-streamis left uncompressed so SSE events are not buffered behind a compression window.
• HTTP/2 with multiplexed streams (enabled when you setssl_certfile/ssl_keyfile).
• Graceful shutdown — active requests finish onSIGTERM.
• Zero-downtime reload —kill -SIGUSR1swaps in new code.
• OpenTelemetry distributed tracing (configurable).

These you opt into throughAppConfigor CLI flags:

For everyAppConfigfield, see Configuration.

Health and readiness probes

Chirp auto-mounts two ops endpoints — no hand-wiring, present on every app including thechirp new --minimalscaffold:

• /health (liveness) — always returns plain 200 ok. Wire it to a Kubernetes livenessProbe: if it stops answering, the orchestrator restarts the pod.
• /ready (readiness) — returns 503 until startup completes (db connect, migrations, and every @app.on_startup hook), then runs every registered readiness check. If a check fails it returns 503 plus the failure list; otherwise plain 200 ready. Wire it to a readinessProbeso the pod is pulled from the load-balancer rotation while it is starting up, draining on shutdown, or a dependency is down.

Both probes bypass the secure middleware stack (Session/CSRF/SecurityHeaders) and the commit teardown — they run no user handler, set no cookie, and never touch the session — and return plain200/503text outside Chirp's return-type negotiation.

Change the paths withAppConfig(health_path=..., ready_path=...) or CHIRP_HEALTH_PATH / CHIRP_READY_PATH. A user route claiming a probe path wins (the probe steps aside); app.check() flags the collision as a deploy_healthERROR so it never happens silently.

Register dependency checks before freeze:

from chirp import HealthCheck

app.add_health_check(HealthCheck("cache", check=ping_cache))   # sync or async

When a database is wired, Chirp auto-includes a Database.probe()-backed check (a SELECT 1 on a fresh pooled connection, never the request session), so /readyreflects DB connectivity for free.

A Kubernetes deployment wires them like this:

livenessProbe:
  httpGet: { path: /health, port: 8000 }
readinessProbe:
  httpGet: { path: /ready, port: 8000 }

Wire the secure-by-default stack

A production app with any mutating route must wireSessionMiddleware → CSRFMiddleware → SecurityHeadersMiddleware. Chirp does not inject these for you; chirp check --deploy fails when they are missing in production. Every chirp newscaffold wires them out of the box.

The full stack, ordering rules, and CSRF form patterns live on Auth Hardening — wire it before you go live.

Run behind a reverse proxy

When Chirp runs behind a proxy (nginx, a load balancer, a CDN, a platform router), the socket peer is the proxy, not the end user. The real client IP arrives in theX-Forwarded-For header. Two AppConfigfields control how that header is trusted:

config = AppConfig(
    env="production",
    secret_key=os.environ["CHIRP_SECRET_KEY"],
    trusted_proxies=("10.0.0.1", "10.0.0.2"),  # your proxy peers
    forwarded_for_trusted_hops=1,               # one proxy in front of the app
)

forwarded_for_trusted_hops only takes effect when the direct peer is one of your trusted_proxies. To ignore X-Forwarded-For, leave trusted_proxies empty — do not set the hop count to 0. It must be >= 1, and AppConfig raises ConfigurationErrorat construction otherwise.

Realtime workloads

SSE is Chirp's realtime contract. Pounce intentionally avoids compressingtext/event-stream responses so event delivery is not buffered behind a compression window. Use worker_mode="async"for apps with long-lived SSE connections.

Demo tier vs production tier

Some examples (notably Lucky Cat) pinworkers=1and keep wallet, trades, notifications, and the signal bus in process memory so they clone-and-run offline. That is a demo boundary, not a framework ceiling.

Multi-worker production needs both external state and a shared backplane so /_chirp/live connections and app.emitfan-out stay coherent across processes. See the Lucky CatDESIGN.md §7 and backplane.pyseam for the worked example.

Advanced

config = AppConfig(debug=False, workers=4, worker_mode="async")

pounce config schema --output-format toml-template   # generate a starting file
pounce config schema --output-format json            # for tooling
pounce config show --config pounce.toml               # inspect the resolved config
pounce serve --app myapp:app --config pounce.toml

import socket

def is_port_in_use(host: str, port: int) -> bool:
    """Return True if another process is actively listening on host:port."""
    try:
        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
            s.bind((host, port))
            return False
    except OSError:
        return True