# argento

Configuration and recovery repo for the argento home server. This repo is the runbook -- it contains the actual config files and documents the manual steps between them.

- Rocky Linux 9 on NVMe
- ZFS storage (2 pools: `nextcloud` mirror, `threeteras` raidz2)
- Docker apps behind nginx reverse proxy
- Daily USB backup via rsync

## Repo structure

```
scripts/           Backup, cert issuance, health monitoring, system config sync
docker/            Docker app configs (compose files, nginx confs)
  nginx/           Reverse proxy + SSL termination
  nextcloud/       Nextcloud + PostgreSQL
  gitea/           Gitea + CI runner
  jellyfin/        Media server
  garage/          S3-compatible storage
  minecraft/       MCSManager
  immich/          Immich photo server + PostgreSQL
  beszel-agent/    System monitoring agent (reports to beszel.hantim.net)
  diun/            Daily image-digest watcher (emails when updates available)
smb/               Samba share (ZFS mountpoint, not in git)
system/            System config snapshots (smb.conf, sanoid.conf, firewalld, etc.)
```

## Key files

| File | Purpose |
|------|---------|
| `RUNBOOK.md` | Full recovery steps, top to bottom |
| `scripts/backup.sh` | Daily USB backup (DB dumps + rsync) |
| `scripts/issue-cert.sh` | Issue SSL certs via certbot webroot |
| `scripts/disk-health-check.sh` | SMART, ZFS, disk space monitoring (daily alerts + weekly reports via cron) |
| `scripts/sync-system.sh` | Auto-sync system configs to git |
| `system/tracked-configs` | Maps system config paths to repo paths |
| `docker/nginx/conf.d/_template.conf.example` | Template for new nginx app confs |

## Workflows

**Compose files** -- edit in `/opt/argento/`, apply:

```bash
cd /opt/argento/docker/<app>
vim compose.yaml
docker compose up -d
```

**System configs** -- edit in place, auto-synced daily:

```bash
vim /etc/samba/smb.conf
systemctl restart smb
# sync-system.sh runs via cron, or run manually: /opt/argento/scripts/sync-system.sh
```

**Nginx configs** -- edit in repo, reload:

```bash
vim /opt/argento/docker/nginx/conf.d/<domain>.conf
docker exec nginx nginx -t
docker exec nginx nginx -s reload
```

**Updating an app (Diun notification received):**

Diun emails name the image (e.g. `postgres:17-alpine`), not the container. Find it:

```bash
docker ps --filter "ancestor=<image>:<tag>" --format '{{.Names}}'
```
Then update:

```bash
cd /opt/argento/docker/<app>
docker compose pull --ignore-buildable
docker compose build --pull # if repo contains dockerfile
docker compose up -d
```
Postgres major version bumps (e.g. 17 -> 18) need extra steps -- see [RUNBOOK.md](RUNBOOK.md#maintenance-postgres-major-version-upgrade).

**Adding a new app:**

1. Create `docker/<app>/compose.yaml` with `container_name` and `shared` network
2. `docker compose up -d`
3. `./scripts/issue-cert.sh <domain>`
4. `cp docker/nginx/conf.d/_template.conf.example docker/nginx/conf.d/<domain>.conf` and fill in placeholders
5. `docker exec nginx nginx -t && docker exec nginx nginx -s reload`

## Recovery

See [RUNBOOK.md](RUNBOOK.md) for full disaster recovery steps.

## What's protected where

| Data | Protection |
|------|-----------|
| Configs (compose, nginx, system) | Git (Gitea bare repo on USB backup) |
| Nextcloud files | ZFS mirror + sanoid snapshots + USB |
| Media library | ZFS raidz2 + sanoid snapshots + USB |
| Nextcloud DB (PostgreSQL) | ZFS dataset + `pg_dumpall` + USB |
| Immich library (photos/videos) | ZFS raidz2 + sanoid snapshots + USB |
| Immich DB (PostgreSQL) | `pg_dumpall` + USB |
| Garage S3 data | 2-node replication + USB |
| Gitea repos + DB | SQLite `.backup` + USB |
| Secrets (.env files) | USB backup + Bitwarden |
| SSL certificates | Re-issued from Let's Encrypt |