Files

S 95eeb698da docs: fix stale counts and preflight check numbering

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>

2026-03-01 11:59:35 -05:00

3.1 KiB

Raw Blame History

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

3.1 KiB Raw Blame History