Add optional Docker Compose dev stack and document it

Introduce docker-compose.yml with API (backend/Dockerfile), rundown-ui,
and prompter services; env vars live in .env.docker (from example).
Vite configs read DUOPUS_API_PROXY for the dev proxy target. Update
PHASE1.md and AGENTS.md: remove Docker from out-of-scope, explain why
Compose exists and how it relates to local dev.

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

Author: cursoragent

.env.docker.example

@@ -0,0 +1,17 @@
+# Used by `docker compose` (see `docker-compose.yml`).
+# Copy to `.env.docker` before `docker compose up`: `cp .env.docker.example .env.docker`
+# At minimum, set `SECRET_KEY` to a long random string.
+
+SECRET_KEY=change-me-to-a-long-random-string
+
+# SQLite on the named volume `duopus-sqlite`, mounted at /data in the API container.
+DATABASE_URL=sqlite+aiosqlite:////data/duopus.db
+
+# Browser origins for the Vite apps (host machine → published ports).
+CORS_ORIGINS=http://localhost:5173,http://localhost:5174
+
+ENVIRONMENT=development
+AUTOGEN_TIME_UTC=03:00
+
+# Optional: seed admin password (default in docs if unset).
+# ADMIN_PASSWORD=

.gitignore

@@ -1,4 +1,5 @@
 .env
+.env.docker
 __pycache__/
 *.py[cod]
 .pytest_cache/

AGENTS.md

@@ -7,7 +7,7 @@
 ### Stack (Phase 1)
 
 - **Backend:** Python 3.12, FastAPI, SQLModel, **SQLite** (`DATABASE_URL`). Dependencies and lockfile live under `backend/` (`pyproject.toml`, `uv.lock`). Schema is created with **`SQLModel.metadata.create_all`** (no Alembic in this phase).
-- **Frontend:** `frontend/rundown-ui` and `frontend/prompter` — local dev with Vite (`npm run dev`). There is **no** Docker Compose or bundled nginx in Phase 1; run the API and Vite dev servers separately.
+- **Frontend:** `frontend/rundown-ui` and `frontend/prompter` — local dev with Vite (`npm run dev`). For a **one-command dev/smoke-test stack**, use Docker Compose from the repo root (see below); otherwise run the API and Vite dev servers separately.
 
 ### Commands
 
