Julian Tabel
349a0cb821
Covers architecture overview, Gitea container registry setup, branching strategy, and deployment workflow. Sections not yet implemented are marked with TODO to be filled in as the deployment epic progresses. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
60 lines
4.8 KiB
Markdown
60 lines
4.8 KiB
Markdown
---
|
|
# nuzlocke-tracker-ahza
|
|
title: Deployment Strategy
|
|
status: in-progress
|
|
type: epic
|
|
priority: normal
|
|
created_at: 2026-02-09T14:03:53Z
|
|
updated_at: 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
|
|
- [x] **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 |