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-10T08:16:36Z

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). Deploy via SSH from the dev machine.

Decided Approach

Docker Compose + SSH + Gitea (source hosting, container registry)

1. Gitea runs on Unraid behind Nginx Proxy Manager with SSL (e.g., gitea.nerdboden.de). It serves as the self-hosted Git remote and container registry.
2. Images are built on the dev machine (podman or docker, cross-compiled for linux/amd64) and pushed to Gitea's container registry as user-level packages (e.g., gitea.nerdboden.de/thefurya/nuzlocke-tracker-api:latest, gitea.nerdboden.de/thefurya/nuzlocke-tracker-frontend:latest).
3. Production runs docker compose on Unraid at /mnt/user/appdata/nuzlocke-tracker/, pulling images from the Gitea container registry instead of mounting source.
4. A deploy script on the dev machine automates the full flow: build images → push to Gitea registry → SCP compose file to Unraid → generate .env if missing → SSH to pull images and (re)start containers.
5. Nginx Proxy Manager handles routing on the LAN (e.g., nuzlocke.nerdboden.de → frontend container, gitea.nerdboden.de → Gitea).
6. Database uses a bind mount (./data/postgres) for persistence on the Unraid disk; 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, deploys to Unraid via SSH)

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.nerdboden.de 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
• Create deploy script — ./deploy.sh builds images (podman/docker, linux/amd64), pushes to Gitea registry, SCPs compose file, generates .env if needed, pulls and starts containers via SSH
• Configure Nginx Proxy Manager — add proxy host entries for Gitea and the nuzlocke-tracker frontend/API on the appropriate ports
• Environment & secrets management — deploy script auto-generates .env with POSTGRES_PASSWORD on Unraid if missing; file lives at /mnt/user/appdata/nuzlocke-tracker/.env
• Implement Gitea Actions CI/CD pipeline — set up Gitea Actions runner on Unraid, create CI workflow (lint/test on develop) and deploy workflow (build/push/deploy on main); uses GitHub Actions-compatible syntax for portability
• Database backup strategy — set up a simple scheduled backup for the PostgreSQL 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