@@ -26,6 +26,11 @@ After changing dependencies in `pyproject.toml`, run `uv lock` and commit `uv.lo
 - `cd frontend/rundown-ui && npm install && npm run dev`
 - `cd frontend/prompter && npm install && npm run dev` — prompter handoff view (`/prompter/:storyId`); polls the API as described in `docs/PHASE1.md`
 
+**Docker Compose (optional, dev / smoke testing)**
+
+- Copy `.env.docker.example` to `.env.docker` (gitignored) and set at least `SECRET_KEY`; add or change any API env vars there (same semantics as `.env` for the backend).
+- From the repo root: `docker compose up --build` — builds `backend/Dockerfile`, runs API on **8000**, rundown UI on **5173**, prompter on **5174**. SQLite uses the `duopus-sqlite` volume; see `docs/PHASE1.md` for rationale and Vite proxy details (`DUOPUS_API_PROXY`).
+
 ### Default dev login
 
 See **Seed data** in `docs/PHASE1.md` (admin user and password for local development).

backend/.dockerignore

@@ -0,0 +1,9 @@
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+*.db
+.git/
+*.egg-info/

backend/Dockerfile

@@ -0,0 +1,17 @@
+# Dev / smoke-test API image (Python 3.12 + locked deps via uv).
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+
+WORKDIR /app
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy
+
+COPY pyproject.toml uv.lock ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-install-project --no-dev
+
+COPY . .
+
+EXPOSE 8000
+
+CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml

@@ -0,0 +1,60 @@
+# Optional dev stack: API + both Vite dev servers.
+# Before first run: `cp .env.docker.example .env.docker` and set secrets / overrides there.
+services:
+  api:
+    build:
+      context: ./backend
+      dockerfile: Dockerfile
+    env_file:
+      - .env.docker
+    ports:
+      - "8000:8000"
+    volumes:
+      - duopus-sqlite:/data
+    healthcheck:
+      test:
+        [
+          "CMD",
+          "python",
+          "-c",
+          "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')",
+        ]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+      start_period: 10s
+
+  rundown-ui:
+    image: node:22-bookworm-slim
+    working_dir: /app
+    environment:
+      DUOPUS_API_PROXY: http://api:8000
+    volumes:
+      - ./frontend/rundown-ui:/app
+      - rundown-ui-node-modules:/app/node_modules
+    command: sh -c "npm ci && npm run dev -- --host 0.0.0.0"
+    ports:
+      - "5173:5173"
+    depends_on:
+      api:
+        condition: service_healthy
+
+  prompter:
+    image: node:22-bookworm-slim
+    working_dir: /app
+    environment:
+      DUOPUS_API_PROXY: http://api:8000
+    volumes:
+      - ./frontend/prompter:/app
+      - prompter-node-modules:/app/node_modules
+    command: sh -c "npm ci && npm run dev -- --host 0.0.0.0"
+    ports:
+      - "5174:5174"
+    depends_on:
+      api:
+        condition: service_healthy
+
+volumes:
+  duopus-sqlite:
+  rundown-ui-node-modules:
+  prompter-node-modules:

docs/PHASE1.md

@@ -17,7 +17,6 @@ Phase 1 is a **self-contained, locally-runnable web app**. No broadcast integrat
 - WebSockets or Redis  
 - CasparCG or vMix integration  
 - Companion / Streamdeck module  
-- Docker / docker-compose (no containerized stack in this phase)  
 - Alembic migrations (**SQLModel `create_all` is sufficient**)  
 - Prompter scroll velocity / mirror flip modes (use QPrompt externally)  
 - Auth beyond simple **session-based** login (FastAPI-Users with cookies; no JWT complexity)
@@ -211,10 +210,22 @@ Prompter polling (handoff to QPrompt): **`GET /api/prompter/{story_id}`** — la
 
 ---
 
-## Running locally (no Docker)
+## Running locally
+
+### Without Docker (default)
 
 1. **Backend:** from `backend/`, `uv sync --extra dev`, set `SECRET_KEY` (and optional `DATABASE_URL`), then `uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000`.  
 2. **Rundown UI:** `frontend/rundown-ui` — `npm install` && `npm run dev` (Vite proxies `/api` to the backend per `vite.config`).  
 3. **Prompter:** `frontend/prompter` — `npm run dev` on a second port if needed; configure API origin as in Vite config.  
 
 `CORS_ORIGINS` in `.env` must include the Vite dev origin (e.g. `http://localhost:5173`).
+
+### Optional Docker Compose (dev / smoke testing)
+
+The repo includes a **non-production** Compose stack for manual testing: API on port **8000**, rundown UI on **5173**, prompter on **5174**. It is **not** part of the Phase 1 product scope beyond convenience for developers and agents; behaviour matches the local stack above.
+
+1. Copy **`.env.docker.example`** to **`.env.docker`** (gitignored) and set **`SECRET_KEY`** and any other variables you need. All API-related env vars for the container are read from `.env.docker` so you can tune `DATABASE_URL`, `CORS_ORIGINS`, `ADMIN_PASSWORD`, etc., without touching the compose file.  
+2. From the repo root: **`docker compose up --build`**.  
+3. SQLite data is stored on the named volume **`duopus-sqlite`** (path inside the API container is whatever `DATABASE_URL` points to; the example uses `/data/duopus.db` on that volume).
+
+Vite dev servers in Compose proxy `/api` to the **`api`** service via the **`DUOPUS_API_PROXY`** environment variable (`http://api:8000`). For local (non-Docker) Vite, the default proxy remains `http://127.0.0.1:8000`.

frontend/prompter/vite.config.ts

@@ -1,13 +1,16 @@
 import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
 
+/** Dev server proxy target (Docker Compose sets `http://api:8000`). */
+const apiProxy = process.env.DUOPUS_API_PROXY ?? "http://127.0.0.1:8000";
+
 export default defineConfig({
   plugins: [react()],
   base: "/prompter/",
   server: {
     port: 5174,
     proxy: {
-      "/api": "http://127.0.0.1:8000",
+      "/api": apiProxy,
     },
   },
 });

frontend/rundown-ui/vite.config.ts

@@ -1,13 +1,16 @@
 import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
 
+/** Dev server proxy target (Docker Compose sets `http://api:8000`). */
+const apiProxy = process.env.DUOPUS_API_PROXY ?? "http://127.0.0.1:8000";
+
 export default defineConfig({
   plugins: [react()],
   base: "/",
   server: {
     port: 5173,
     proxy: {
-      "/api": "http://127.0.0.1:8000",
+      "/api": apiProxy,
     },
   },
 });