95eeb698da
README.md: 10 templates→9, ~6500 lines→~8000, 25 checks→22, ~50 prompts→~65 CLAUDE.md: ~55 env vars→~70 PLAN.md: mark all tracker items DONE, fix Nginx→Caddy/SSL→TLS refs, add missing setup scripts and template entries USAGE_GUIDE.md: add configure_runners.sh mention, fix check 15→14 ref preflight.sh: renumber checks to fill gaps at 14 and 19 (now 1-22) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
62 lines
3.1 KiB
Markdown
62 lines
3.1 KiB
Markdown
# Gitea Migration Toolkit
|
|
|
|
## Project Overview
|
|
Bash-based automation toolkit for migrating 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**: Caddy reverse proxy with Cloudflare DNS-01 or existing certs (macvlan IP 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 (includes .env format validation)
|
|
- `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
|
|
|
|
## .env Validation
|
|
`validate_env()` in `lib/common.sh` checks all ~70 .env variables against their expected format (IP, port, email, path, URL, bool, integer, password, tls_mode, db_type). Uses parallel arrays for the variable-to-validator mapping (bash 3.2 compatible). Called by `preflight.sh` and `bitwarden_to_env.sh`. `configure_env.sh` uses the same individual validators interactively.
|
|
|
|
## 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
|