nuzlocke-tracker/DEPLOYMENT.md

Deployment

This document describes the deployment architecture and workflows for the nuzlocke-tracker.

Architecture Overview

Component	Dev (Laptop/PC)	Production (Unraid)
API	docker-compose.yml (hot reload)	docker-compose.prod.yml (built image)
Frontend	docker-compose.yml (Vite dev server)	docker-compose.prod.yml (nginx, static build)
Database	PostgreSQL 16 (Docker volume)	PostgreSQL 16 (bind mount)
Container Registry	—	Gitea (user-level packages)
Reverse Proxy	—	Nginx Proxy Manager
CI/CD	—	Gitea Actions

Services

• Gitea — self-hosted Git server, container registry, and CI/CD runner. Accessible at gitea.nerdboden.de via SSL.
• Nginx Proxy Manager — reverse proxy with SSL termination for all services on the Unraid server.

Branching Strategy

Branch	Purpose	Merge strategy
main	Always production-ready. Deploy workflow builds from here.	Merge commit from develop
develop	Integration branch for day-to-day work. CI runs on push.	Squash merge from feature/*
feature/*	Short-lived branches off develop for individual features/fixes.	—

Workflow

1. Create feature/xyz from develop
2. Work on the feature, commit, squash merge into develop
3. CI runs automatically on develop (lint checks)
4. When ready to deploy: merge develop into main (merge commit)
5. Trigger the deploy workflow via workflow_dispatch in Gitea Actions

CI/CD (Gitea Actions)

The project uses two Gitea Actions workflows (GitHub Actions-compatible syntax):

CI (.github/workflows/ci.yml)

Triggers: Push to develop, PRs targeting develop (skips bean-only changes)

Jobs:

• backend-lint — ruff check + ruff format --check
• frontend-lint — eslint + tsc -b

Deploy (.github/workflows/deploy.yml)

Triggers: Manual via workflow_dispatch (must be on main)

Steps:

1. Login to Gitea container registry
2. Build Docker images (linux/amd64) for API and frontend
3. Push images to the Gitea registry
4. SCP compose file and backup script to Unraid
5. SSH into Unraid and run docker compose pull && docker compose up -d

Secrets (configured in Gitea repo settings)

Secret	Purpose
REGISTRY_USERNAME	Gitea username for pushing images
REGISTRY_PASSWORD	Gitea access token (read:package + write:package scopes)
DEPLOY_SSH_KEY	SSH private key for root@192.168.1.10

Runner

An act_runner container runs on Unraid with the Docker socket mounted, registered with the Gitea instance.

Manual Deployment

The ./deploy.sh script can also be used to deploy from the dev machine:

# Ensure you're on main with latest changes
git checkout main
./deploy.sh

The script:

1. Checks you're on main with no uncommitted changes
2. Builds Docker images (podman or docker, linux/amd64)
3. Pushes to the Gitea container registry
4. SCPs docker-compose.prod.yml and backup.sh to Unraid
5. Generates .env with a random POSTGRES_PASSWORD if missing
6. Pulls images and restarts containers on Unraid via SSH

Container Registry

Images are hosted on Gitea's built-in container registry as user-level packages:

gitea.nerdboden.de/thefurya/nuzlocke-tracker-api:latest
gitea.nerdboden.de/thefurya/nuzlocke-tracker-frontend:latest

Authentication

1. Create a Gitea access token at Settings > Applications with read:package and write:package scopes.
2. Log in: docker login gitea.nerdboden.de (username + token as password).

Production Environment

File layout on Unraid

/mnt/user/appdata/nuzlocke-tracker/
├── docker-compose.yml    # production compose (synced from repo)
├── .env                  # POSTGRES_PASSWORD (auto-generated)
├── backup.sh             # database backup script (synced from repo)
├── backups/              # pg_dump backups (daily, 7-day retention)
│   └── cron.log
└── data/
    └── postgres/         # PostgreSQL data (bind mount)

Environment variables

The .env file is auto-generated on first deploy with a random POSTGRES_PASSWORD. The compose file references it for both the database and API connection string.

Database

PostgreSQL 16 with data persisted via bind mount at ./data/postgres/.

• Migrations run automatically on API container startup (alembic upgrade head)
• Daily backups via pg_dump scheduled through the Unraid User Scripts plugin (03:00, 7-day retention)

Backup

Backups are created by backup.sh and stored in /mnt/user/appdata/nuzlocke-tracker/backups/. The script is scheduled via the Unraid User Scripts plugin.

Restore

cd /mnt/user/appdata/nuzlocke-tracker
gunzip -c backups/nuzlocke-YYYYMMDD-HHMMSS.sql.gz | \
  docker compose exec -T db psql -U postgres nuzlocke

Rollback

Currently images are tagged as latest only. To roll back:

1. Revert the merge commit on main
2. Trigger the deploy workflow (or run ./deploy.sh) to rebuild and push

For more granular rollback, consider adding commit-hash tags to images in the future.

Nginx Proxy Manager

NPM runs on Unraid and handles SSL termination and routing:

• nuzlocke.nerdboden.de → nuzlocke-tracker frontend (port 9080)
• gitea.nerdboden.de → Gitea