Skip to content
Tutorials Center
My learning

Topics

Lesson 41 of 50 ยท Testing and production

Deployment

Take a FastAPI app to production: choose uvicorn or gunicorn workers, build a Docker image, put a reverse proxy in front, add health checks and shut down cleanly.

On your laptop you start FastAPI with one command and stop it with Ctrl+C. In production the same app has to survive crashes, restarts, traffic spikes and deploys that happen while users are connected. Deployment is the set of decisions that make that possible: which server runs the code, how many processes, what sits in front of it, how the platform knows the app is healthy, and what happens when it is told to stop.

Most of this lesson is configuration rather than Python, so the files are shown read-only. The two live examples cover the parts that are Python: health endpoints and a clean shutdown. The ideas apply to any platform, from a single virtual machine to a container orchestrator.

The pieces of a deployment

A FastAPI app is an ASGI application, so it needs an ASGI server to speak HTTP. That server usually does not face the internet directly: a reverse proxy receives the traffic first, terminates HTTPS and forwards plain HTTP to your app.

flowchart LR
    U["Browser or client"] -->|HTTPS| P["Reverse proxy<br/>(nginx, Caddy, load balancer)"]
    P -->|HTTP| W1["uvicorn worker 1"]
    P -->|HTTP| W2["uvicorn worker 2"]
    W1 --> D[("Database")]
    W2 --> D

HTTPS ends at the proxy; each worker is one process running your app.

Production checklist

ASGI server uvicorn runs the app.
Reverse proxy HTTPS, buffering, limits.
Health checks The platform asks "are you alive?"
Config from env No secrets in the image.
1 / 2

Running the server: uvicorn, workers and the FastAPI CLI

uvicorn is the standard ASGI server. A single uvicorn process runs one event loop on one CPU core, so to use several cores you run several processes (workers).

Terminal
# one process, good for development and for containers that scale by replicas
uvicorn app.main:app --host 0.0.0.0 --port 8000

# several worker processes on one machine
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

# development only: restart on file changes
uvicorn app.main:app --reload

app.main:app means "module app/main.py, variable app". The fastapi command from fastapi[standard] is a thin wrapper: fastapi dev runs with reload for development, and fastapi run is the production mode (no reload, listens on all interfaces, and can take --workers).

uvicorn alone or behind gunicorn? Gunicorn is a process manager that can supervise uvicorn workers (gunicorn -k uvicorn.workers.UvicornWorker -w 4 app.main:app). Older guides recommend it because it restarts crashed workers. Today uvicorn's own --workers supervises its children too, and many teams run one process per container and let Docker or Kubernetes provide restarts and scaling. Choose what your platform already does:

Situation Typical choice
Containers on Kubernetes or a similar orchestrator One uvicorn process per container, scale with replicas
One virtual machine with systemd uvicorn --workers N or gunicorn with uvicorn workers
Quick demo fastapi run or plain uvicorn

A common starting point for the worker count is the number of CPU cores. Remember that every worker has its own memory, caches and database pool (Performance and caching), so more workers means more connections to the database.

Plain def endpoints also run in a threadpool inside each worker, which is why a single worker can still serve many concurrent requests (async def vs def endpoints).

A Docker image

A container packages your code and its dependencies so that it runs the same everywhere. A small, cache-friendly Dockerfile for a FastAPI app (read-only; see the Docker tutorial for every instruction):

DOCKERFILE
FROM python:3.13-slim

ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
WORKDIR /app

# Install dependencies first: this layer is cached until requirements change
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app ./app

# Do not run as root
RUN useradd --create-home appuser
USER appuser

EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=3s CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Notes on the choices: the exec form of CMD (a JSON list) makes uvicorn process number 1, so it receives the stop signal directly. Copying requirements.txt before the code keeps rebuilds fast. A non-root user limits the damage of a compromise. More habits are collected in Dockerfile best practices, and Docker's own health check is explained in Healthcheck.

Behind a reverse proxy, with HTTPS

