# How to Run the FastAPI Boilerplate Application Using Docker Compose

> Easily run the FastAPI boilerplate application with Docker Compose. Use the setup script to configure and launch PostgreSQL, Redis, and FastAPI services in one command.

- Repository: [Benav Labs/fastapi-boilerplate](https://github.com/benavlabs/fastapi-boilerplate)
- Tags: how-to-guide
- Published: 2026-02-26

---

**Use the [`./setup.py`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/./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:

```bash
./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`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/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`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/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`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/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`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/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:

```bash
docker compose up -d

```

2. Verify the API health endpoint:

```bash
curl http://127.0.0.1:8000/health

```

3. View logs for a specific service:

```bash
docker compose logs -f web

```

4. Stop the entire stack when finished:

```bash
docker compose down

```

## Running Administrative Tasks

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

Create the initial superuser account:

```bash
docker compose run --rm create_superuser

```

Execute the full test suite inside a disposable container:

```bash
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`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/./setup.py) with arguments `local`, `staging`, or `production` to select the appropriate [`docker-compose.yml`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/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`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/./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`](https://github.com/benavlabs/fastapi-boilerplate/blob/main/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.