> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipfastai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker and Docker Compose local development setup

> Run the full Shipfastai stack locally with Docker Compose, including the FastAPI backend, Next.js frontend, PostgreSQL, and Redis.

Shipfastai ships with Docker Compose configuration so you can spin up the entire stack — FastAPI backend, Next.js frontend, PostgreSQL database, and Redis — with a single command. This page walks you through starting, inspecting, and stopping your local environment, and explains how the production Compose file differs.

## Starting the stack

From the root of your product directory (e.g. `products/basic/` or `products/pro/`), run:

```bash theme={null}
docker-compose up -d
```

Docker Compose pulls any missing images, builds the backend and frontend containers from their respective `Dockerfile`s, and starts all services in the background. Once the command returns, the following services are running:

| Service    | Port | Description                         |
| ---------- | ---- | ----------------------------------- |
| `frontend` | 3000 | Next.js development server          |
| `backend`  | 8000 | FastAPI with Uvicorn, hot-reload on |
| `db`       | 5432 | PostgreSQL 15                       |
| `redis`    | 6379 | Redis 7 for caching                 |

The backend waits for PostgreSQL and Redis to pass their health checks before it starts, so all services are ready by the time `docker-compose up -d` returns.

<Tip>
  Run `docker-compose ps` at any time to see the status of every service and confirm each one is healthy before you start developing.
</Tip>

## Viewing logs

To follow the combined log output of all services:

```bash theme={null}
docker-compose logs -f
```

To tail only the backend:

```bash theme={null}
docker-compose logs -f backend
```

You can substitute any service name (`frontend`, `db`, `redis`) to isolate its output. Press `Ctrl+C` to stop following without stopping the containers.

## Stopping the stack

To stop all containers while preserving your database volume:

```bash theme={null}
docker-compose down
```

To stop all containers **and delete all data volumes** (a full reset):

```bash theme={null}
docker-compose down -v
```

The `-v` flag removes the named `postgres_data` volume, so your database is wiped. Use this when you want a clean slate or need to re-run migrations from scratch.

## Production Docker Compose

The repository also includes `docker-compose.prod.yml` for production deployments on a single server (e.g. a DigitalOcean Droplet or EC2 instance). It differs from the development file in several important ways:

* **No hot-reload.** The backend runs Gunicorn with multiple Uvicorn workers instead of `uvicorn --reload`, and the frontend is served as a pre-built static bundle.
* **Pre-built images.** Services reference tagged Docker images (e.g. `ghcr.io/Shipfastai/backend:latest`) rather than building from local source.
* **Production environment variables.** `APP_ENV=production`, `DEBUG=false`, and `LOG_FORMAT=json` are set explicitly.
* **Nginx reverse proxy.** An Nginx container handles TLS termination and routes traffic to the backend (port 8000) and frontend (port 3000) services.
* **Persistent Redis volume.** Redis data is written to a named volume so it survives container restarts.

To start the production stack:

```bash theme={null}
docker-compose -f docker-compose.prod.yml up -d
```

## Rebuilding after changes

When you modify the `Dockerfile` or install new Python/Node dependencies, rebuild the affected image before restarting:

```bash theme={null}
docker-compose up -d --build
```

To rebuild a single service without restarting the others:

```bash theme={null}
docker-compose up -d --build backend
```