nuzlocke-tracker/.beans/nuzlocke-tracker-ahza--deployment-strategy.md

title, status, type, priority, created_at, updated_at

title	status	type	priority	created_at	updated_at
Deployment Strategy	todo	epic	normal	2026-02-09T14:03:53Z	2026-02-09T15:08:29Z

Define and implement a deployment strategy for running the nuzlocke-tracker in production on a local Unraid server while keeping laptop/PC as the development environment.

Context

• Components: API (Python/FastAPI), Frontend (Vite/React), PostgreSQL database
• Dev environment: Laptop/PC — continue using the existing docker-compose.yml for local development
• Production host: Unraid server running Docker containers
• Networking: LAN-only access, Nginx Proxy Manager already in place on Unraid
• Orchestration: Docker Compose for production (matching dev workflow). Install Portainer for container management and semi-automated deployments.

Decided Approach

Docker Compose + Portainer + Local Docker Registry

1. A local Docker registry runs on Unraid as a container, accessible on the LAN (e.g., unraid:5000 or behind Nginx Proxy Manager).
2. Images are built on the dev machine and pushed to the local registry.
3. Production runs docker-compose on Unraid, pulling images from the local registry instead of mounting source.
4. Portainer is installed on Unraid to manage stacks, provide a web UI, and enable webhook-triggered redeployments.
5. A deploy script on the dev machine automates the full flow: build images → push to local registry → trigger Portainer webhook to redeploy.
6. Nginx Proxy Manager handles routing on the LAN (e.g., nuzlocke.local → frontend container).
7. Database uses a named Docker volume for persistence; migrations run automatically on API container startup.

Branching Strategy

main + develop + feature branches

• main — always production-ready. Only receives merges from develop when ready to deploy. The deploy script builds from main.
• develop — integration branch for day-to-day work. Features are merged here and tested before promoting to main.
• feature/* — short-lived branches off develop for individual features/fixes. Merged back into develop via PR or direct merge when complete.

Workflow:

1. Create feature/xyz from develop
2. Work on the feature, commit, merge into develop
3. When ready to deploy: merge develop → main
4. Run ./deploy.sh (builds from main, pushes to local registry, triggers Portainer webhook)

Checklist

• Set up branching structure — create develop branch from main, establish the main/develop/feature/* workflow
• Update CLAUDE.md with branching rules — once the branching structure is in place, add instructions to CLAUDE.md that the branching strategy must be adhered to (always work on feature branches, never commit directly to main, merge flow is feature/* → develop → main)
• Set up local Docker registry on Unraid — run the registry:2 container, configure storage volume, optionally put it behind Nginx Proxy Manager with a hostname (e.g., registry.local)
• Create production docker-compose file (docker-compose.prod.yml) — uses images from the local registry, production env vars, no source volume mounts, proper restart policies
• Create production Dockerfiles (or multi-stage builds) — ensure frontend is built and served statically (e.g., via the API or a lightweight nginx container), API runs without debug mode
• Set up Portainer on Unraid — install Portainer CE as a Docker container, configure the stack from the production compose file
• Configure Portainer webhook for automated redeployment — add a webhook trigger in Portainer that pulls latest images and restarts the stack
• Create deploy script — a script (e.g., ./deploy.sh) that builds images from main, tags them for the local registry, pushes them, and triggers the Portainer webhook to redeploy
• Configure Nginx Proxy Manager — add proxy host entry pointing to the frontend/API containers on the appropriate ports
• Environment & secrets management — create a .env.prod template, document required variables, decide on secret handling (.env file on Unraid, Portainer env vars, etc.)
• Database backup strategy — set up a simple scheduled backup for the PostgreSQL volume/data (e.g., cron + pg_dump script on Unraid)
• Document the deployment workflow — README or docs covering how to deploy, redeploy, rollback, and manage the production instance