# Gitea Migration Toolkit

## Project Overview
Bash-based automation toolkit for migrating 3 GitHub repos to self-hosted Gitea. All scripts run from MacBook, SSHing into Unraid (primary) and Fedora (backup mirror). GitHub serves as offsite push mirror.

## Architecture
- **Control plane**: MacBook runs all scripts locally, SSHs into remotes
- **Primary Gitea**: Docker Compose on Unraid
- **Backup Gitea**: Docker Compose on Fedora (pull mirrors)
- **Runners**: Docker on Unraid/Fedora, native binary + launchd on MacBook
- **HTTPS**: Nginx reverse proxy + Certbot on Unraid

## Script Conventions
- All `.sh` files MUST start with `set -euo pipefail`
- All scripts source `lib/common.sh` for shared functions
- All scripts MUST pass `shellcheck` with zero warnings
- All scripts MUST pass `bash -n` syntax check
- Configuration via `.env` file (never hardcode values)
- Templates use `.tpl` extension and `envsubst` for rendering
- Every phase has: main script + post_check + teardown

## Idempotency
Every create/deploy operation checks state first and skips if already done. Running any script twice produces the same result with no errors.

## File Structure
```
.env.example          # Template — copy to .env and fill in
runners.conf.example  # Template — copy to runners.conf
lib/common.sh         # Shared functions (source this in every script)
setup/                # Machine setup + .env wizard
templates/            # Config templates (.tpl files)
contracts/            # API endpoint documentation
backup/               # Backup and restore scripts
```

## Key Commands
- `setup/configure_env.sh` — Interactive .env setup wizard
- `setup/cleanup.sh` — Reverse everything setup scripts installed (reads .manifests/)
- `preflight.sh` — Validate everything before running phases
- `run_all.sh` — Execute all phases sequentially
- `teardown_all.sh` — Reverse teardown (add `--cleanup` to also uninstall prerequisites)
- `manage_runner.sh add|remove|list` — Dynamic runner management

## Version Checking
Setup scripts and preflight validate minimum versions for all tools:
- Local: jq>=1.6, curl>=7.70, git>=2.30, shellcheck>=0.8, gh>=2.0
- Remote: docker>=20.0, docker-compose>=2.0, jq>=1.6

## Install Manifests
Setup scripts record every install action to `.manifests/<host>.manifest`.
`setup/cleanup.sh` reads these manifests to fully reverse setup actions.
Useful for cleaning machines after testing or migrating to new servers.

## Sensitive Files (never commit)
- `.env` — contains passwords, tokens, IPs
- `runners.conf` — contains server IPs and paths
- `.manifests/` — machine-specific install state
- `*.pem`, `*.key`, `*.crt` — SSL certificates