39 lines
4.4 KiB
Markdown
39 lines
4.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
## What this repo is
|
|
|
|
Git-based provisioning and recovery repo for the "argento" home server (Rocky Linux 9, ZFS, Docker). The repo lives at `/opt/argento/` on the server and contains the actual running configs. This dev copy at `~/dev/argento` is where edits happen, then synced to the server via git push/pull (Timothy runs the git commands).
|
|
|
|
Recovery steps are in `RUNBOOK.md`. Repo overview and workflows are in `README.md`.
|
|
|
|
## Architecture notes not in the docs
|
|
|
|
- **Docker shared network**: Created by the nginx compose file. All Docker apps that nginx proxies to join this network as `external: true`. If nginx compose hasn't been started, other apps will fail with "network shared not found".
|
|
- **nginx variable upstreams**: `nginx.conf` uses `resolver 127.0.0.11` (Docker DNS). Confs that proxy to container names use `set $upstream_<name>` variables so nginx resolves at request time, not startup. Without this, one down container prevents nginx from starting at all.
|
|
- **host.docker.internal**: Used for services running on the host network (Jellyfin, Cockpit). Requires `extra_hosts: ["host.docker.internal:host-gateway"]` in nginx's compose.yaml.
|
|
- **Jellyfin uses host network**: Needs direct access to NVIDIA GPU for hardware transcoding. Proxied via `host.docker.internal:8096`.
|
|
- **Cockpit (argento.timothykim.net)**: Runs directly on the host (not Docker) on port 9090 with self-signed TLS. The nginx conf inlines security headers instead of including security-headers.inc because Cockpit's internal iframes break with X-Frame-Options: DENY. Cockpit has a known bug where font files return 404 — this is not a proxy issue.
|
|
- **Minecraft HTTP-only**: HTTPS causes WebSocket/CORS errors with the MCSManager daemon. No cert issued for this domain.
|
|
- **SSL cert issuance chicken-and-egg**: On fresh recovery, certs don't exist so SSL confs can't load. The `.hold` pattern moves SSL confs aside, starts nginx with HTTP-only confs, issues certs, then restores SSL confs.
|
|
- **SELinux is enforcing**: Caused issues with samba (symlinks blocked, parent directory traversal blocked). Don't use symlinks for config files — use the sync-system.sh copy approach instead.
|
|
- **Secrets in .env files**: All secrets (DB passwords, API keys, tokens) live in `.env` files under each app's `docker/<app>/` directory on the server. These are gitignored (`**/.env` in root `.gitignore`). The `.env` files are included in the USB backup. If the backup is lost, all secrets can be recreated from Bitwarden. The `system/msmtprc` in the repo has its password REDACTED -- the real one is only on the server.
|
|
- **ZFS parent dataset mountpoints**: Pools have parent datasets (e.g., `nextcloud`, `threeteras`) that create mountpoints like `/mnt/nextcloud`. These are empty and expected — do not delete them.
|
|
- **msmtp**: Replaces sendmail for cron MAILTO and smartd email alerts. Configured via `/etc/msmtprc` (Fastmail SMTP). The symlink `/usr/sbin/sendmail -> /usr/bin/msmtp` is set up in recovery step 2.
|
|
- **Beszel agent**: System monitoring agent that reports to the beszel hub on hantim (`beszel.hantim.net`). Uses host network, listens on port 45876. No nginx proxy — it's not a web app.
|
|
- **Diun**: Watches all running containers daily at 06:00 for new image digests, emails via Fastmail SMTP (credentials in `docker/diun/.env`). State DB in `docker/diun/data/` tracks seen digests; `firstCheckNotif: false` suppresses the flood on first run after a restore.
|
|
- **hantim-server**: Sister repo with similar nginx/certbot patterns. Located at `~/dev/hantim-server`. Useful as reference for deploy patterns.
|
|
|
|
## Remotes
|
|
|
|
- **origin**: Gitea on argento (private). No offsite mirror — disaster recovery relies on the USB backup's copy of the Gitea bare repo.
|
|
|
|
## Working preferences
|
|
|
|
- Don't edit compose files in this repo — Timothy edits those directly on the server. Compose changes here get rejected.
|
|
- Comments in config files should explain the real WHY for this specific app, not generic descriptions of what a directive does.
|
|
- Don't add redundant documentation. If something is already on disk (e.g., crontab contents), don't repeat it in the docs.
|
|
- Keep docs linear and non-confusing. Avoid branching flows that duplicate steps.
|
|
- When proposing config changes, explain the flags/options — Timothy wants to understand what he's committing, not blindly trust it.
|
|
- No emojis in any files.
|
|
- Verify suggestions actually work before confidently recommending them. If unsure, say so.
|