build(backend): manage dependencies with uv and pyproject.toml (#13)

Replace requirements.txt with a uv project (pyproject.toml + uv.lock),
following Astral uv Docker guidance: copy the uv binary, sync from the
lockfile in a cache-friendly layer, and run the app from .venv.

Declare Alembic, psycopg, and redis explicitly; use python -m alembic in
the entrypoint. Set tool.uv.package=false for a flat FastAPI app layout.

CI runs pytest via uv with --extra dev so production images stay slim;
Docker Compose build still validates the image. Add backend/.dockerignore
so local .venv is not sent as build context.

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Jakub Doboš <kubo6472@users.noreply.github.com>

Author: kubo6472

.github/workflows/ci.yml

@@ -23,11 +23,18 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.11.14"
+          enable-cache: true
+          cache-dependency-glob: "backend/uv.lock"
+
+      - name: Run backend tests
+        working-directory: backend
+        run: uv sync --locked --extra dev && uv run pytest
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
       - name: Build Compose images
         run: docker compose build
-
-      - name: Run backend tests (backend image)
-        run: docker compose run --rm --no-deps backend python -m pytest

AGENTS.md

@@ -10,13 +10,17 @@ Copy `.env.example` to `.env` if you want to override defaults locally. Compose
 
 **Backend (from `backend/`)**
 
-- `python3 -m pip install -r requirements.txt` — install dependencies
-- `python3 -m pytest` — run tests (vMix tally parsing + rundown engine DB logic)
-- `python3 -m uvicorn main:app --reload --host 0.0.0.0 --port 8000` — local API (requires Postgres + Redis + env)
+Install [uv](https://docs.astral.sh/uv/) once (see upstream install instructions), then:
+
+- `uv sync --extra dev` — create `.venv` and install dependencies from `uv.lock` (omit `--extra dev` for runtime-only installs)
+- `uv run pytest` — run tests (vMix tally parsing + rundown engine DB logic)
+- `uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000` — local API (requires Postgres + Redis + env)
+
+After changing dependencies in `pyproject.toml`, run `uv lock` and commit the updated `uv.lock`.
 
 **Database migrations**
 
-- `POSTGRES_URL=... python3 -m alembic upgrade head` — apply migrations (also runs automatically in the backend container entrypoint)
+- `POSTGRES_URL=... uv run alembic upgrade head` — apply migrations (also runs automatically in the backend container entrypoint)
 
 **Frontends**
 

backend/.dockerignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.git/

backend/Dockerfile

@@ -2,12 +2,26 @@ FROM python:3.12-slim
 WORKDIR /app
 RUN apt-get update && apt-get install -y --no-install-recommends libpq5 \
   && rm -rf /var/lib/apt/lists/*
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-RUN addgroup --system app && adduser --system --ingroup app app
+
+COPY --from=ghcr.io/astral-sh/uv:0.11.14 /uv /uvx /bin/
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=0
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --locked
+
 COPY . .
-RUN chmod +x /app/entrypoint.sh && chown -R app:app /app
-ENV PYTHONUNBUFFERED=1
+RUN chmod +x /app/entrypoint.sh \
+  && addgroup --system app && adduser --system --ingroup app app \
+  && chown -R app:app /app
+
+ENV PATH="/app/.venv/bin:$PATH" \
+    VIRTUAL_ENV=/app/.venv \
+    PYTHONUNBUFFERED=1
 EXPOSE 8000
 USER app
 CMD ["/app/entrypoint.sh"]

backend/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "duopus-backend"
+version = "0.1.0"
+description = "Duopus NRCS FastAPI backend"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+    "alembic>=1.13.0",
+    "psycopg[binary]>=3.2.0",
+    "sqlmodel>=0.0.22",
+    "aiosqlite>=0.20.0",
+    "fastapi-users>=14.0.0",
+    "fastapi-users-db-sqlalchemy>=7.0.0",
+    "python-multipart>=0.0.9",
+    "python-dotenv>=1.0.0",
+    "redis>=5.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-asyncio>=0.24.0",
+]
+
+[tool.uv]
+package = false
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"