From ad4ac6cf8c035a4aef2c8e4dc780fbe4853f6fb6 Mon Sep 17 00:00:00 2001 From: Julian Tabel Date: Mon, 9 Feb 2026 17:45:43 +0100 Subject: [PATCH] Update deployment strategy to use Gitea instead of plain Docker registry Gitea provides source hosting, container registry, and CI/CD in one package. Images are pushed as user-level packages to the Gitea registry over SSL. Co-Authored-By: Claude Opus 4.6 --- ...locke-tracker-ahza--deployment-strategy.md | 24 +++++++++---------- ...-set-up-local-docker-registry-on-unraid.md | 18 ++++++++------ 2 files changed, 23 insertions(+), 19 deletions(-) diff --git a/.beans/nuzlocke-tracker-ahza--deployment-strategy.md b/.beans/nuzlocke-tracker-ahza--deployment-strategy.md index 7cfbd49..49e2962 100644 --- a/.beans/nuzlocke-tracker-ahza--deployment-strategy.md +++ b/.beans/nuzlocke-tracker-ahza--deployment-strategy.md @@ -5,7 +5,7 @@ status: todo type: epic priority: normal created_at: 2026-02-09T14:03:53Z -updated_at: 2026-02-09T15:08:29Z +updated_at: 2026-02-09T16:44:13Z --- 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. @@ -20,14 +20,14 @@ Define and implement a deployment strategy for running the nuzlocke-tracker in p ## Decided Approach -**Docker Compose + Portainer + Local Docker Registry** +**Docker Compose + Portainer + Gitea (source hosting, container registry, CI/CD)** -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. +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 local registry → trigger Portainer webhook to redeploy. -6. **Nginx Proxy Manager** handles routing on the LAN (e.g., `nuzlocke.local` → frontend container). +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 @@ -42,19 +42,19 @@ Define and implement a deployment strategy for running the nuzlocke-tracker in p 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) +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`) -- [ ] **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 +- [ ] **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 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 +- [ ] **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 \ No newline at end of file diff --git a/.beans/nuzlocke-tracker-izf6--set-up-local-docker-registry-on-unraid.md b/.beans/nuzlocke-tracker-izf6--set-up-local-docker-registry-on-unraid.md index f33fc92..dfa6e45 100644 --- a/.beans/nuzlocke-tracker-izf6--set-up-local-docker-registry-on-unraid.md +++ b/.beans/nuzlocke-tracker-izf6--set-up-local-docker-registry-on-unraid.md @@ -1,16 +1,20 @@ --- # nuzlocke-tracker-izf6 -title: Set up local Docker registry on Unraid +title: Configure Gitea container registry status: todo type: task +priority: normal created_at: 2026-02-09T15:30:40Z -updated_at: 2026-02-09T15:30:40Z +updated_at: 2026-02-09T16:44:19Z parent: nuzlocke-tracker-ahza --- -Run a `registry:2` container on the Unraid server for storing production Docker images locally. +Set up and verify the Gitea container registry for hosting Docker images as user-level packages. -- Run `registry:2` as a Docker container on Unraid -- Configure a persistent storage volume for the registry data -- Optionally put it behind Nginx Proxy Manager with a hostname (e.g., `registry.local`) -- Verify pushing/pulling images from the dev machine works \ No newline at end of file +## Checklist + +- [ ] Create a Gitea access token with `read:package` and `write:package` scopes +- [ ] Verify `docker login gitea.yourdomain.com` works from the dev machine +- [ ] Test pushing a Docker image as a user-level package (e.g., `gitea.yourdomain.com/julian/nuzlocke-tracker-api:latest`) +- [ ] Verify the image appears under the user's Packages tab in Gitea +- [ ] Test pulling the image back (from Unraid or dev machine) \ No newline at end of file