Skip to content

development-guide.md

Latest commit

 

History

History
209 lines (154 loc) · 6.87 KB

development-guide.md

File metadata and controls

209 lines (154 loc) · 6.87 KB
Raw

Development Guide

This guide describes all available modes for running the project locally. Choose the one that best fits your workflow.

For production deployment, see the Deployment Guide.

Overview

development/
├── compose/
│   ├── full-stack/    → Everything in Docker (databases + API + workers)
│   └── infra-only/    → Only databases in Docker; API runs on the host
└── native/            → Everything runs directly on the host (no Docker)
Mode Best For Docker Required Hot Reload IDE Debugger
compose/full-stack Isolated, consistent environment ✅ ✅ ⚠️ Remote only
compose/infra-only Native API with local DBs ✅ (DBs only) ✅ ✅
native Maximum performance, full control ❌ ✅ ✅

🐳 compose/full-stack

Full documentation: development/compose/full-stack/README.md

When to use: You want to run everything — databases, API, and Celery services — inside Docker containers on your local machine, with hot-reload enabled via volume mounts.

What's included:

Service Description
postgres PostgreSQL 17 with pgvector
redis Redis Alpine
migrate Runs alembic upgrade head once before API starts
api FastAPI via Uvicorn with --reload
celery_worker Celery Worker (source mounted)
celery_beat Celery Beat scheduler
celery_flower Flower UI (auth required)

Prerequisites:

  • Docker and Docker Compose installed.
  • backend/.env configured (copy from backend/.env.example).
  • FLOWER_BASIC_AUTH=user:password set in backend/.env.

Run (from repository root):

Start main environment (Postgres, Redis, API):

docker compose --env-file backend/.env \
  -f development/compose/full-stack/docker-compose.yml \
  --project-name fastapi-async-sqlmodel-boilerplate up -d

Run migration:

docker compose --env-file backend/.env \
  -f development/compose/full-stack/docker-compose.yml \
  --project-name fastapi-async-sqlmodel-boilerplate \
  --profile migrate run --rm migrate

Start Celery Worker:

docker compose --env-file backend/.env \
  -f development/compose/full-stack/docker-compose.yml \
  --project-name fastapi-async-sqlmodel-boilerplate \
  --profile worker up -d celery_worker

Start Celery Beat:

docker compose --env-file backend/.env \
  -f development/compose/full-stack/docker-compose.yml \
  --project-name fastapi-async-sqlmodel-boilerplate \
  --profile scheduler up -d celery_beat

Start Flower (Observability):

docker compose --env-file backend/.env \
  -f development/compose/full-stack/docker-compose.yml \
  --project-name fastapi-async-sqlmodel-boilerplate \
  --profile observability up -d celery_flower

Notes:

  • The backend/ directory is mounted as a volume — code changes reflect immediately without rebuilding.
  • Connection host variables (POSTGRES_SERVER, REDIS_*_HOST) are automatically overridden to point to the Docker service names. Your .env values for those are not used inside Docker.

🐳 compose/infra-only

Full documentation: development/compose/infra-only/README.md

When to use: You want Postgres and Redis running in Docker, but prefer to run the API and Celery directly on your host machine — for full IDE debugger support or faster startup.

What's included:

Service Description
postgres PostgreSQL 17 with pgvector (exposed on localhost:5432)
redis Redis Alpine (exposed on localhost:6379)

Run (from repository root):

docker compose --env-file backend/.env -f development/compose/infra-only/docker-compose.yml \
  --project-name fastapi-async-sqlmodel-boilerplate up -d

Then run the backend. Option A — Quick start:

python3 setup.py

Option B — Manual (from backend/):

poetry run alembic upgrade head
poetry run uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
# In another terminal:
poetry run celery -A src.worker worker --loglevel=info

Notes:

  • Make sure backend/.env has POSTGRES_SERVER=localhost and REDIS_*_HOST=localhost.
  • Postgres password is read from REDIS_CACHE_PASSWORD in backend/.env.

🖥️ native

Full documentation: development/native/README.md

When to use: You want to run everything directly on your host machine without Docker — the fastest setup with the lowest overhead and full debugger support.

Prerequisites:

  • Python 3.11+ and Poetry
  • PostgreSQL with pgvector extension installed locally
  • Redis installed locally

Don't have Python/Poetry? Use the install helper scripts:

  • Linux: bash development/native/scripts/install_python.sh
  • Windows: development\native\scripts\install_python.bat

Quick start (recommended):

python3 setup.py

Manual setup (from backend/):

poetry install
cp .env.example .env   # Edit with your local DB credentials
poetry run alembic upgrade head
poetry run uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

Tips:

  • Use Honcho to manage multiple processes in one terminal.
  • If you don't want to install Postgres/Redis locally, use compose/infra-only instead.

Common: Environment Variables

All development modes use backend/.env. Start by copying the example:

cp backend/.env.example backend/.env

For local development, the key variables to set are:

Variable Local Default
POSTGRES_SERVER localhost
POSTGRES_USER your local DB user
POSTGRES_PASSWORD your local DB password
POSTGRES_DB your local DB name
REDIS_CACHE_HOST localhost
REDIS_CACHE_PASSWORD your local Redis password
REDIS_BROKER_HOST localhost
REDIS_BROKER_PASSWORD your local Redis password
SECRET_KEY any random string for local dev
ENVIRONMENT local

For Docker-based modes (compose/full-stack, compose/infra-only), host variables like POSTGRES_SERVER are overridden automatically by the compose file.

See backend/.env.example for the full list and descriptions.

Further Reading