Docker base image for FastAPI
Start from the official Python base image (FROM python:3.14) when building a Dockerfile for FastAPI. The deprecated tiangolo/uvicorn-gunicorn-fastapi image should not be used.
FastAPI · Deployment · all subjects
deployment/docker
23 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Dockerfile working directory setup
Set the working directory to /code using WORKDIR /code. This is where the requirements.txt file and app directory will be placed.
Dockerfile Docker cache optimization
Copy requirements.txt first (before copying app code) to optimize Docker's layer caching. Since requirements don't change frequently, Docker will use the cache for the pip install step, significantly reducing build time during development. Copy app code near the end of the Dockerfile since it changes most frequently and would invalidate the cache for subsequent steps.
FastAPI Dockerfile example - multi-file project
Example Dockerfile for a FastAPI project with app directory: FROM python:3.14 WORKDIR /code COPY ./requirements.txt /code/requirements.txt RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt COPY ./app /code/app CMD ["fastapi", "run", "app/main.py", "--port", "80"] For a TLS Termination Proxy (Nginx, Traefik), add --proxy-headers: CMD ["fastapi", "run", "app/main.py", "--port", "80", "--proxy-headers"]
Dockerfile pip install options
Use pip install with --no-cache-dir and --upgrade options. The --no-cache-dir option tells pip not to save downloaded packages locally (not relevant to Docker cache). The --upgrade option tells pip to upgrade packages if already installed.
CMD instruction exec form requirement
Always use the exec form of the CMD instruction, not the shell form. Exec form: CMD ["fastapi", "run", "app/main.py", "--port", "80"]. Shell form (incorrect): CMD fastapi run app/main.py --port 80. Using exec form ensures FastAPI can shutdown gracefully and lifespan events are triggered. This is especially important with docker compose.
Build Docker image command
Build a Docker image using: docker build -t myimage . The dot (.) at the end specifies the build context directory (current directory).
Run Docker container command
Run a container based on an image using: docker run -d --name mycontainer -p 80:80 myimage. The -d flag runs in detached mode, --name sets the container name, -p maps ports (host:container).
Dockerfile for single-file FastAPI
Example Dockerfile for a single-file FastAPI project (main.py without app directory): FROM python:3.14 WORKDIR /code COPY ./requirements.txt /code/requirements.txt RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt COPY ./main.py /code/ CMD ["fastapi", "run", "main.py", "--port", "80"] When passing a single file to fastapi run, it automatically detects it is not part of a package and handles importing and serving the app.
Container advantages
Linux containers provide security, replicability, simplicity, and are lightweight compared to virtual machines. Containers run using the host's Linux kernel, consume minimal resources comparable to running processes directly, and have isolated running processes, file systems, and networks.
Container image definition
A container image is a static version of all files, environment variables, and the default command/program for a container. It is not running; it is only the packaged files and metadata. In contrast, a container is the running instance executed from a container image.
Container process lifecycle
A container is running only when it has a process running, normally just a single process. The container stops when there is no process running in it.
HTTPS handling with containers
HTTPS for container-based FastAPI applications is normally handled externally by another tool, such as a TLS Termination Proxy (e.g., Traefik, Nginx) running in another container, or by a cloud provider service. Traefik has integrations with Docker and Kubernetes for easy HTTPS and automatic certificate acquisition.
Container startup and restart management
Container orchestration tools (Docker, Docker Compose, Kubernetes, cloud services) typically provide built-in options for running containers on startup and enabling restarts on failures. In Docker, this is configured with the --restart command line option.
Replication strategy with cluster systems
When using Kubernetes or other distributed container management systems, handle replication at the cluster level rather than using a process manager with multiple workers in each container. Build a Docker image from scratch with a single Uvicorn process per container, and let the cluster system handle replication across multiple containers.
Load balancer with containers
When working with containers, a load balancer listens on the main port and distributes requests among worker containers. This is typically a TLS Termination Proxy component that also handles HTTPS. In Kubernetes and similar systems, internal networking mechanisms transmit communication from the load balancer to multiple identical containers running the app.
Multiple workers in container with --workers
To run multiple Uvicorn worker processes in a single container, use the --workers command line option with fastapi run. Example: CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"]
Single container with multiple processes use cases
Multiple Uvicorn worker processes per container make sense for: simple applications running on a single server, or Docker Compose deployments on a single server where cluster-level container replication is not available.
Memory management in containers
When running a single process per container, memory consumption is well-defined and stable per container. Container orchestration systems can use this to replicate containers across available machines based on memory requirements. If running multiple processes per container, ensure the total memory used by all processes does not exceed available memory.
Previous steps before starting with containers
For multi-container deployments (e.g., Kubernetes), use a separate container (or Init Container in Kubernetes) to run setup steps before running replicated worker containers. For single-container deployments, run setup steps in the same container before starting the main process.
Docker image deployment options
After building a container image, deployment options include: Docker Compose on a single server, Kubernetes cluster, Docker Swarm Mode cluster, Nomad, or cloud services that accept and deploy container images.
uv package manager with Docker
When using uv to manage FastAPI projects, direct dependencies are declared in pyproject.toml and exact versions in uv.lock. Export locked dependencies to requirements.txt format for the Dockerfile using: uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt. Continue managing dependencies with uv add and regenerate requirements.txt when uv.lock changes. Refer to uv's Docker guide for integration.
Proxy headers for TLS termination
When running a FastAPI container behind a TLS Termination Proxy (load balancer) like Nginx or Traefik, add the --proxy-headers option. This tells Uvicorn (through the FastAPI CLI) to trust headers sent by the proxy about HTTPS and related information.