feat(server): use Gunicorn + UvicornWorker with on_starting migration hook (#2)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nanotaboada

CHANGELOG.md

@@ -50,7 +50,12 @@ This project uses famous football coaches as release codenames, following an A-Z
   11 Starting XI players, `003` seeds 15 Substitute players (all with
   deterministic UUID v5 values); `alembic upgrade head` applied by
   `entrypoint.sh` (Docker) or manually for local development (#2)
-- `alembic==1.18.4`, `asyncpg==0.31.0` added to dependencies (#2)
+- `alembic==1.18.4`, `asyncpg==0.31.0`, `gunicorn==25.3.0` added to dependencies (#2)
+- `gunicorn.conf.py`: Gunicorn configuration — binds to `0.0.0.0:9000`, uses
+  `UvicornWorker`, derives worker count from `WEB_CONCURRENCY` env var; the
+  `on_starting` hook runs `alembic upgrade head` once in the master process
+  before any workers are forked, replacing the entrypoint-driven migration
+  pattern (#2)
 - `tests/test_migrations.py`: integration tests for migration downgrade paths —
   verifies each step removes only its seeded rows and restores correctly (#2)
 - `tests/conftest.py`: session-scoped `apply_migrations` fixture runs
@@ -78,8 +83,10 @@ This project uses famous football coaches as release codenames, following an A-Z
 - `Dockerfile`: removed `COPY storage/ ./hold/` and its associated comment;
   added `COPY alembic.ini` and `COPY alembic/` (#2)
 - `scripts/entrypoint.sh`: checks for an existing database file in the Docker
-  volume; runs `alembic upgrade head` only on first start; adds structured
-  `log()` helper with timestamps, emojis, and API/Swagger UI addresses (#2)
+  volume (informational logging only); adds structured `log()` helper with
+  timestamps and API/Swagger UI addresses; migrations delegated to Gunicorn
+  `on_starting` hook (#2)
+- `Dockerfile`: replaced `CMD uvicorn` with `CMD gunicorn -c gunicorn.conf.py` (#2)
 - `compose.yaml`: replaced `STORAGE_PATH` with `DATABASE_URL` pointing to the
   SQLite volume path (#2)
 - `.gitignore`: added `*.db`; `storage/players-sqlite3.db` removed from git

Dockerfile

@@ -51,6 +51,7 @@ RUN pip install --no-cache-dir --no-index --find-links /app/wheelhouse /app/whee
 
 # Copy application source code
 COPY main.py            ./
+COPY gunicorn.conf.py   ./
 COPY alembic.ini        ./
 COPY alembic/           ./alembic/
 COPY databases/         ./databases/
@@ -80,4 +81,4 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
     CMD ["./healthcheck.sh"]
 
 ENTRYPOINT ["./entrypoint.sh"]
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "9000"]
+CMD ["gunicorn", "-c", "gunicorn.conf.py", "main:app"]

gunicorn.conf.py

@@ -0,0 +1,24 @@
+"""
+Gunicorn configuration for production deployment.
+
+Uses UvicornWorker to run the FastAPI ASGI app. The on_starting hook runs
+Alembic migrations once in the master process before any workers are forked,
+ensuring a single, race-free initialization step.
+"""
+
+import multiprocessing
+import os
+from pathlib import Path
+
+from alembic import command
+from alembic.config import Config
+
+bind: str = "0.0.0.0:9000"
+workers: int = int(os.getenv("WEB_CONCURRENCY", multiprocessing.cpu_count() * 2 + 1))
+worker_class: str = "uvicorn.workers.UvicornWorker"
+
+
+def on_starting(server) -> None:
+    """Apply Alembic migrations once before workers are spawned."""
+    alembic_cfg = Config(str(Path(__file__).resolve().parent / "alembic.ini"))
+    command.upgrade(alembic_cfg, "head")

pyproject.toml

@@ -12,6 +12,7 @@ dependencies = [
     "aiocache==0.12.3",
     "alembic==1.18.4",
     "asyncpg==0.31.0",
+    "gunicorn>=25.3.0",
 ]
 
 [dependency-groups]

scripts/entrypoint.sh

@@ -15,9 +15,7 @@ mkdir -p "$(dirname "$STORAGE_PATH")"
 
 if [ ! -f "$STORAGE_PATH" ]; then
     log "⚠️ No existing database file found in volume."
-    log "🗄️ Applying Alembic migrations to initialize the database..."
-    alembic upgrade head
-    log "✔ Migrations applied."
+    log "🗄️ Gunicorn will apply Alembic migrations on first start."
 else
     log "✔ Existing database file found at $STORAGE_PATH."
 fi