/litestar-deployment

name: litestar-deployment
description: "Use when working with Dockerfile, compose, Railway, Cloud Run, GKE, systemd, Kubernetes, Terraform, deploy scripts, or granian/litestar run at runtime. Not for packaging artifacts."

Litestar Deployment

Production deployment patterns for Litestar ASGI applications across Docker, Railway, Kubernetes/GKE, Cloud Run, and systemd. Covers multi-stage Dockerfiles, distroless images, asset pipelines, worker containers, and health-check integration.

All deployment paths use **Granian** (via `litestar-granian`) as the ASGI server, **uv** for Python package management, and **Bun** for frontend asset builds.

**Build vs. deploy split:** this skill is about **running** Litestar artifacts in production. For **producing** those artifacts — wheel bundling with embedded Vite assets, PyApp onefile binaries, GitHub Actions CI/release pipelines — see [litestar-build](../litestar-build/SKILL.md).

Code Style Rules

• `from __future__ import annotations` is allowed in consumer-app modules (Dockerfiles, deploy scripts, settings).
• All Python samples use PEP 604 unions (`T | None`).
• Granian over uvicorn in every CMD/entrypoint. Use `litestar run` (which delegates to Granian when `litestar-granian` is installed).
• Environment-driven configuration via `@dataclass` settings — never hardcode secrets or connection strings.
• Shell scripts follow Google Shell Style Guide (set -euo pipefail, quoted variables).

Quick Reference

| Target | Reference | Key File | | --- | --- | --- | | Litestar App & Cloud IAP | [references/litestar-app.md](references/litestar-app.md) | `asgi.py`, IAP middleware | | Docker (standard multi-stage) | [references/docker-standard.md](references/docker-standard.md) | `Dockerfile` | | Docker (distroless production) | [references/docker-distroless.md](references/docker-distroless.md) | `Dockerfile.distroless` | | Background worker container (`litestar-saq` / `litestar-queues`) | [references/docker-workers.md](references/docker-workers.md) | `Dockerfile.worker` | | Docker Compose (app + infra) | [references/docker-compose.md](references/docker-compose.md) | `docker-compose.yml` | | Railway | [references/railway.md](references/railway.md) | `railway.app.json` | | Kubernetes / GKE | [references/kubernetes.md](references/kubernetes.md) | `deploy.py`, templates/ | | Cloud Run (Services & Jobs) | [references/cloud-run.md](references/cloud-run.md) | `service.yaml` | | systemd native | [references/systemd.md](references/systemd.md) | `litestar.service` |

Dockerfile CMD (all variants)

# Web server (Granian via litestar-granian)
ENTRYPOINT ["tini", "--"]
CMD ["litestar", "run", "--host", "0.0.0.0", "--port", "8000"]

# Background worker — Option A: litestar-saq (separate container)
ENTRYPOINT ["tini", "--"]
CMD ["litestar", "workers", "run"]

# Background worker — Option B: litestar-queues (separate container)
ENTRYPOINT ["tini", "--"]
CMD ["litestar", "queues", "run", "--max-concurrency", "10", "--drain-timeout", "30.0"]

# Database migrator — Option A: advanced-alchemy (one-off job / init container)
ENTRYPOINT ["tini", "--"]
CMD ["litestar", "database", "upgrade", "--no-prompt"]

# Database migrator — Option B: sqlspec (one-off job / init container)
ENTRYPOINT ["tini", "--"]
CMD ["litestar", "db", "upgrade", "--no-prompt"]

Environment variables (required in every target)

LITESTAR_APP="app.server.asgi:create_app"   # app discovery
DATABASE_URL="postgresql+asyncpg://..."       # async driver
SAQ_REDIS_URL="redis://cache:6379/0"         # worker queue (when using litestar-saq)
LITESTAR_TRUSTED_PROXIES="*"                 # proxy header trust behind Cloud Run / Railway / ingress
SECRET_KEY="..."                              # session signing

<workflow>

Workflow

Step 1: Choose deployment target

Docker Compose for local/staging. Railway for rapid PaaS. GKE/K8s for production at scale. Cloud Run for serverless containers (and Cloud Run Jobs for `litestar-queues` one-shot tasks). systemd for bare-metal.

Step 2: Write the Dockerfile

Start from `Dockerfile.distroless` for production (preferred). Use standard multi-stage for environments that need a shell. Use `Dockerfile.dev` for local Docker development. Always pin `ARG PYTHON_VERSION=3.13`.

Step 3: Build frontend assets inside Docker

Copy Bun lockfiles first (layer caching), install JS deps, then `bun run build` and `uv run litestar assets build` (or `uv run app assets build` when a custom `[project.scripts]` CLI entry point is defined). Assets must be in the wheel before `uv build --wheel --clear`.

Step 4: Create separate worker image (Match-Your-Stack)

Background workers use the same build stages as the web image but a different `CMD`, no exposed HTTP port, and a longer termination grace period (`120s`):

• **`litestar-saq`**: run `litestar workers run` (or `app workers run`) with `SAQ_USE_SERVER_LIFESPAN=false`.
• **`litestar-queues`**: run `litestar queues run --max-concurrency 10 --drain-timeout 30.0` for persistent task queues (SQLSpec, Advanced Alchemy, Redis/Valkey), `litestar queues run-consumer --backend <kafka|pubsub|rabbitmq|sqs>` for stream consumers, `CloudTasksExecutionConfig` (`WorkerConfig(placement="external")`) for zero-worker serverless push delivery on Cloud Run Services, or `litestar queues run-task` inside isolated Cloud Run Jobs (`CloudRunExecutionConfig`).

Step 5: Set up CI/CD

Build images in CI, push to registry, deploy via `railway up`, `gcloud run deploy`, or `kubectl apply`. Tag images with git SHA for production — never deploy `latest` to prod.

Step 6: Configure health checks and monitoring

Expose `/health` on the API container. K8s uses startupProbe + livenessProbe + readinessProbe on `/health:8000`. Cloud Run and Railway use the same endpoint for readiness.

</workflow>

<guardrails>

Guardrails

• **Distroless for production, slim for dev.** Distroless (`gcr.io/distroless/cc-debian1