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	in-progress	epic	normal	2026-02-09T14:03:53Z	2026-02-09T16:53:58Z

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 + Gitea (source hosting, container registry, CI/CD)

1. Gitea runs on Unraid behind Nginx Proxy Manager with SSL (e.g., gitea.yourdomain.com). It serves as the self-hosted Git remote, container registry, and (optionally) CI/CD via Gitea Actions.
2. Images are built on the dev machine and pushed to Gitea's container registry as user-level packages (e.g., gitea.yourdomain.com/julian/nuzlocke-tracker-api:latest, gitea.yourdomain.com/julian/nuzlocke-tracker-frontend:latest).
3. Production runs docker-compose on Unraid, pulling images from the Gitea container 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 Gitea registry → trigger Portainer webhook to redeploy.
6. Nginx Proxy Manager handles routing on the LAN (e.g., nuzlocke.yourdomain.com → frontend container, gitea.yourdomain.com → Gitea).
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 Gitea 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)
• Configure Gitea container registry — create an access token with read:package and write:package scopes, verify docker login gitea.yourdomain.com works, test pushing and pulling an image as a user-level package
• Create production docker-compose file (docker-compose.prod.yml) — uses images from the Gitea container 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 Gitea registry, pushes them, and triggers the Portainer webhook to redeploy
• Configure Nginx Proxy Manager — add proxy host entries for Gitea and the nuzlocke-tracker frontend/API 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