---
title: "FastAPI + Python + Docker Stack"
aliases: [fastapi-docker, python-api]
tags: [fastapi, python, docker, backend]
sources: [01 Projects/gmal-scope-builder, 01 Projects/modcomms, 01 Projects/video-accessibility, 01 Projects/pdf-accessibility, 01 Projects/olivas, 01 Projects/pimco-charts, 01 Projects/solventum-image-metadata]
created: 2026-04-15
updated: 2026-04-15
---

# FastAPI + Python + Docker Stack

The dominant backend pattern at Oliver — Python FastAPI served via Docker Compose, typically paired with React/Vite frontend.

## Key Takeaways
- Default backend choice for all new Oliver AI tools
- Uvicorn is the ASGI server; standard port is 8000 or 8001
- Always use `asyncpg` + SQLAlchemy async when touching PostgreSQL
- Docker Compose is the standard deploy — backend + frontend + DB in one `compose.yml`
- `alembic` for database migrations (PostgreSQL projects)
- `uv` emerging as the package manager of choice (Sandbox NotebookLM uses Python 3.13 + uv)

## When to Use
Any new Oliver internal tool needing a REST API backend, especially when AI integration is required.

## Key Details
- **ASGI server:** Uvicorn (`uvicorn app.main:app --reload --host 0.0.0.0 --port 8000`)
- **Async DB:** SQLAlchemy async + asyncpg (PostgreSQL) or PyMongo (MongoDB)
- **Migrations:** Alembic (30+ revisions in Enterprise Nexus)
- **Package manager:** pip / venv standard; `uv` for newer projects
- **Port conventions:** Backend 8000 or 8001; Frontend 3000, 3010, or 5173

## Projects Using This Pattern
- [[01 Projects/gmal-scope-builder/GMAL Scope Builder|GMAL Scope Builder]] — FastAPI :8001, PostgreSQL :5433, React :3010
- [[01 Projects/modcomms/Mod Comms|Mod Comms]] — FastAPI :8000, PostgreSQL, React :3000, GCP
- [[01 Projects/video-accessibility/Video Accessibility Platform|Video Accessibility]] — FastAPI + Celery workers, MongoDB, Redis
- [[01 Projects/pdf-accessibility/PDF Accessibility Checker|PDF Accessibility]] — FastAPI + PHP hybrid, PostgreSQL, Redis
- [[01 Projects/enterprise-ai-hub-nexus/Enterprise AI Hub Nexus|Enterprise Nexus]] — FastAPI + Celery + Qdrant + PostgreSQL + Redis
- [[01 Projects/olivas/OliVAS|OliVAS]] — FastAPI + DeepGaze + Claude
- [[01 Projects/pimco-charts/PIMCO Chart Generator|PIMCO Charts]] — FastAPI + Claude API
- [[01 Projects/solventum-image-metadata/Solventum Image Metadata|Solventum]] — FastAPI + OpenAI
- [[01 Projects/Oliver-ai-bot_2.0/Oliver AI Bot 2.0|Oliver AI Bot 2.0]] — FastAPI + Next.js

## Standard Docker Compose Structure
```yaml
services:
  backend:
    build: ./backend
    ports: ["8000:8000"]
    env_file: .env
    depends_on: [db, redis]
  frontend:
    build: ./frontend
    ports: ["3000:3000"]
  db:
    image: postgres:16
    ports: ["5432:5432"]
  redis:
    image: redis:7
```

## Gotchas & Lessons
- GCP Load Balancer has a 30s timeout — long AI calls must use **HTTP polling**, not WebSocket streaming (learned from Mod Comms + Semblance)
- Vite proxy timeout must be increased for long AI operations: `proxy timeout: 300000` (5 min) — learned from GMAL
- `DEV_AUTH_BYPASS` env var pattern for skipping Azure AD auth locally
- For PostgreSQL, always pin port to non-default (e.g., 5433) to avoid conflicts with local installs
- When using Alembic: run `alembic upgrade head` inside the container after first start

## Related
- [[wiki/tech-patterns/react-vite-typescript|react-vite-typescript]] — paired frontend
- [[wiki/tech-patterns/azure-ad-msal-auth|azure-ad-msal-auth]] — auth layer
- [[wiki/tech-patterns/redis-celery-worker-queue|redis-celery-worker-queue]] — async task processing
- [[wiki/architecture/docker-compose-fullstack|docker-compose-fullstack]] — deployment pattern
- [[wiki/architecture/gcp-deployment-lb-timeout|gcp-deployment-lb-timeout]] — GCP gotcha