Let a proxy (nginx, Caddy, Traefik, or your cloud's load balancer) handle certificates, slow clients and static files. Your app then sees plain HTTP from the proxy, so it must be told the original scheme and client address. Uvicorn can read the standard X-Forwarded-* headers, but only from proxies you trust:

Terminal
uvicorn app.main:app --proxy-headers --forwarded-allow-ips="10.0.0.5"

Without this, request.url shows http:// instead of https://, and redirects or generated links point to the wrong address. Never set --forwarded-allow-ips="*" when the app is reachable directly, because any client could then forge its own address. A minimal nginx location, also read-only:

NGINX
location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Use HTTPS everywhere. Free certificates from Let's Encrypt renew automatically with Caddy or certbot, and managed platforms add TLS for you. If the app runs on a plain Linux server, systemd and package management keep the process alive across reboots.

Health checks

An orchestrator or load balancer needs a cheap URL that answers "should I send traffic here?". Two endpoints are common:

  • Liveness (/health): the process is running and can answer. It must not call the database; a database outage should not make the platform kill and restart healthy app processes.
  • Readiness (/ready): the app can do useful work, so it checks the things it needs, such as the database. While it fails, the instance is taken out of rotation but not killed.
Python Liveness and readiness endpoints

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

With the database down, liveness still answers 200 while readiness answers 503, which is exactly the signal a load balancer needs: stop routing here, but do not restart the process.

Configuration and secrets

Follow the twelve-factor idea: the same image runs in every environment, and environment variables carry what differs (database URL, secret keys, allowed origins). Never bake secrets into the image or commit them to git. Load them with the settings pattern from Settings and configuration, and fail at startup when a required value is missing, so a misconfigured release never goes live.

Terminal
docker run -p 8000:8000 \
  -e DATABASE_URL="postgresql://app:secret@db/app" \
  -e SECRET_KEY="$(cat /run/secrets/app_key)" \
  my-api:1.4.0

Graceful shutdown

On every deploy, the platform sends your process a SIGTERM ("please stop"). Uvicorn handles it well: it stops accepting new connections, waits for requests in progress to finish (up to --timeout-graceful-shutdown), runs the lifespan shutdown code and exits. If the process does not stop in time, the platform sends SIGKILL, which cannot be caught. Signals are explained in kill and signals.

For you, that means two jobs: put cleanup in the lifespan (Lifespan events and app state), and keep requests short enough to finish within the platform's grace period. Long work belongs in a queue (Background tasks).

Python What runs on shutdown

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The code after yield is what a real server runs when it receives the stop signal. Connections are returned cleanly instead of being cut off.

Deploying to Render and other platforms

You do not need to run your own server. Platform-as-a-service (PaaS) hosts such as Render, Railway, Fly.io, Heroku-style services, Google Cloud Run or Azure App Service take your code (or your Docker image), start it, give it an HTTPS address and restart it when it crashes. They all work the same way, and four ideas cover almost every one of them.

  1. A build step that installs dependencies (pip install -r requirements.txt), or a Dockerfile (the one above works unchanged).
  2. A start command that runs uvicorn.
  3. Listening on the port the platform gives you. The platform sets a PORT environment variable and routes traffic to it. Bind to host 0.0.0.0 (all interfaces), not 127.0.0.1, or the platform's router cannot reach you.
  4. Configuration through environment variables, never committed files: database URL, secret keys, allowed origins. See Settings and configuration.

The first three fit in one line: uvicorn app.main:app --host 0.0.0.0 --port $PORT. If the platform runs your command without a shell, $PORT is not expanded; a small wrapper in Python avoids that. The example below shows how the port, the number of workers and the environment come together, using only the standard library:

Python Building the start command from the environment

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Render

On Render you create a Web Service from a Git repository. In the dashboard you fill in a build command and a start command, or you commit a blueprint file, render.yaml, so the setup lives in version control (read-only, check Render's documentation for current options and plans):

YAML
services:
  - type: web
    name: my-api
    runtime: python
    buildCommand: pip install -r requirements.txt
    startCommand: uvicorn app.main:app --host 0.0.0.0 --port $PORT
    healthCheckPath: /health
    envVars:
      - key: PYTHON_VERSION          # use a full version number such as 3.13.5
        value: 3.13.5
      - key: SECRET_KEY
        generateValue: true          # Render creates a random value
      - key: DATABASE_URL
        fromDatabase:
          name: my-db
          property: connectionString

databases:
  - name: my-db

The healthCheckPath is the health endpoint from the "Health checks" section above: Render calls it and only sends traffic once it answers 200. Pushing to the connected branch redeploys automatically. Free plans typically "spin down" after a period of inactivity, so the first request after a pause is slow; use a paid plan for anything users depend on.

If you prefer containers, choose Docker as the runtime instead. Render builds your Dockerfile and provides PORT, so use CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8000}"] (the sh -c form makes the variable expand; start with exec uvicorn ... in the shell if you want uvicorn to be process 1).

Railway, Heroku-style hosts and Fly.io

  • Railway detects a Python project, installs requirements.txt (or pyproject.toml) and needs one start command, set in the dashboard or in a Procfile: web: uvicorn app.main:app --host 0.0.0.0 --port $PORT. It injects PORT and lets you add a PostgreSQL service whose connection string appears as a variable you reference.
  • Heroku-style buildpacks read the same Procfile and runtime.txt/.python-version for the Python version, and release-phase commands are a good place to run migrations.
  • Fly.io runs your Docker image on small virtual machines close to your users. fly launch inspects the project and writes a fly.toml; the key line is the internal port your container listens on. Deploy with fly deploy, set secrets with fly secrets set SECRET_KEY=....
TOML
# fly.toml (read-only, abridged)
app = "my-api"

[http_service]
  internal_port = 8000        # the port your uvicorn listens on
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true
  min_machines_running = 1
  • Google Cloud Run, Azure App Service and AWS App Runner accept a container image and give it PORT (Cloud Run uses 8080 by default). The Dockerfile from this lesson is all you need, plus the same environment-variable rules.

Platforms change plans, free tiers and file names often. Treat the snippets as the shape of the setup and confirm exact keys in the provider's current documentation. The ideas (build step, start command, PORT, environment variables, health check) stay the same.

Platform checklist

  • Bind to 0.0.0.0 and the platform's PORT.
  • Keep secrets in the platform's environment settings, never in the repository.
  • Give the database URL through an environment variable and run migrations as a separate release step (Migrations with Alembic).
  • Add a health check path and make sure it does not need a login.
  • Remember that most platforms have an ephemeral file system: files written at runtime vanish on redeploy. Store uploads in object storage and data in a database.
  • Use --proxy-headers (or the platform's recommended flag) so request.url shows https.
  • Set the workers/replicas to match the plan's memory.

Before you go live

  • Run at least two instances so a deploy or crash never leaves you with zero.
  • Turn off debug output and the auto-reload flag; consider disabling /docs for private APIs (FastAPI(docs_url=None, redoc_url=None, openapi_url=None)).
  • Set CORS to the exact origins you need (Middleware and CORS).
  • Log to standard output as structured lines; the platform collects them.
  • Pin dependency versions and rebuild the image regularly for security fixes.
  • Run database migrations as a separate, explicit step of the deploy, not inside every worker's startup.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why do you usually put a reverse proxy in front of uvicorn?

    The proxy handles TLS, buffering and limits and routes traffic to one or more app workers.
  2. 2. What is the difference between a liveness and a readiness check?

    A failing liveness check gets the process restarted; a failing readiness check only removes the instance from rotation.
  3. 3. Why use the exec form CMD ["uvicorn", ...] in a Dockerfile?

    The shell form wraps the command in sh -c, and the shell may not forward the stop signal to your server.
  4. 4. Where should secrets such as the database password live?

    The same image should run everywhere; configuration and secrets are injected at run time and never baked in.

Summary

  • A FastAPI app runs on an ASGI server (uvicorn), usually behind a reverse proxy that handles HTTPS.
  • One process uses one core: scale with --workers, or with container replicas, and remember each worker has its own memory and database pool.
  • Build a small image, install dependencies before copying code, use the exec form of CMD and run as a non-root user.
  • Trust X-Forwarded-* headers only from your own proxy.
  • Offer /health (liveness) and /ready (readiness) endpoints.
  • Read configuration from the environment, and put cleanup in the lifespan so SIGTERM shuts the app down gracefully.

Time to build something real: start with the Project: To-do API.