docs: describe the servers as they are
The READMEs still tracked the 2025 migration from bare metal and listed Grafana, Immich, Valheim, Prosody and others that do not run. Replace them with what is deployed, how a change reaches production and where the secrets live. Assisted-by: Claude:fable-5-2
This commit is contained in:
parent
63bd67a86d
commit
e76d2a022c
2 changed files with 149 additions and 98 deletions
|
|
@ -1,60 +1,86 @@
|
|||
# ASXP.IO Ansible Infrastructure
|
||||
# Ansible
|
||||
|
||||
Automated deployment for asxpio servers: WireGuard VPN, SSH hardening, Traefik, Forgejo, and S3 storage.
|
||||
`site.yaml` is the desired state of both servers and is applied by the
|
||||
deploy pipeline on every push to `main`. The playbooks under
|
||||
`playbooks/` are host bootstrap and are run by hand.
|
||||
|
||||
## Quick Start
|
||||
## Running
|
||||
|
||||
```bash
|
||||
# 1. Setup vault
|
||||
echo "your-password" > .vault_pass && chmod 600 .vault_pass
|
||||
./scripts/setup-vault.sh encrypt
|
||||
```sh
|
||||
echo '<vault password>' > .vault_pass && chmod 600 .vault_pass
|
||||
|
||||
# 2. Stage 1: WireGuard VPN
|
||||
ansible-playbook playbooks/01-wireguard-setup.yaml
|
||||
# Connect to VPN, update inventory/hosts.yaml to use WireGuard IPs
|
||||
|
||||
# 3. Stage 2: Full deployment (SSH hardening, Traefik, Forgejo, Runner)
|
||||
ansible-playbook playbooks/02-full-deployment.yaml
|
||||
|
||||
# 4. Stage 3: S3 storage mounts
|
||||
ansible-playbook playbooks/03-setup-s3fs.yaml
|
||||
ansible-playbook site.yaml --check --diff # dry run, over WireGuard
|
||||
ansible-playbook site.yaml # apply
|
||||
ansible-playbook site.yaml --tags forgejo # one role
|
||||
```
|
||||
|
||||
## Infrastructure
|
||||
On NixOS: `nix shell nixpkgs#ansible -c ansible-playbook …`.
|
||||
|
||||
**Servers:**
|
||||
- **asxpio-ops** (CX22): Forgejo, Traefik, WireGuard VPN hub
|
||||
- **asxpio-services** (CX43): Forgejo Runner, Immich, game servers
|
||||
Templates that carry secrets are never shown in `--diff` output.
|
||||
|
||||
**Networks:**
|
||||
- VPC: 10.10.0.0/20
|
||||
- WireGuard: 10.20.0.0/24
|
||||
## Inventories
|
||||
|
||||
**S3 Buckets (mounted via s3fs):**
|
||||
- asxpio-terraform-main → /mnt/s3/terraform
|
||||
- asxpio-backups-main → /mnt/s3/backups
|
||||
- asxpio-immich-main → /mnt/s3/immich
|
||||
- `inventory/hosts.yaml`: default. Connects as root to the WireGuard
|
||||
addresses.
|
||||
- `inventory/ci.yaml`: used by the pipeline. Connects as `deploy` over
|
||||
the private network, reaching asxpio-services through asxpio-ops.
|
||||
|
||||
## Playbook Workflow
|
||||
`known_hosts` pins both servers' SSH host keys for the pipeline.
|
||||
|
||||
1. **WireGuard Setup** - Deploy VPN, generate client configs
|
||||
2. **Full Deployment** - SSH hardening (no lockout), Traefik, Forgejo, Runner
|
||||
3. **S3 Storage** - Mount S3 buckets with automatic cache management
|
||||
|
||||
All playbooks are idempotent - safe to rerun without breaking existing setup.
|
||||
|
||||
## Configuration Files
|
||||
## Variables
|
||||
|
||||
```
|
||||
inventory/
|
||||
├── hosts.yaml # Server inventory, IPs, groups
|
||||
├── group_vars/all/ # Variables applied to all hosts
|
||||
│ ├── main.yaml # Forgejo version, ports, runner config
|
||||
│ ├── network.yaml # VPC (10.10.0.0/20), WireGuard (10.20.0.0/24) IPs
|
||||
│ ├── services.yaml # Service paths (/opt/*), ports, Docker networks
|
||||
│ ├── s3.yaml # S3 buckets, mount points, credentials reference
|
||||
│ └── vault.yaml # ENCRYPTED: S3 keys, Forgejo secrets, runner token
|
||||
└── host_vars/ # Host-specific overrides
|
||||
├── asxpio-ops.yaml # WireGuard server, clients list, S3 cache: 10GB
|
||||
└── asxpio-services.yaml # S3 cache: 80GB
|
||||
├── group_vars/all/
|
||||
│ ├── network.yaml # VPC and WireGuard addresses
|
||||
│ ├── paths.yaml # /opt
|
||||
│ ├── s3.yaml # object storage buckets and s3fs mounts
|
||||
│ ├── wireguard.yaml # WireGuard peers
|
||||
│ └── vault.yaml # encrypted secrets
|
||||
├── group_vars/ops_servers/
|
||||
│ ├── traefik.yaml # traefik_version
|
||||
│ └── forgejo.yaml # forgejo_version, domain and aliases
|
||||
├── group_vars/services_servers/
|
||||
│ ├── forgejo_runner.yaml # runner version, labels' nix image
|
||||
│ └── minecraft.yaml
|
||||
└── host_vars/ # per-host addresses, SSH and s3fs settings
|
||||
```
|
||||
|
||||
Compose files without variables are plain files under
|
||||
`roles/<role>/files/`; edit the image tag there.
|
||||
|
||||
## Roles in site.yaml
|
||||
|
||||
`base`, `traefik`, `crawler_alert`, `forgejo`, `forgejo_runner`,
|
||||
`sillytavern`, `minecraft`, `minecraft_fossils`. Service roles go
|
||||
through `docker_service`, which writes the files, runs
|
||||
`docker compose up -d`, restarts on a config change and waits for the
|
||||
service to answer.
|
||||
|
||||
`crawler_alert` installs a copy of
|
||||
[traefik-crawlers-statistics](https://git.asxp.io/asxpi/traefik-crawlers-statistics);
|
||||
update `roles/crawler_alert/files/` from there.
|
||||
|
||||
## Bootstrap playbooks
|
||||
|
||||
| Playbook | Purpose |
|
||||
|----------|---------|
|
||||
| `01-wireguard-setup.yaml` | WireGuard hub on asxpio-ops, peer on asxpio-services, client configs |
|
||||
| `02-ssh-hardening.yaml` | restrict SSH to WireGuard and the private network |
|
||||
| `03-setup-s3fs.yaml` | s3fs mounts on asxpio-services (off on asxpio-ops) |
|
||||
| `04-add-user-zerrtika.yaml` | add a user to running servers |
|
||||
| `05-swap.yaml` | 2 GB swapfile on asxpio-ops |
|
||||
|
||||
Always dry-run these first with `--check --diff`.
|
||||
|
||||
- `03-setup-s3fs.yaml` rewrites `/etc/s3fs/.passwd-s3fs`, which the
|
||||
backup script on asxpio-ops also reads.
|
||||
- On asxpio-services the WireGuard interface is named
|
||||
`asxpio-services`, not `wg0`. Check `01-wireguard-setup.yaml` against
|
||||
the host before re-running it there.
|
||||
|
||||
## Runner notes
|
||||
|
||||
The `nix-latest` label runs `nixos/nix:<forgejo_runner_nix_version>`
|
||||
with a `nix-store-<version>` volume over `/nix`. To bump it: change the
|
||||
variable, let the pipeline apply it, then remove the old volume.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue