73 lines
3.7 KiB
Markdown
73 lines
3.7 KiB
Markdown
---
|
|
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
|