How to Run the FastAPI Boilerplate Application Using Docker Compose

Use the ./setup.py helper script to select a deployment configuration, then execute docker compose up to launch the PostgreSQL, Redis, and FastAPI services bundled in the multistage Docker setup.

The benavlabs/fastapi-boilerplate repository provides production-ready container orchestration for Python web applications. You can run the application using Docker Compose through three distinct deployment modes—local development, staging, and production—each optimized for specific runtime requirements. The architecture uses a shared multistage Dockerfile with environment-specific compose files located in the scripts/ directory.

Architecture Overview

The Docker Compose configuration orchestrates six core services defined across three environment-specific files:

• web: The FastAPI application server (Uvicorn or Gunicorn) built from the multistage Dockerfile
• worker: Background job processor using ARQ, sharing the same image as the web service
• db: PostgreSQL 13 database using the official postgres:13 image
• redis: Message broker and cache using the official redis:alpine image
• nginx (production only): Reverse proxy using the official nginx:latest image
• create_superuser (optional): One-off container to initialize the first admin user
• pytest (optional): Ephemeral container for running the test suite

The compose files handle service dependencies, volume mounts, and network bridging between containers.

Prerequisites and Initial Setup

Before starting the application, you must generate the runtime environment configuration. The repository includes a setup helper that copies the appropriate Docker assets and environment templates.

Run the setup script to select your target environment:

./setup.py local        # Uvicorn with auto-reload

./setup.py staging      # Gunicorn managing Uvicorn workers

./setup.py production   # NGINX + Gunicorn stack

This command copies the relevant docker-compose.yml and Dockerfile from the corresponding scripts/ subdirectory (such as scripts/local_with_uvicorn/) into the project root. It also copies src/.env.example to src/.env, which you must edit to set DATABASE_URL, REDIS_URL, SECRET_KEY, and other secrets required by all containers.

Deployment Modes and Compose Files

The repository maintains three distinct Docker Compose configurations tailored to specific operational contexts.

Local Development with Uvicorn

For local development, use scripts/local_with_uvicorn/docker-compose.yml. This configuration mounts your source code as a volume and runs Uvicorn with --reload to reflect code changes immediately without rebuilding the image. The API binds to http://127.0.0.1:8000.

Staging with Gunicorn Managing Uvicorn Workers

The staging configuration in scripts/gunicorn_managing_uvicorn_workers/docker-compose.yml deploys Gunicorn as the process manager with Uvicorn workers. This mirrors production process architecture while remaining accessible at http://127.0.0.1:8000 for validation.

Production with NGINX Reverse Proxy

The production setup in scripts/production_with_nginx/docker-compose.yml adds an NGINX service that listens on port 80 and proxies requests to the Gunicorn-backed FastAPI application. This provides static file serving, SSL termination readiness, and improved connection handling. The application is accessible at http://localhost.

Step-by-Step Execution Guide

Once you have selected a deployment mode and configured src/.env, start the stack with Docker Compose.

1. Build and launch all services in detached mode:

docker compose up -d

2. Verify the API health endpoint:

curl http://127.0.0.1:8000/health

3. View logs for a specific service:

docker compose logs -f web

4. Stop the entire stack when finished:

docker compose down

Running Administrative Tasks

The compose configuration includes optional services for database initialization and testing.

Create the initial superuser account:

docker compose run --rm create_superuser

Execute the full test suite inside a disposable container:

docker compose run --rm pytest

These commands spawn temporary containers using the same image as the web service, ensuring dependency consistency with the runtime environment.

Understanding the Multistage Dockerfile

All deployment modes share a common multistage Dockerfile (located in scripts/local_with_uvicorn/Dockerfile and equivalents) that optimizes image size and security:

1. Builder Stage: Uses ghcr.io/astral-sh/uv:python3.11-bookworm-slim to install Python dependencies into a virtual environment using the uv package manager for speed.

2. Final Stage: Copies the .venv directory into a minimal python:3.11-slim-bookworm image, creates a non-root user for runtime security, and configures the PATH to include the virtual environment binaries.

3. Default Command: The Dockerfile defaults to starting Uvicorn, though you can uncomment an alternative CMD to launch Gunicorn with Uvicorn workers when building for staging or production.

Summary

• Use ./setup.py with arguments local, staging, or production to select the appropriate docker-compose.yml and Dockerfile for your environment.
• The multistage Dockerfile builds a secure, minimal image using uv for dependency resolution and a non-root execution context.
• Docker Compose coordinates the web server, background worker, PostgreSQL database, and Redis cache through official base images.
• One-off administrative tasks like superuser creation and test execution run via docker compose run --rm using ephemeral containers.

Frequently Asked Questions

What services are included in the Docker Compose setup?

The compose configuration includes the web API server, worker ARQ processor, db PostgreSQL 13 instance, and redis Alpine cache. Optional services include nginx for production reverse-proxying, create_superuser for initial admin setup, and pytest for test execution.

How do I switch between development and production modes?

Run ./setup.py with the desired mode argument—local for development (Uvicorn with reload), staging for pre-production validation (Gunicorn), or production for the NGINX-backed deployment. This overwrites the root-level docker-compose.yml and Dockerfile with the appropriate variants from the scripts/ directory.

How do I create an admin user in the Dockerized application?

Execute the one-off superuser service: docker compose run --rm create_superuser. This command spins up a temporary container using the application image, runs the creation script against the shared PostgreSQL volume, and removes the container upon completion.

What is the difference between the Uvicorn and Gunicorn deployment options?

The local configuration runs Uvicorn directly with --reload enabled for rapid iteration. The staging and production configurations use Gunicorn as the process manager with Uvicorn worker classes, providing multiple worker processes, graceful restarts, and better resource utilization under load.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}