iac/ansible/README.md

# ASXP.IO Ansible

Post-cloud-init configuration for asxpio servers.

## Playbooks

### setup-servers.yaml
Post-deployment verification (cloud-init handles base setup).

```bash
ansible-playbook playbooks/setup-servers.yaml
```

### wireguard.yaml
Deploy WireGuard VPN server on asxpio-ops (10.20.0.10).

```bash
# Initial deployment
ansible-playbook playbooks/wireguard.yaml

# Add new clients to inventory/host_vars/asxpio-ops.yaml, then re-run
ansible-playbook playbooks/wireguard.yaml
```

Client configs fetched to `./wireguard-configs/asxpio-ops/`

### wireguard-client.yaml
Deploy WireGuard client configs to servers.

```bash
ansible-playbook playbooks/wireguard-client.yaml
```

Deploys asxpio-services.conf (10.20.0.20) to asxpio-services server.

### ssh-harden.yaml
Harden SSH configuration with network restrictions and strong cryptography.

```bash
ansible-playbook playbooks/ssh-harden.yaml
```

**Security measures:**
- Shell access (asxpi/deploy/root): Only from VPC (10.10.0.0/20) or WireGuard (10.20.0.0/24)
- Forgejo git user: Public access on asxpio-ops for git operations (ssh://forgejo@git.asxp.io/...)
- Strong crypto: ChaCha20-Poly1305, AES-GCM, RSA-SHA2, Ed25519
- iptables: SSH blocked on asxpio-services except from trusted networks
- Enhanced sshd_config: MaxAuthTries 3, MaxSessions 5, no X11 forwarding

**Access after hardening:**
- Admin access: Connect via WireGuard VPN first, then SSH
- Git operations: Public access to asxpio-ops (Forgejo handles authentication)
- Internal VPC: Servers can SSH to each other via 10.10.0.0/20

### deploy-traefik.yaml
Deploy Traefik reverse proxy with Let's Encrypt on asxpio-ops.

```bash
ansible-playbook playbooks/deploy-traefik.yaml
```

**Features:**
- Automatic HTTPS with Let's Encrypt (HTTP challenge)
- Dashboard accessible only via WireGuard (http://10.20.0.10:8080)
- Shared Docker network for service discovery
- Certificates stored in `/opt/traefik/letsencrypt/`
- Logs in `/opt/traefik/logs/`

### deploy-forgejo.yaml
Deploy fresh Forgejo Git server on asxpio-ops (no data migration).

```bash
ansible-playbook playbooks/deploy-forgejo.yaml
```

**Configuration:**
- Forgejo 12.x with SQLite database
- HTTP: port 3000 (internal), exposed via Traefik at git.asxp.io
- SSH: port 2222 (external) → 22 (container)
- Actions enabled with 365-day artifact retention
- LFS enabled, OAuth2 enabled
- Data stored in `/opt/forgejo/data/`

**Important:** Configure secrets in `inventory/host_vars/asxpio-ops.yaml`:
```yaml
forgejo_secret_key: "YOUR-SECRET-KEY"
forgejo_internal_token: "YOUR-INTERNAL-TOKEN"
forgejo_jwt_secret: "YOUR-JWT-SECRET"
forgejo_lfs_jwt_secret: "YOUR-LFS-JWT-SECRET"
letsencrypt_email: "admin@asxp.io"
```

### deploy-forgejo-runner.yaml
Deploy Forgejo Runner on asxpio-services for CI/CD.

```bash
ansible-playbook playbooks/deploy-forgejo-runner.yaml
```

**Configuration:**
- Forgejo Runner 11.x with Docker execution
- 14 pre-configured labels (ubuntu, debian, arch, node, python, nginx, alpine)
- Connects to Forgejo via VPC (http://10.10.0.10:3000)
- Requires manual registration after deployment

**Post-deployment registration:**
```bash
# 1. Get registration token from Forgejo:
#    Site Administration > Actions > Runners > Generate Token

# 2. Register the runner:
ssh asxpio-services
docker exec -it forgejo-runner forgejo-runner register --no-interactive \
  --token YOUR_REGISTRATION_TOKEN \
  --name runner-asxpio-services \
  --instance http://10.10.0.10:3000

# 3. Restart runner:
cd /opt/forgejo-runner && docker compose restart
```

### backup-forgejo.yaml
Backup Forgejo from old server (10.0.0.1).

```bash
ansible-playbook playbooks/backup-forgejo.yaml
```

**What it does:**
1. Stops Forgejo service temporarily
2. Creates dump: `forgejo dump -c /etc/forgejo/app.ini`
3. Creates additional archive of:
   - Database: `/srv/gitea/gitea.db`
   - Repositories: `/srv/gitea/data/`
   - SSH keys: `/var/lib/forgejo/.ssh/`
   - Runner registration: `/var/lib/forgejo-runner/.runner`
4. Fetches backups to local machine: `/tmp/forgejo-backups/`
5. Restarts Forgejo service

**Backup includes:** Database, repositories (~513MB), configuration, SSH keys, runner registration.

### restore-forgejo.yaml
Restore Forgejo backup to new server (10.20.0.10 via WireGuard).

```bash
ansible-playbook playbooks/restore-forgejo.yaml
```

**Prerequisites:**
- Traefik deployed and running
- Forgejo deployed (fresh instance)
- Backup files in `/tmp/forgejo-backups/`

**What it does:**
1. Stops Forgejo container
2. Extracts dump backup to `/opt/forgejo/`
3. Restores database, repositories, SSH keys
4. Sets correct ownership (UID 1000)
5. Starts Forgejo container
6. Waits for health check

**Post-restore verification:**
```bash
# Test web interface
curl -I https://git.asxp.io

# Test git clone
git clone https://git.asxp.io/asxpi/infrastructure.git

# Test SSH access
git clone git@git.asxp.io:asxpi/infrastructure.git
```

## Deployment Order

### Phase 1: Infrastructure (Prerequisites)
```bash
# 1. Deploy VPN
ansible-playbook playbooks/wireguard.yaml
ansible-playbook playbooks/wireguard-client.yaml

# 2. Harden SSH (Switch to WireGuard IP's in hosts.yaml before applying)
ansible-playbook playbooks/ssh-harden.yaml

# 3. Deploy reverse proxy
ansible-playbook playbooks/deploy-traefik.yaml
```

### Phase 2: Forgejo Fresh Deployment
```bash
# 4. Deploy Forgejo (empty instance)
ansible-playbook playbooks/deploy-forgejo.yaml

# 5. Deploy runner
ansible-playbook playbooks/deploy-forgejo-runner.yaml

# 6. Register runner (manual step - see instructions above)
```

### Phase 3: Data Migration (When Ready)
```bash
# 7. Backup from old server
ansible-playbook playbooks/backup-forgejo.yaml

# 8. Restore to new server
ansible-playbook playbooks/restore-forgejo.yaml

# 9. Update DNS: git.asxp.io → 65.109.14.216
# 10. Re-register runner with migrated instance
```

## Inventory

- **asxpio-ops** (65.109.14.216) - Traefik, Forgejo, monitoring, WireGuard server
- **asxpio-services** (95.217.19.240) - Forgejo Runner, Immich, game servers, XMPP