From 37faf252dcea3f81da531f445bf7a9c417980e87 Mon Sep 17 00:00:00 2001 From: Timothy Kim Date: Wed, 29 Apr 2026 13:14:23 -0400 Subject: [PATCH] streamline README --- README.md | 70 +++++++++++++++---------------------------------------- 1 file changed, 19 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 6d4e62b..12306fb 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ docker/ Docker app configs (compose files, nginx confs) 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.) ``` @@ -38,13 +39,12 @@ system/ System config snapshots (smb.conf, sanoid.conf, firewalld, et ## Workflows -**Compose files** -- edit in `/opt/argento/`, apply, commit: +**Compose files** -- edit in `/opt/argento/`, apply: ```bash cd /opt/argento/docker/ vim compose.yaml docker compose up -d -git add . && git commit && git push ``` **System configs** -- edit in place, auto-synced daily: @@ -61,55 +61,24 @@ systemctl restart smb vim /opt/argento/docker/nginx/conf.d/.conf docker exec nginx nginx -t docker exec nginx nginx -s reload -git add . && git commit && git push ``` **Updating an app (Diun notification received):** -Diun emails when a watched image has a new digest on the registry. The email -names the image (e.g. `postgres:17-alpine`), not the container. To find which -container uses it: +Diun emails name the image (e.g. `postgres:17-alpine`), not the container. Find it: ```bash docker ps --filter "ancestor=:" --format '{{.Names}}' ``` - -Then apply the update from that app's directory: +Then update: ```bash cd /opt/argento/docker/ -docker compose pull +docker compose pull --ignore-buildable +docker compose build --pull # if repo contains dockerfile docker compose up -d -docker ps # verify container is healthy ``` - -Then smoke-test the app (open the UI, or `curl -I https://`). - -Caveats before pulling: - -- Diun only reports that a digest changed -- it does not say the update is safe. For apps with schema migrations (Nextcloud, Immich, Gitea, Postgres), skim the release notes first. -- For major version bumps, run `./scripts/backup.sh` manually before pulling so the USB has a fresh snapshot. -- Postgres major version bumps (e.g. 17 -> 18) cannot reuse the old data dir -- a plain `compose up -d` will fail to start. See [RUNBOOK.md](RUNBOOK.md#maintenance-postgres-major-version-upgrade). -- After several updates, reclaim disk with `docker image prune -f`. - -**Apps with a local Dockerfile:** - -Some compose files build their image locally instead of pulling a tagged one: - -| App | Service | Base image | Why | -|-----|---------|-----------|-----| -| `nextcloud` | `nextcloud` | `nextcloud:latest` | Adds smbclient + ffmpeg | -| `minecraft` | `daemon` | `githubyumao/mcsmanager-daemon:latest` | Adds Temurin 25 JRE | - -For these, plain `docker compose pull` fails on the buildable service ("pull access denied"). Use one of: - -```bash -docker compose pull --ignore-buildable # pull only registry-backed services -docker compose build --pull # rebuild, refreshing the FROM base -docker compose up -d --build # build + pull + recreate, one shot -``` - -Diun caveat: Diun watches the running container's image reference. Since these run as local images (e.g. `mcsmanager-daemon-java25`), the registry lookup has nothing to compare against -- **Diun will not notify when the base image updates**. Refresh these manually on your own cadence with `docker compose build --pull && 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:** @@ -118,7 +87,6 @@ Diun caveat: Diun watches the running container's image reference. Since these r 3. `./scripts/issue-cert.sh ` 4. `cp docker/nginx/conf.d/_template.conf.example docker/nginx/conf.d/.conf` and fill in placeholders 5. `docker exec nginx nginx -t && docker exec nginx nginx -s reload` -6. Commit and push ## Recovery @@ -126,15 +94,15 @@ See [RUNBOOK.md](RUNBOOK.md) for full disaster recovery steps. ## What's protected where -| Data | Protection | Recovery | -|------|-----------|----------| -| Configs (compose, nginx, system) | Git (Gitea bare repo on USB backup) | `git clone` from USB | -| Nextcloud files | ZFS mirror + sanoid snapshots + USB | `rsync` from USB | -| Media library | ZFS raidz2 + sanoid snapshots + USB | `rsync` from USB | -| Nextcloud DB (PostgreSQL) | ZFS dataset + `pg_dumpall` + USB | `rsync` from USB | -| Immich library (photos/videos) | ZFS raidz2 + sanoid snapshots + USB | `rsync` from USB | -| Immich DB (PostgreSQL) | `pg_dumpall` + USB | `rsync` from USB | -| Garage S3 data | 2-node replication + USB | Replication or USB | -| Gitea repos + DB | SQLite `.backup` + USB | `rsync` from USB | -| Secrets (.env files) | USB backup + Bitwarden | `rsync` from USB, or recreate from Bitwarden | -| SSL certificates | Re-issued from Let's Encrypt | `./scripts/issue-cert.sh` | +| 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 |