From e6646fc3e008106045b622b9f3ef150391f47128 Mon Sep 17 00:00:00 2001 From: Julian Tabel Date: Mon, 9 Feb 2026 16:29:28 +0100 Subject: [PATCH] Add deployment strategy epic bean Co-Authored-By: Claude Opus 4.6 --- ...locke-tracker-ahza--deployment-strategy.md | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 .beans/nuzlocke-tracker-ahza--deployment-strategy.md diff --git a/.beans/nuzlocke-tracker-ahza--deployment-strategy.md b/.beans/nuzlocke-tracker-ahza--deployment-strategy.md new file mode 100644 index 0000000..7cfbd49 --- /dev/null +++ b/.beans/nuzlocke-tracker-ahza--deployment-strategy.md @@ -0,0 +1,60 @@ +--- +# nuzlocke-tracker-ahza +title: Deployment Strategy +status: todo +type: epic +priority: normal +created_at: 2026-02-09T14:03:53Z +updated_at: 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 \ No newline at end of file