Docker and Docker Compose configuration and troubleshooting. Use for containers, services, volumes, networking, health checks, and deployment patterns.
Activation: Docker, Docker Compose, containers, services, deployment
Pre-bundled frontend: astro/dist/ is committed to git. No Vite dev server at runtime.
Runtime containers: db, backend, nginx
Build-only container: frontend (used for just build-astro)
| Service | Port | Image | Purpose |
|---|---|---|---|
| nginx | 9000 | nginx:alpine | Routes static files + API proxy |
| backend | 8000 | python:3.12-slim | FastAPI with uvicorn --reload |
| astro | - |
| node:24-alpine |
| Build-only (Astro build) |
| worker | - | python:3.12-slim | TaskIQ workers |
| db | 5432 | postgres:18-alpine | PostgreSQL database |
| redis | 6379 | redis:8.4.0-alpine | Job queue + cache |
Note: Frontend container is only used for builds (just build-astro). At runtime, nginx serves pre-built files from the bind-mounted astro/dist/ directory.
# Start all services
docker compose up
# Start specific service
docker compose up backend
# Rebuild after dependency changes
docker compose build backend
docker compose up backend
# View logs
docker compose logs -f backend worker
# Shell into container
docker compose exec backend bash
docker compose exec astro sh
# Stop all
docker compose down
# Stop and remove volumes (reset DB)
docker compose down -v
# backend/Dockerfile.dev
FROM python:3.12-slim
WORKDIR /app
# System dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential \
curl \
libsndfile1 \
ffmpeg \
&& rm -rf /var/lib/apt/lists/*
# Install uv for fast dependency management
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
# Copy dependency files
COPY backend/pyproject.toml ./
# Install dependencies
RUN uv pip install --system -e ".[dev]"
# Copy source (volumes override in dev)
COPY backend/ .
# Run with hot-reload (via entrypoint.sh for migrations)
ENTRYPOINT ["/bin/bash", "/app/entrypoint.sh"]
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
The frontend container is used for builds only. No dev server runs at runtime.
# astro/Dockerfile.dev
FROM node:24-alpine
WORKDIR /app
# Install pnpm
RUN corepack enable && corepack prepare pnpm@latest --activate
# Copy dependency files
COPY package.json pnpm-lock.yaml ./
# Install dependencies
RUN pnpm install --frozen-lockfile
# Copy source (volumes override in dev)
COPY . .
# Build command (not a running server)
# Used via: docker compose exec astro pnpm build
CMD ["sleep", "infinity"]
Note: Frontend builds to astro/dist/ which is committed to git and bind-mounted into nginx.
# backend/Dockerfile
FROM python:3.12-slim AS builder
WORKDIR /app
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
COPY backend/pyproject.toml ./
RUN uv pip install --system -e "."
FROM python:3.12-slim
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends \
libsndfile1 ffmpeg \
&& rm -rf /var/lib/apt/lists/*
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY backend/ .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
# docker-compose.yml