From b17e7501213c873402f293d186c72cb4eee05946 Mon Sep 17 00:00:00 2001 From: John Gatward Date: Tue, 27 Oct 2026 12:21:10 +0000 Subject: [PATCH] tidy up notes --- docs/home-server/authentication.md | 283 +++++---------------- docs/home-server/backups.md | 160 ++++-------- docs/home-server/deployment.md | 173 +++++-------- docs/home-server/downloads.md | 225 ++++++----------- docs/home-server/host.md | 117 +++------ docs/home-server/ideas-next-steps.md | 229 ----------------- docs/home-server/index.md | 76 ++---- docs/home-server/mercury.md | 281 ++++----------------- docs/home-server/networking.md | 352 ++++++++------------------- docs/home-server/notes.md | 139 +++++------ docs/home-server/operations.md | 240 ++++-------------- docs/home-server/portainer.md | 92 +++---- docs/home-server/seedbox.md | 141 ++--------- docs/home-server/storage.md | 238 +++++------------- zensical.toml | 1 - 15 files changed, 669 insertions(+), 2078 deletions(-) delete mode 100644 docs/home-server/ideas-next-steps.md diff --git a/docs/home-server/authentication.md b/docs/home-server/authentication.md index 02c90ec..1c78c43 100644 --- a/docs/home-server/authentication.md +++ b/docs/home-server/authentication.md @@ -4,213 +4,90 @@ id: home-server.authentication type: reference scope: [jupiter, authentik, oidc, forward-auth, per-user-access, secrets] sensitivity: private-infrastructure -last_reviewed: "2026-10-26" +last_reviewed: "2026-10-27" sources: - kind: owner-report - reference: "Public qbittorrent.umbra.mom UI working through Mercury/Traefik/Authentik with native qBittorrent login retained, 2026-10-26; does not establish broader per-user migration completion" - - kind: owner-report - reference: "Requested removal of custom service-access groups, manual per-user application access and retained Jay administration, 2026-10-26; repository prepared, deployment unconfirmed" - - kind: owner-report - reference: "Requested Authentik-only Homarr login and read-only Docker socket proxy; deployment not confirmed, 2026-10-18" - - kind: owner-report - reference: "Homarr Authentik login created a separate account; requested linking to existing jay account, 2026-10-18" + reference: "Authentik deployed/Authelia retired 2026-10-16; Homarr login 2026-10-18; per-user policy and account linking still unconfirmed 2026-10-26" - kind: repository repository: jupiter-stacks - revision: 026cfa58b601165342b278401183c5fed5a50db2 - paths: - - stacks/homarr/docker-compose.yml - - stacks/homarr/.env.example - - stacks/authentik/docker-compose.yml - - stacks/authentik/blueprints/jupiter.yaml - - stacks/authentik/.env.example - - kind: owner-report - reference: "Authentik fully deployed, all listed app integrations complete and Authelia retired; OIDC and three-group motivation, 2026-10-16" - - kind: owner-report - reference: "Six-directory Backrest plan including Authentik and Wardrowbe; deployed Authentik container names confirmed, 2026-10-16" - - kind: owner-report - reference: "All stack environment values/secrets managed in Portainer; GitHub access uses PAT, 2026-10-06" - - kind: owner-report - reference: "Independent credential recovery unchanged: only restic key has independent custody, 2026-10-16" - - kind: repository - repository: jupiter-stacks - revision: d09df456ad331b8beb9a40615114ea8aae2dced5 - paths: - - stacks/authentik/docker-compose.yml - - stacks/authentik/blueprints/jupiter.yaml - - stacks/authentik/.env.example - - stacks/beszel/docker-compose.yml - - stacks/dozzle/docker-compose.yml - - stacks/gitea/docker-compose.yml - - stacks/immich/docker-compose.yml - - stacks/paperless-ngx/docker-compose.yml - - stacks/portainer/portainer_start.sh - - stacks/wardrowbe/docker-compose.yml - - stacks/backrest/docker-compose.yml - - stacks/notes/docker-compose.yml - - stacks/prowlarr/docker-compose.yml - - stacks/radarr/docker-compose.yml - - stacks/sonarr/docker-compose.yml -related: [home-server.reference, home-server.networking, home-server.portainer, home-server.backups, home-server.deployment] -update_triggers: [access-policy-change, authentication-change, secret-rotation, middleware-change] -unknowns: - - deployed-per-user-bindings-and-jay-superuser-membership - - per-application-local-login-and-account-linking-settings - - retired-authelia-data-retention + revision: 12fb1b96e01fc062fdce4c216f11eb5d7ce716ed + paths: [stacks/authentik/docker-compose.yml, stacks/authentik/blueprints/jupiter.yaml, stacks/authentik/.env.example, stacks/homarr/docker-compose.yml] +related: [home-server.networking, home-server.deployment, home-server.backups, home-server.portainer] +update_triggers: [access-policy-change, authentication-change, secret-rotation] +unknowns: [deployed-per-user-bindings-and-jay-superuser-membership, per-application-local-login-and-account-linking, retired-authelia-data-retention] --- # Authentication -Authentik replaces Authelia. The original setup used native OIDC and forward-auth -with three access groups. On 2026-10-26 the owner requested direct per-user -service access instead; the repository now prepares that migration, with `jay` -allowed into every configured application. Deployment is unconfirmed. -The owner reports the earlier Authentik migration -fully deployed as of 2026-10-16 and Authelia retired. Homarr OIDC login was -reported working on 2026-10-18; linking to the existing account is configured -in the repository but has not been confirmed successful. -Configuration details below are repository evidence, not live inspection. - -| Component | Configuration | -| --- | --- | -| Portal | `https://auth.umbra.mom` | -| Identity service | Authentik server + worker; image `2026.8.4` | -| Database | PostgreSQL 16; database/user `authentik` | -| Configuration | `stacks/authentik/blueprints/jupiter.yaml`; worker-mounted custom blueprint | -| Application MFA | `jupiter-app-authorization`; TOTP or WebAuthn; prompts for setup if none configured | -| Recent MFA | Five-minute reuse threshold avoids an immediate duplicate challenge | -| Host setup access | Loopback `127.0.0.1:9000` -> server `9000` | +- **Deployed:** Authentik replaces Authelia; portal `https://auth.umbra.mom`. +- **Repository intent, deployment unconfirmed:** direct per-user access and Homarr account linking. +- Backend: server + worker + PostgreSQL 16 (`authentik` DB/user). +- Blueprint: `stacks/authentik/blueprints/jupiter.yaml`; host copy must be applied separately. +- MFA: `jupiter-app-authorization`; TOTP/WebAuthn; setup if absent; five-minute reuse. +- Proxy transport/trust: [Networking](networking.md#listener-and-trust-boundaries). ## Per-user application access -Every one of the 15 configured applications has a direct binding for the -**existing** Authentik user `jay`, at order `0`. Applications use -`policy_engine_mode: any`: Jay **or** another explicitly added user may pass. -Unassigned users are denied, and the shared application-MFA flow remains. -The blueprint does not create users or change passwords, MFA devices or -application-native administrator roles. - -Add other users in the application's **Policy / Group / User Bindings** tab, -using a **User** binding with order `10` or higher, enabled and not negated. -Keep ANY mode and retain Jay's order-0 binding. Manual bindings at other orders -are not removed by blueprint reapplication. Admission does not itself grant -administrator privileges inside a service. - -The blueprint deletes only the custom `admins`, `development` and `clients` -groups after replacing their bindings; their memberships and group-based grants -are removed. **Retain Jay's built-in superuser group membership**, normally -`authentik Admins`: Authentik derives administrator status from a superuser -group, so removing every group would lock out administration. - -Before applying, back up Authentik, confirm Jay is still a superuser, and redeploy -Trek with its username-based admin mapping. Copy the updated blueprint into the -host's `/data/authentik/blueprints/jupiter.yaml` and apply it, then individually -assign the other users you want to retain. See the -[access-management runbook](https://github.com/jayo60013/jupiter-stacks/blob/main/stacks/authentik/README.md) -for rollout and rollback. Existing application sessions/API keys need separate -revocation when removing access. +- All 15 applications bind existing user `jay` at order `0`; `policy_engine_mode: any`. +- Add others under **Policy / Group / User Bindings**: enabled, non-negated **User** binding, order `10+`. Unassigned users are denied; manual higher-order bindings survive reapplication. +- Blueprint replaces custom `admins`, `development`, `clients` groups; does not create users or change passwords/MFA/app-native roles. +- **Keep Jay in the built-in superuser group** (`authentik Admins`); application admission is not administration. +- Before applying: back up Authentik, verify Jay's superuser membership, redeploy Trek's username-based admin mapping, copy/apply the host blueprint, assign retained users. +- Revoke existing application sessions/API keys separately when removing access. ## Native OIDC -Each client uses a confidential authorization-code provider, strict redirect URIs, -per-provider issuer and the shared application-MFA authorization flow. -Issuer pattern: `https://auth.umbra.mom/application/o//`. +- Confidential authorization-code clients; strict callbacks; shared MFA flow. +- Issuer: `https://auth.umbra.mom/application/o//`. -| Client ID | Application hostname | Integration configuration | +| Client ID | Host under `umbra.mom` | Configuration | | --- | --- | --- | -| `beszel` | `beszel.umbra.mom` | Database/UI provider; password-auth disable flag in Compose | -| `dozzle` | `logs.umbra.mom` | Compose OIDC settings; no forward-auth middleware | -| `gitea` | `gitea.umbra.mom` | Database/UI authentication source; Compose requires login for account linking and disables automatic registration | -| `homarr` | `umbra.mom` | Compose OIDC settings; Authentik-only login configured; verified-email linking to existing password accounts enabled | -| `immich` | `photos.umbra.mom` | Database/UI OAuth settings; web and mobile callbacks registered | -| `paperless` | `paperless.umbra.mom` | Compose OpenID Connect/allauth configuration; PKCE enabled; signups disabled | -| `portainer` | `portainer.umbra.mom`, `portainer.local.umbra.mom` | Database/UI OAuth settings; both callback hosts registered | -| `trek` | `holidays.umbra.mom` | Compose OIDC settings; `preferred_username == jay` grants the app admin role | -| `wardrowbe` | `wardrobe.umbra.mom` | Compose OIDC settings for frontend and backend/workers | +| `beszel` | `beszel` | Database/UI provider; password-disable flag in Compose | +| `dozzle` | `logs` | Compose OIDC; `dozzle_roles: ["none"]`; read-only Docker proxy | +| `gitea` | `gitea` | Database/UI source; login required for linking; auto-registration disabled | +| `homarr` | Apex | Compose OIDC; verified-email linking | +| `immich` | `photos` | Database/UI OAuth; web + mobile callbacks | +| `paperless` | `paperless` | Compose allauth/OIDC; PKCE; signups disabled | +| `portainer` | `portainer`, `portainer.local` | Database/UI OAuth; both callback hosts | +| `trek` | `holidays` | Compose; `preferred_username == jay` grants app admin | +| `wardrowbe` | `wardrobe` | Compose frontend/backend/workers | -Dozzle's custom profile mapping emits `dozzle_roles: ["none"]` for any user -admitted by its direct application bindings. Its Docker proxy stays read-only. -The email mapping asserts `email_verified` only when the user has -an email and their `email_verified` attribute is explicitly true. - -OIDC integration does not prove local password login is disabled or application -roles are synchronized. Beszel and Paperless retain migration-safe local-login -defaults in Compose; deployed overrides and account-linking details were not -supplied. Application permissions and existing sessions remain app-managed. +- Beszel/Paperless retain migration-safe local-login defaults; deployed overrides unconfirmed. +- OIDC does not synchronise native app roles or prove local login disabled. +- Email mapping emits `email_verified` only for an existing email with explicit boolean `true`. ### Homarr -Homarr uses native OIDC, not a Traefik forward-auth gate. Its Authentik provider -is `jupiter-homarr`, with the shared application-MFA flow. - | Setting | Value | | --- | --- | -| Login providers | `AUTH_PROVIDERS=oidc` (Authentik only) | -| Issuer | `https://auth.umbra.mom/application/o/homarr/` | -| Client ID / display name | `homarr` / `Authentik` | -| Callback | `https://umbra.mom/api/auth/callback/oidc` (strict match) | -| Requested scopes | `openid email profile` | -| Client secret | `OIDC_HOMARR_SECRET` in both the Homarr and Authentik stack environments | -| Existing-account linking | `AUTH_OIDC_ENABLE_DANGEROUS_CREDENTIALS_LINKING=true` | +| Provider / login | `jupiter-homarr`; `AUTH_PROVIDERS=oidc` | +| Callback | `https://umbra.mom/api/auth/callback/oidc` | +| Scopes | `openid email profile` | +| Shared secret | `OIDC_HOMARR_SECRET` in Homarr + Authentik | +| Linking | `AUTH_OIDC_ENABLE_DANGEROUS_CREDENTIALS_LINKING=true` | -An OIDC login initially created a separate user instead of signing into the -existing `jay` password account. Linking is now enabled in Compose; it matches -email addresses, not usernames, and preserves the existing account's username, -password credentials, permissions, boards, settings and API keys. Password -credentials are retained but cannot be used while only OIDC is enabled. +- Linking matches **email**, not username; applies to all matching password accounts. +- Preserve `SECRET_ENCRYPTION_KEY`; password credentials remain stored but unusable with OIDC-only login. -To complete linking: +1. Back up `/data/homarr/appdata`; ensure existing `jay` email matches the intended identity. +2. Independently verify ownership, then set that user's `email_verified` to boolean `true`; never mark all users verified. +3. Preserve/transfer duplicate-account data, then delete **only the duplicate OIDC account**, not `jay`; an existing link otherwise wins. +4. Confirm login reaches `jay`, admin permissions and existing boards before disabling credentials. Temporarily use `AUTH_PROVIDERS=credentials,oidc` if needed. -1. Before deploying Authentik-only login, back up `/data/homarr/appdata`, then - sign in with the local administrator account and ensure `jay`'s email exactly - matches the intended Authentik user's. -2. Independently verify ownership of that email before setting the Authentik - user's `email_verified` attribute to boolean `true`, not string `"true"`. - The existing email scope mapping requires this before issuing - `email_verified: true`; do not mark every user's email verified. -3. Preserve or transfer anything owned by the duplicate OIDC account, then - delete only that duplicate through Homarr's user management. Do not delete - `jay`. An existing OIDC link otherwise continues using the duplicate. -4. Confirm Authentik login links to `jay` with administrator access and the - existing boards and permissions before disabling password login. If linking - still needs setup, temporarily use `AUTH_PROVIDERS=credentials,oidc` and - redeploy. Once working, pull/redeploy with `AUTH_PROVIDERS=oidc`. - -The linking setting applies to all matching password accounts, not just `jay`. -Only trusted administrators should mark Authentik emails verified. Password login -is disabled in the current Compose configuration; successful deployment and -account linking have not been confirmed. For recovery if Authentik is unavailable, -temporarily restore `AUTH_PROVIDERS=credentials,oidc` and redeploy Homarr. -That recovery setting bypasses Authentik MFA and application-access policies -for password logins. Keep `SECRET_ENCRYPTION_KEY` unchanged. - -Homarr also has a read-only Docker socket proxy on an internal `docker-api` -network. Only the proxy mounts `/var/run/docker.sock`; its API port is not -published or connected to Traefik. Homarr's `Jupiter` endpoint permits inventory -and logs, while the proxy blocks writes (`POST=0`). Container lifecycle controls -are disabled. Redeploy the whole stack to create the proxy alongside Homarr. +- Credential fallback bypasses Authentik MFA/access policy for password logins. +- Internal `docker-api` proxy: only proxy mounts socket; no published API/Traefik attachment; inventory/logs allowed, `POST=0`, lifecycle controls disabled. Redeploy the whole stack. ## Forward-auth -Backrest (`backups.umbra.mom`), Notes, Prowlarr, Radarr and Sonarr retain -proxy-based protection. Their routers attach `authentik@docker`: +- Protected apps: Backrest (`backups`), Notes, Prowlarr, Radarr, Sonarr, qBittorrent. +- Router middleware: `authentik@docker`; `trustForwardHeader=true`. +- Endpoint: `http://authentik-server:9000/outpost.goauthentik.io/auth/traefik`. +- Six embedded `forward_single` providers; explicit external hosts, empty `skip_path_regex`. +- Priority **1000** callback router: `/outpost.goauthentik.io/` goes directly to Authentik, bypassing forward-auth. +- qBittorrent keeps native login; internal Arr API traffic bypasses this browser gate. +- Only attached routers are protected; published ports, SSH and API tokens are separate boundaries. -```text -Traefik -> http://authentik-server:9000/outpost.goauthentik.io/auth/traefik -``` - -The blueprint now includes a sixth `forward_single` provider for -`qbittorrent.umbra.mom`, with a direct `jay` user binding and the shared MFA flow. -The owner confirms its public UI and both authentication layers are working -on 2026-10-26. This confirmation is specific to qBittorrent, not proof that the -broader per-user access migration is complete. qBittorrent retains its own password login, and internal Arr API -connections do not pass through Authentik. See [Local downloads](downloads.md). - -The embedded-outpost blueprint lists six `forward_single` providers, each with an -explicit external host and empty `skip_path_regex`. A priority-1000 router -on those hosts sends `/outpost.goauthentik.io/` directly to Authentik, -bypassing forward-auth so callbacks can complete. - -`trustForwardHeader=true`; forwarded response headers: +Forwarded response headers: ```text X-authentik-username, X-authentik-groups, X-authentik-entitlements, @@ -219,50 +96,16 @@ X-authentik-meta-jwks, X-authentik-meta-outpost, X-authentik-meta-provider, X-authentik-meta-app, X-authentik-meta-version ``` -Forward-auth applies only to attached routers. Authentik is not a global gate -for every service, directly published port, SSH connection or API token. - ## State / secrets | Host path | Container use | | --- | --- | -| `/data/authentik/postgres` | PostgreSQL `/var/lib/postgresql/data`; identity, policy and MFA state | -| `/data/authentik/data` | Server + worker `/data`; persistent files | -| `/data/authentik/blueprints` | Worker `/blueprints/custom:ro`; host copy of repository blueprint | +| `/data/authentik/postgres` | PostgreSQL `/var/lib/postgresql/data` | +| `/data/authentik/data` | Server + worker `/data` | +| `/data/authentik/blueprints` | Worker `/blueprints/custom:ro` | -Stack variable overrides/secrets are managed in Portainer; Compose retains -non-secret configuration. Required Authentik stack secrets: - -```text -AUTHENTIK_SECRET_KEY -AUTHENTIK_DB_PASSWORD -OIDC_BESZEL_SECRET -OIDC_DOZZLE_SECRET -OIDC_GITEA_SECRET -OIDC_HOMARR_SECRET -OIDC_IMMICH_SECRET -OIDC_PAPERLESS_SECRET -OIDC_PORTAINER_SECRET -OIDC_WARDROWBE_SECRET -``` - -Client secrets are independently generated plaintext credentials, not old -Authelia password hashes. The worker passes them to blueprint `!Env` entries. -Keep each provider secret matched to its application configuration: -Homarr uses `OIDC_HOMARR_SECRET`, Dozzle uses `DOZZLE_OIDC_CLIENT_SECRET`, Paperless -`PAPERLESS_OIDC_CLIENT_SECRET`, and Wardrowbe `WARDROWBE_OIDC_CLIENT_SECRET`. -Other clients store provider configuration in their databases/UIs. - -Public Traefik routing defaults off (`AUTHENTIK_PUBLIC_ROUTING=false`) for -private initial setup; enable only after securing the administrator account. -The owner reports public deployment complete; this default is not deployed state. -See [deployment](deployment.md) for the configuration surfaces and order. - -`/data/authentik` and [Portainer state](portainer.md) are included in -[Backrest](backups.md). Backups stop Authentik server/worker and PostgreSQL; -new OIDC logins and forward-auth access are unavailable during that stop. -Recovery remains untested, with no independent admin/MFA or stack-secret -recovery arrangement; only the restic key has independent custody. -Retention/deletion of retired `/data/authelia` data is unconfirmed. -GitHub repository access uses a PAT; host SSH keys and tunnel credential files -are separate from stack environment variables. +- `authentik-data`: internal DB/server/worker network; worker also uses `authentik-egress`, server uses `traefik`. Internal DB network does not imply full egress isolation. +- Secret inventory: `stacks/authentik/.env.example`; values in Portainer, consumed through `!Env`. Do not reuse Authelia hashes as client secrets. +- Match provider/application credentials: Homarr `OIDC_HOMARR_SECRET`; Dozzle `DOZZLE_OIDC_CLIENT_SECRET`; Paperless `PAPERLESS_OIDC_CLIENT_SECRET`; Wardrowbe `WARDROWBE_OIDC_CLIENT_SECRET`. +- Initial setup: `AUTHENTIK_PUBLIC_ROUTING=false`, SSH-forwarded `127.0.0.1:9000`; secure admin/MFA before public routing, prove OIDC before disabling local logins. +- Backup coverage, login downtime and credential recovery: [Backups](backups.md). diff --git a/docs/home-server/backups.md b/docs/home-server/backups.md index fe10c38..941a181 100644 --- a/docs/home-server/backups.md +++ b/docs/home-server/backups.md @@ -4,156 +4,80 @@ id: home-server.backups type: reference scope: [jupiter, backrest, restic, google-drive, recovery] sensitivity: private-infrastructure -last_reviewed: "2026-10-26" +last_reviewed: "2026-10-27" sources: - kind: owner-report - reference: "Live AirVPN downloads; qBittorrent state/defaults and AirVPN WireGuard secrets not yet added to encrypted off-host backups, 2026-10-26" - - kind: owner-report - reference: "Backrest plan JSON, destination, key custody and no restore test, 2026-10-06" - - kind: owner-report - reference: "Updated four-service Backrest plan and deployed Portainer bind mount/container name, 2026-10-06" - - kind: owner-report - reference: "Only restic key has independent custody; no independent credential recovery or backup/restore evidence, 2026-10-06" - - kind: owner-report - reference: "Updated six-directory Backrest plan including Authentik and Wardrowbe, deployed Authentik hook container names confirmed; independent recovery custody unchanged, 2026-10-16" - - kind: owner-report - reference: "Backrest notifications received in Discord server Jupiter, channel #backrest-alerts, 2026-10-23" + reference: "Plan/hooks/key custody 2026-10-06; six-directory plan and Authentik names 2026-10-16; downloads not backed up 2026-10-26; no restore evidence" - kind: repository repository: jupiter-stacks revision: d09df456ad331b8beb9a40615114ea8aae2dced5 - paths: - - stacks/backrest/docker-compose.yml - - stacks/gitea/docker-compose.yml - - stacks/paperless-ngx/docker-compose.yml - - stacks/vaultwarden/docker-compose.yml - - stacks/authentik/docker-compose.yml - - stacks/wardrowbe/docker-compose.yml -related: [home-server.reference, home-server.downloads, home-server.storage, home-server.portainer, home-server.authentication, home-server.operations] + paths: [stacks/backrest/docker-compose.yml, stacks/authentik/docker-compose.yml, stacks/wardrowbe/docker-compose.yml] +related: [home-server.storage, home-server.downloads, home-server.authentication, home-server.operations] update_triggers: [backup-plan-change, destination-change, hook-change, credential-change, restore-test] -unknowns: - - last-successful-backup-and-repository-check - - google-drive-repository-path - - measured-rpo-and-rto +unknowns: [last-successful-backup-and-check, google-drive-repository-path, measured-rpo-and-rto] --- # Backups | Setting | Value | | --- | --- | -| Engine | Backrest / restic; plan `jupiter-backup` | -| Repository | `jayo60013-gdrive`; Google Drive; account `jayo60013` | -| Schedule | `0 3 * * *`; UTC; daily 03:00 | -| Retention | `policyKeepLastN: 4`; last four snapshots, not four days | -| Encryption key | iCloud password app; no key stored here | -| Independent credential recovery | None beyond the restic encryption key | -| Backup / integrity evidence | None supplied | -| Restore test | Never performed | - -## Notifications - -Backrest notifications are delivered to **Jupiter** (Discord server) in -`#backrest-alerts`; receipt confirmed by the owner on 2026-10-23. -Exact enabled hook conditions have not been recorded. Delivery alone does not -confirm backup integrity, successful application restarts or detection of a -backup that never runs. See [Observability](operations.md#observability) for -the shared notification destinations and remaining coverage gaps. +| Engine / plan | Backrest + restic / `jupiter-backup` | +| Repository | `jayo60013-gdrive`; Google Drive account `jayo60013` | +| Schedule | `0 3 * * *`, UTC | +| Retention | `policyKeepLastN: 4`: four **snapshots**, not days | +| Key custody | iCloud password app; only independently held recovery secret | +| Evidence | No successful backup/integrity evidence supplied; restore never exercised | ## Coverage -Backrest bind-mounts host `/data` at container `/userdata:ro`. - -| Host source | Plan path | -| --- | --- | -| `/data/authentik` | `/userdata/authentik` | -| `/data/gitea` | `/userdata/gitea` | -| `/data/paperless-ngx` | `/userdata/paperless-ngx` | -| `/data/portainer` | `/userdata/portainer` | -| `/data/vaultwarden` | `/userdata/vaultwarden` | -| `/data/wardrowbe` | `/userdata/wardrowbe` | - -Case-insensitive exclusions: `/userdata/gitea/gitea/packages`, -`/userdata/wardrowbe/redis`. -`excludes: []`; CLI `--skip-if-unchanged` supplied despite -plan `skipIfUnchanged: false`. Unchanged runs may create no snapshot. +- Backrest sees `/data` as `/userdata:ro`; **only** these six directories are selected: + `authentik`, `gitea`, `paperless-ngx`, `portainer`, `vaultwarden`, `wardrowbe`. +- Case-insensitive exclusions: `/userdata/gitea/gitea/packages`, `/userdata/wardrowbe/redis`. +- `excludes: []`; CLI `--skip-if-unchanged` despite plan `skipIfUnchanged: false`; unchanged runs may create no snapshot. ### Local-downloads recovery gap -The owner confirms on 2026-10-26 that the live [AirVPN download stack](downloads.md) -has **not** yet been added to encrypted off-host backups. Missing recovery state: -`/data/qbittorrent/config` (settings/torrent state), -`/data/qbittorrent/defaults` (defaults and startup/resolver files), and -`/data/gluetun/secrets` (WireGuard private/preshared keys). The reserved peer -port, tunnel address and server-country settings also need recoverable -deployment configuration; no secret values belong in these notes. - -Torrent payloads and media libraries remain outside the six-directory plan. -Hardlinks are not backups. Ultra.cc is retired and is no longer a remote -source to assume during recovery. Removing `rclone-seedbox.service` does not -remove Backrest's separate Google Drive/rclone dependency. +- [qBittorrent config/defaults and AirVPN keys](downloads.md#state-and-redeployment) are **not backed up** as of 2026-10-26. +- Keep address/country/reserved-port configuration recoverable alongside encrypted keys; never put key values here. +- Torrent payloads/media are also outside the plan. Retired Ultra.cc is not a recovery source. +- Backrest's Google Drive/rclone dependency is separate from the removed seedbox mount. ## Consistency hooks -Stop timeout `120s`; chains use `&&`. Errors: `ON_ERROR_FATAL`, -except Portainer, Wardrowbe and Authentik restart hooks (`ON_ERROR_IGNORE`). -Rows below group the supplied hooks by service; the plan lists Wardrowbe's -hooks before Authentik's. +- Cold filesystem copies, not DB dumps; stop timeout **120s**, ordered chains use `&&`. +- Default failure: `ON_ERROR_FATAL`. Portainer/Wardrowbe/Authentik **restart** failures: `ON_ERROR_IGNORE`. -| Event | Ordered commands / containers | -| --- | --- | -| `SNAPSHOT_START` | Stop `paperless` -> `paperless_db` | -| `SNAPSHOT_START` | Stop `gitea_runner` -> `gitea` -> `gitea_db` | -| `SNAPSHOT_START` | Stop `vaultwarden` | -| `SNAPSHOT_START` | Stop `portainer` | -| `SNAPSHOT_END`, `SNAPSHOT_ERROR` | Start `paperless_db` -> `paperless` | -| `SNAPSHOT_END`, `SNAPSHOT_ERROR` | Start `gitea_db` -> `gitea` -> `gitea_runner` | -| `SNAPSHOT_END`, `ANY_ERROR` | Start `vaultwarden` | -| `SNAPSHOT_END`, `SNAPSHOT_ERROR` | Start `portainer`; ignore hook failure | -| `SNAPSHOT_START` | Stop `wardrowbe-frontend`, `wardrowbe-backend`, `wardrowbe-worker`, `wardrowbe-image-worker` in one command -> stop `wardrowbe-postgres`, `wardrowbe-redis` | -| `SNAPSHOT_END`, `SNAPSHOT_ERROR` | Start `wardrowbe-postgres`, `wardrowbe-redis` -> wait for PostgreSQL and Redis -> start backend, worker, image-worker, frontend; ignore hook failure | -| `SNAPSHOT_START` | Stop `authentik-server`, `authentik-worker` in one command -> stop `authentik-postgresql` | -| `SNAPSHOT_END`, `SNAPSHOT_ERROR` | Start `authentik-postgresql` -> wait for PostgreSQL -> start `authentik-server`, `authentik-worker`; ignore hook failure | +| Service | `SNAPSHOT_START` stop order | Restart order / event | +| --- | --- | --- | +| Paperless | `paperless` -> `paperless_db` | DB -> app; `SNAPSHOT_END`, `SNAPSHOT_ERROR` | +| Gitea | `gitea_runner` -> `gitea` -> `gitea_db` | DB -> app -> runner; end/error | +| Vaultwarden | `vaultwarden` | Start; `SNAPSHOT_END`, `ANY_ERROR` | +| Portainer | `portainer` | Start; end/error; failure ignored | +| Wardrowbe | frontend/backend/worker/image-worker together -> postgres/redis | DB/cache -> readiness waits -> apps; end/error; failure ignored | +| Authentik | `authentik-server`, `authentik-worker` -> `authentik-postgresql` | DB -> readiness wait -> server/worker; end/error; failure ignored | -Cold filesystem copies of applications/databases; no database dumps supplied. -Paperless broker stays running. Paperless/Gitea restart chains use `docker start` -without waiting for database readiness. - -Wardrowbe waits inside the containers using `pg_isready -U wardrowbe -d wardrowbe` -then `redis-cli ping`; Authentik uses `pg_isready -U authentik -d authentik`. -These are `until` loops with two-second sleeps and no explicit deadline in the -commands. Starting multiple application containers in one command does not -establish application readiness or dependency ordering. - -The owner confirms the three Authentik hook names match deployed containers. -Repository Compose explicitly names only `authentik-server`; worker/database -names must be preserved or the hooks updated when recreating the stack. - -Hook failure can leave services stopped; Portainer, Wardrowbe and Authentik -restart failures do not fail the backup operation. Authentik downtime also -interrupts new OIDC logins and proxy-protected access, including the Backrest UI. -Application readiness and recovery are not demonstrated by the plan. +- Wardrowbe names use `wardrowbe-` prefix; hooks precede Authentik's in the supplied plan. +- Waits: `pg_isready -U wardrowbe -d wardrowbe`, `redis-cli ping`; Authentik `pg_isready -U authentik -d authentik`; 2s polling, no explicit deadline. +- Paperless broker stays running; Paperless/Gitea use `docker start` without DB readiness waits. +- Preserve deployed Authentik worker/DB names or update hooks; only server has explicit Compose name. +- Authentik stops interrupt new OIDC/proxy logins, including Backrest access. +- **Backup completion does not prove service recovery**; ignored restart errors can leave apps down. [Notifications](operations.md#observability) do not prove integrity/readiness. ## Backrest state | Host path | Container path | | --- | --- | | `/data/backrest/data` | `/data` | -| `/data/backrest/config` | `/config`; plan/repository configuration `config.json` | +| `/data/backrest/config` | `/config`; `config.json` plan/repository settings | | `/data/backrest/rclone` | `/root/.config/rclone` | | `/home/jay/data/backrest/cache` | `/cache` | | `/data/backrest/restore` | `/restore` | -| `/var/run/docker.sock` | `/var/run/docker.sock`; lifecycle hooks | +| `/var/run/docker.sock` | Same path; lifecycle hooks | ## Recovery limits -Only the six listed directories are covered, subject to the exclusions above. -Authentik identity/MFA state and Wardrowbe PostgreSQL/uploads are included; -Wardrowbe Redis is excluded. SSD-backed Wardrowbe model/cache paths are outside -the plan. No supplied coverage for Traefik, Backrest configuration, Docker named -volumes, OS, or Mercury. Authelia is retired; old data retention is unconfirmed. - -Full-host recovery requires independently retrievable repository credentials, -configuration and restic key. Key custody alone does not establish recoverability. -No independent Google Drive/rclone credential recovery or Backrest-config -recovery arrangement exists. Recovering backed-up Portainer state is not a -substitute for first being able to retrieve the backup. -`/restore` is on the same RAID array; not an independent backup. +- No supplied coverage for Backrest config, Traefik, OS/host config, Mercury, named volumes or SSD model/cache paths. Wardrowbe Redis explicitly excluded. +- No independent Git/PAT, stack-secret, Authentik admin/MFA or Google Drive/rclone recovery arrangement; restic key alone cannot retrieve backups. +- Proposed, **not implemented**: sanitised host/bootstrap config in private Git; encrypted off-host credential/config archive; independently usable access/decryption instructions. +- Restore/retrieval must work without Jupiter or Portainer; recovering Portainer's DB cannot bootstrap access to an inaccessible backup. +- `/restore` is on the same RAID array, not an independent copy. RPO/RTO and full-host recovery order remain unproven. diff --git a/docs/home-server/deployment.md b/docs/home-server/deployment.md index 3f9bf7c..1200607 100644 --- a/docs/home-server/deployment.md +++ b/docs/home-server/deployment.md @@ -4,137 +4,78 @@ id: home-server.deployment type: reference scope: [jupiter, portainer, github, stack-deployment, secrets] sensitivity: private-infrastructure -last_reviewed: "2026-10-26" +last_reviewed: "2026-10-27" sources: - kind: owner-report - reference: "AirVPN local downloads and public authenticated qBittorrent UI live; Ultra.cc/rclone retired; encrypted download-state/secret backups not yet added, 2026-10-26" + reference: "Portainer Git/PAT/manual deployment 2026-10-06; Authentik deployed 2026-10-16; downloads deployed 2026-10-26; ingress runbook completed 2026-10-27" - kind: repository repository: jupiter-stacks - revision: working-tree - base_revision: 631e4fdfa4c7122e5eff38e11b070c17ff7a4a2a - paths: - - stacks/downloads/docker-compose.yml - - stacks/downloads/README.md - - stacks/sonarr/docker-compose.yml - - stacks/radarr/docker-compose.yml - - stacks/prowlarr/docker-compose.yml - - stacks/traefik/docker-compose.yml - - kind: repository - repository: jupiter-stacks - revision: 026cfa58b601165342b278401183c5fed5a50db2 - paths: - - stacks/homarr/docker-compose.yml - - stacks/authentik/docker-compose.yml - - stacks/authentik/blueprints/jupiter.yaml - - stacks/authentik/.env.example - - kind: owner-report - reference: "Portainer GitHub/main/PAT configuration, environment management and manual pull/redeploy workflow, 2026-10-06" - - kind: owner-report - reference: "No independent credential recovery; operational rules not established, 2026-10-06" - - kind: owner-report - reference: "Authentik fully deployed with all listed application integrations; Authelia retired; independent recovery custody unchanged, 2026-10-16" - - kind: repository - repository: jupiter-stacks - revision: d09df456ad331b8beb9a40615114ea8aae2dced5 - paths: - - stacks/authentik/docker-compose.yml - - stacks/authentik/blueprints/jupiter.yaml - - stacks/authentik/.env.example - - stacks/beszel/docker-compose.yml - - stacks/gitea/docker-compose.yml - - stacks/immich/docker-compose.yml - - stacks/paperless-ngx/docker-compose.yml -related: [home-server.reference, home-server.host, home-server.portainer, home-server.authentication, home-server.backups, home-server.operations, home-server.notes, home-server.downloads] -update_triggers: [deployment-workflow-change, repository-change, credential-rotation, rollback-policy-change] -unknowns: - - github-pat-scopes-and-expiration - - post-deployment-health-criteria + revision: 12fb1b96e01fc062fdce4c216f11eb5d7ce716ed + paths: [stacks/traefik/docker-compose.yml, stacks/authentik/docker-compose.yml, stacks/downloads/docker-compose.yml, stacks/notes/docker-compose.yml] +related: [home-server.portainer, home-server.authentication, home-server.downloads, home-server.notes, home-server.networking, home-server.backups] +update_triggers: [deployment-workflow-change, repository-change, credential-rotation] +unknowns: [github-pat-scopes-and-expiration, general-health-gates-and-approval-policy] --- # Deployment -| Setting | Source / workflow | -| --- | --- | -| Stack definitions | | -| Git ref | `main` | -| Repository authentication | GitHub PAT configured in Portainer | -| Environment values/secrets | Portainer stack environment settings; AirVPN keys use root-restricted host secret files | -| Deployment | Manually pull/redeploy each affected stack in Portainer | -| Portainer itself | [Host shell script](portainer.md), not a managed Compose stack | - -```text -Compose change -> push main -> manual Portainer pull/redeploy -> running stack +```mermaid +--- +config: + themeCSS: | + text,.nodeLabel { fill:var(--infra-text);color:var(--infra-text); } + .flowchart-link { stroke:var(--infra-line); } + marker path { fill:var(--infra-line);stroke:var(--infra-line); } + .infraClient rect { fill:var(--infra-client-fill);stroke:var(--infra-client-stroke);rx:8px;ry:8px; } + .infraEdge rect { fill:var(--infra-edge-fill);stroke:var(--infra-edge-stroke);rx:8px;ry:8px; } + .infraService rect { fill:var(--infra-service-fill);stroke:var(--infra-service-stroke);rx:8px;ry:8px; } +--- +flowchart LR + accTitle: Manual Git-backed stack deployment + accDescr: Pushing configuration does not deploy it; Portainer must pull and redeploy before runtime checks. + Git["Push main
jupiter-stacks"]:::infraClient + Portainer["Portainer
manual pull / redeploy"]:::infraEdge + Runtime["Running containers
check routes + health"]:::infraService + Git --> Portainer --> Runtime ``` -A Git commit is not deployment proof. Installed host Compose version is not -proof of Portainer's Compose implementation. +- Source: , branch `main`; GitHub PAT in Portainer. +- Stack values/secrets live in Portainer; AirVPN keys are root-restricted host files. +- Git updates do not populate bind-mounted files or application databases. +- Native Compose version does not establish Portainer's Compose implementation. +- Host apt, fstab/RAID, systemd and Mercury nginx are outside this workflow. -Recovering deployment requires Portainer state or independently retrievable -repository credentials and stack environment values. [Portainer backups](backups.md) -exist; credential/state restoration is untested. Do not put secret values in -this site or Git. +## Prerequisites / order -No independent recovery arrangement exists for the PAT or stack secrets. -Rollback, health-check gates, approval rules and UI-versus-Git drift policy -are not established; do not assume permission to deploy, stop or delete services. +| Before | Then | Detail | +| --- | --- | --- | +| Mounted `/data`, Docker, required networks | Workloads | Preserve bind paths, named volumes and secrets | +| Downloads stack creates `downloads` | Arr + Traefik | [Download state/redeployment](downloads.md#state-and-redeployment) | +| Gitea creates `notes_build` | Notes | [Notes deployment](notes.md#deployment) | +| Secure Authentik + apply host blueprint | Public authentication | [Authentication](authentication.md#state-secrets) | +| Independent SSH session | Replace Portainer | [Standalone deployment](portainer.md#deployment) | -## Local downloads deployment / recovery +## Ingress transport deployment and rollback -The owner confirms [qBittorrent/Gluetun through AirVPN](downloads.md) live on -2026-10-26, including both Arr import workflows and the authenticated public UI. -Use the linked stack runbook for reconstruction, not the retired seedbox. +Current routing convention: [Networking](networking.md#listener-and-trust-boundaries). +Owner confirmed cutover complete **2026-10-27**. -Deploy Downloads before its consumers: it creates the external `downloads` -network used by Sonarr, Radarr, Prowlarr and Traefik. Prepare the bind-mounted -files under `/data/qbittorrent/{config,defaults}` and -`/data/gluetun/secrets` first. AirVPN private/preshared keys are root-restricted -host files mounted as Compose secrets, not Portainer environment values; -the tunnel address, country and reserved peer port are stack environment values. +1. Keep SSH and configuration backups; ensure WireGuard owns `10.0.0.2`. +2. Deploy Traefik's HTTPS defaults, restricted WireGuard listener and trusted forwarded headers **before** changing app routes. +3. Redeploy public routers as `https,wireguard` without router TLS labels; retain local HTTPS-only routes and HSTS proxy-scheme handling. +4. Recreate Portainer independently; include external football's router. Recreate Gluetun/qBittorrent together; preserve Authentik names used by [backup hooks](backups.md#consistency-hooks). +5. From Mercury, check each host/path at HTTP `10.0.0.2:8081` with original HTTPS headers. Do not follow fallback redirects; verify callbacks/HSTS, non-Mercury denial and LAN HTTPS. +6. Switch Mercury **last**: install the shared upstream plus all three nginx site files together; `sudo nginx -t && sudo systemctl reload nginx`. +7. Check public login/callbacks, WebSockets, registry and media responses. -Arr client credentials, categories, library roots, remote-path mappings and -hardlink settings are database/UI state, not reproduced by pulling Compose. -The public UI also depends on the persisted qBittorrent Server domains setting, -the host-side Authentik blueprint and Traefik's `downloads` network attachment. -Recreate Gluetun and qBittorrent together when replacing their shared namespace. +- Transport rollback: restore Mercury's previous **sites and upstream together** (`https://jupiter_backend` + `10.0.0.2:443`), syntax-check, reload. +- Leave migrated Jupiter routes in place: HTTPS still works. If reverting Traefik too, restore app TLS labels before removing entrypoint defaults. +- Host staging/backups: `~/jupiter-wireguard-http` on both hosts; Mercury's rollback files under `backup/{conf.d,sites-available}`. Not independent recovery storage. -Full isolation exercises remain outstanding, and the new client state/defaults -and VPN secrets are not yet backed up. See [Backups](backups.md#local-downloads-recovery-gap). +## Reconstruction limits -## Notes deployment - -The [Notes reference](notes.md) covers `notes_builder`, `notes_web`, host bind -mounts, the signed Gitea webhook and the shared static volume. Deploy Gitea before -Notes: Gitea owns the `notes_build` network that the Notes stack consumes. - -## Authentik configuration surfaces - -The owner reports the Authelia-to-Authentik migration complete. Rebuilding it -requires more than pulling Compose: - -| Surface | Required state | -| --- | --- | -| Portainer environment | Authentik persistent key, database password, eight provider client secrets; matching application secrets/overrides | -| Host files | Copy repository `stacks/authentik/blueprints/jupiter.yaml` into `/data/authentik/blueprints`; Git checkout alone does not populate this bind mount | -| Authentik database | Administrator, MFA enrolment, group memberships, applied providers/application policies | -| Application databases/UIs | Beszel, Gitea, Immich and Portainer OIDC setup/account linking | -| Application Compose | Dozzle, Homarr, Paperless and Wardrowbe OIDC settings; five proxy-protected routers use `authentik@docker` | - -Homarr uses the same `OIDC_HOMARR_SECRET` in both stack environments. Its -[account-linking steps](authentication.md#homarr) include verified email and -duplicate-account cleanup; redeploying Compose alone does not complete linking. - -For initial setup, keep `AUTHENTIK_PUBLIC_ROUTING=false` and access the -loopback-published `127.0.0.1:9000` privately, for example through SSH forwarding. -Secure the administrator account and prepare MFA, groups and blueprint policy -before enabling public routing. Enable routing and establish working OIDC -account links before disabling any local application login; Beszel/Paperless -flags default to preserving it. The retired Authelia service is not a -replacement recovery path. - -Redeploying the Authentik stack alone does not copy changed host blueprints -or reproduce database-backed application settings. Keep provider/client secrets -matched across both sides. Preserve deployed Authentik container names or update -the [Backrest hooks](backups.md) when recreating containers. - -Host apt packages, fstab, RAID assembly, systemd units and Mercury nginx are -outside the Compose deployment workflow. +- Restore Portainer state or independently retrieve Git credentials + stack secrets: [Backups](backups.md#recovery-limits). +- Authentik: copy blueprint into its host bind mount; restore identity/MFA and application-managed OIDC state. Compose alone is insufficient. +- Football is externally managed; its Compose definition is not in `jupiter-stacks`. +- Portainer image pin caveat: [Portainer](portainer.md#deployment). +- General approvals/drift policy and full-host recovery order remain undefined. diff --git a/docs/home-server/downloads.md b/docs/home-server/downloads.md index 5986871..4e84ddb 100644 --- a/docs/home-server/downloads.md +++ b/docs/home-server/downloads.md @@ -2,185 +2,106 @@ schema_version: 1 id: home-server.downloads type: reference -scope: [jupiter, airvpn, gluetun, qbittorrent, media-import] +scope: [jupiter, airvpn, gluetun, qbittorrent] sensitivity: private-infrastructure -last_reviewed: "2026-10-26" +last_reviewed: "2026-10-27" sources: - kind: owner-report - reference: "Sonarr, Radarr and Prowlarr now have alerting enabled; destination and enabled events not supplied, 2026-10-26" - - kind: owner-report - reference: "Former Ultra.cc subscription active since 2024-05-25, always GBP 4.50/month until retirement, 2026-10-26" - - kind: owner-report - reference: "AirVPN live with direct home-ISP egress; Sonarr/Radarr imports, hardlinks and seeding/removal confirmed; public UI and both login layers working; Ultra.cc and rclone mount retired; remaining isolation checks and backups outstanding, 2026-10-26" - - kind: owner-report - reference: "Cost saving and simpler architecture; three-year AirVPN plan purchased for GBP 56.06, expires Thursday, 25 October 2029, 2026-10-26" - - kind: owner-report - reference: "Requested AirVPN/local qBittorrent migration with direct home-ISP egress, 2026-10-26" + reference: "AirVPN egress, imports/hardlinks, seeding/removal and authenticated UI live; subscription details and Ultra.cc retirement confirmed 2026-10-26; isolation exercises incomplete" - kind: repository repository: jupiter-stacks revision: working-tree base_revision: 631e4fdfa4c7122e5eff38e11b070c17ff7a4a2a - paths: - - stacks/downloads/docker-compose.yml - - stacks/downloads/README.md - - stacks/downloads/qBittorrent.conf - - stacks/downloads/resolv.conf - - stacks/downloads/vpn-entrypoint.sh - - stacks/sonarr/docker-compose.yml - - stacks/radarr/docker-compose.yml - - stacks/prowlarr/docker-compose.yml -related: [home-server.seedbox, home-server.networking, home-server.storage, home-server.deployment, home-server.backups, home-server.operations] -update_triggers: [deployment, airvpn-device-change, route-change, storage-change, seedbox-retirement, alerting-change] -unknowns: - - selected-airvpn-server-country-and-forwarded-port - - measured-throughput-and-runtime-isolation - - airvpn-renewal-behaviour - - arr-alert-destinations-and-enabled-events + paths: [stacks/downloads/docker-compose.yml, stacks/downloads/qBittorrent.conf, stacks/downloads/resolv.conf, stacks/downloads/vpn-entrypoint.sh, stacks/sonarr/docker-compose.yml, stacks/radarr/docker-compose.yml] +related: [home-server.networking, home-server.storage, home-server.deployment, home-server.backups, home-server.operations, home-server.seedbox] +update_triggers: [airvpn-device-change, route-change, storage-change, renewal] +unknowns: [airvpn-country-and-reserved-port, measured-throughput, complete-runtime-isolation, renewal-behaviour] --- # Local downloads / AirVPN -**Live by owner report on 2026-10-26.** Local qBittorrent behind Gluetun/AirVPN -has replaced the [Ultra.cc seedbox](seedbox.md). Downloads use the home ISP -directly. Sonarr and Radarr imports, hardlinks, continued seeding and intended -removal behaviour are confirmed. Ultra.cc is cancelled/expired, retained files -have been handled, and the old rclone-seedbox service and FUSE mount are removed. - -The change saves money and simplifies the architecture: downloads and libraries -now share local storage, removing the remote seedbox, SFTP/FUSE mount and -cross-filesystem import dependency. This is owner confirmation, not independent -runtime inspection; the remaining isolation and recovery gaps are listed below. - -## Subscription / savings - -| Item | Cost / term | -| --- | --- | -| Provider | [AirVPN](https://airvpn.org/); three-year plan purchased | -| Upfront payment | GBP 56.06 for three years | -| Expiry | **Thursday, 25 October 2029** | -| Effective subscription cost | Approximately GBP 1.56/month or GBP 18.69/year, amortised over 36 months | -| Former Ultra.cc subscription | Active since 2024-05-25 until retirement; always GBP 4.50/month (GBP 54/year), with no price changes | -| Subscription saving | Approximately GBP 2.94/month or GBP 35.31/year; GBP 105.94 over three years at the former rate | - -Savings exclude incremental electricity and any future renewal price. -Automatic renewal behaviour has not been recorded. - -The authoritative deployment and rollback runbook is -[`jupiter-stacks/stacks/downloads/README.md`](https://github.com/jayo60013/jupiter-stacks/blob/main/stacks/downloads/README.md). -It includes the required host files, AirVPN setup, routing acceptance gates, -failure exercises, application UI changes and seedbox retirement. +- **Live, owner-confirmed 2026-10-26:** home-ISP egress, Sonarr/Radarr hardlink imports, seeding/removal and both Web UI login layers. +- Replaces [Ultra.cc](seedbox.md); local imports remove the SFTP/FUSE dependency. +- Working downloads do **not** prove fail-closed behaviour; outstanding exercises below. ## Current topology -```text -qBittorrent - -> shared Gluetun network namespace / firewall - -> AirVPN WireGuard packets over Jupiter's home interface/router - -> AirVPN public exit - -> peers - -Sonarr / Radarr / optional Prowlarr direct downloads - -> dedicated downloads Docker network - -> http://gluetun:8080 +```mermaid +--- +config: + themeCSS: | + text,.nodeLabel,.cluster-label { fill:var(--infra-text);color:var(--infra-text); } + .edgeLabel,.edgeLabel p { background:var(--infra-zone);color:var(--infra-text); } + .flowchart-link { stroke:var(--infra-line); } + marker path { fill:var(--infra-line);stroke:var(--infra-line); } + .cluster rect { fill:var(--infra-zone);stroke:var(--infra-border);stroke-dasharray:5 5;rx:12px;ry:12px; } + .cluster span,.cluster text { color:var(--infra-text)!important;fill:var(--infra-text)!important; } + .infraClient rect { fill:var(--infra-client-fill);stroke:var(--infra-client-stroke);rx:8px;ry:8px; } + .infraService rect { fill:var(--infra-service-fill);stroke:var(--infra-service-stroke);rx:8px;ry:8px; } + .infraEdge rect { fill:var(--infra-edge-fill);stroke:var(--infra-edge-stroke);rx:8px;ry:8px; } + .infraCloud rect { fill:var(--infra-cloud-fill);stroke:var(--infra-cloud-stroke);rx:8px;ry:8px; } +--- +flowchart LR + accTitle: Download API and VPN-only torrent egress + accDescr: Arr uses the internal authenticated API. qBittorrent shares Gluetun's namespace and reaches peers through AirVPN, not Mercury. + Arr["Sonarr / Radarr / Prowlarr"]:::infraClient + subgraph Namespace["SHARED NETWORK NAMESPACE"] + Qbit["qBittorrent
torrent interface wg0"]:::infraService + VPN["Gluetun
firewall + WireGuard"]:::infraEdge + end + ISP["Home ISP"]:::infraEdge + Exit["AirVPN exit"]:::infraCloud + Peers["Torrent peers"]:::infraClient + Arr -->|"HTTP gluetun:8080 / native login"| Qbit + Qbit --> VPN -->|"Encrypted VPN"| ISP --> Exit <--> Peers ``` -The existing Jupiter-to-Mercury host WireGuard tunnel remains separate and -unchanged. Direct home-ISP egress, not Mercury, is confirmed by the owner. -Recheck host routing and packet-marking rules after network or endpoint changes. - -## Repository configuration - | Surface | Configuration | | --- | --- | -| Downloads stack | Pinned Gluetun and LinuxServer qBittorrent images in one Compose project | -| Egress isolation | qBittorrent uses `network_mode: service:gluetun`; enabled Gluetun firewall; initial torrent interface binding `wg0` | -| Startup | Compose health dependency plus a per-start entrypoint guard before qBittorrent's original `/init`, including Docker automatic restarts | +| Namespace | `network_mode: service:gluetun`; enabled firewall; initial torrent binding `wg0` | +| Startup | Compose health dependency + per-start guard before `/init`, including Docker restarts | | DNS / IPv6 | qBittorrent resolver pinned to Gluetun localhost; namespace IPv6 disabled | -| Administration | HTTPS `qbittorrent.umbra.mom` via Traefik/Authentik direct user bindings + MFA and qBittorrent login; loopback/SSH fallback retained | -| Client API | `gluetun:8080` on the named `downloads` bridge; application authentication retained | -| Peer ingress | AirVPN-reserved TCP/UDP port allowed through the VPN firewall; no host/router publication | -| Secrets | Root-restricted files under `/data/gluetun/secrets`, mounted only into Gluetun | - -Prowlarr and FlareSolverr indexer traffic is not moved behind AirVPN. Sonarr, -Radarr and Prowlarr retain their ordinary networks and internet routes. +| Network | Named `downloads` bridge, non-internal, IPv6 disabled; Gluetun, Traefik and Arr attach | +| Peer ingress | AirVPN-reserved TCP/UDP port; allowed by VPN firewall, **not** published on host/router | +| Indexers | Prowlarr/FlareSolverr and Arr ordinary internet traffic stay outside AirVPN | ## Public monitoring -Public access and both authentication layers are working by owner report. -`https://qbittorrent.umbra.mom` uses Mercury's existing wildcard ingress, then -Traefik and Authentik's per-user/MFA policy before qBittorrent's own login. -This is the normal management UI, not a read-only monitoring account. +- Browser: `https://qbittorrent.umbra.mom`; [Mercury ingress](networking.md#application-ingress) -> [Authentik](authentication.md#forward-auth) -> native qBittorrent login. +- Full management UI, **not read-only**. Arr uses the internal API, not the public URL. +- Traefik reaches `gluetun:8080`; router labels belong to Gluetun. qBittorrent gets no extra network/egress path. +- Loopback fallback: `127.0.0.1:8080` via SSH forwarding. +- Persist qBittorrent's **Server domains** before public routing; defaults do not update existing state. Apply the host Authentik blueprint/callback membership. +- Retain native authentication, CSRF and host checks; public DNS points to Mercury, never the VPN exit. -Traefik joins the existing `downloads` network to reach `gluetun:8080`; -Gluetun and qBittorrent gain no independent network or non-VPN egress path. -The router labels belong to Gluetun, which owns the shared namespace. -The Authentik blueprint adds an application bound to `jay` (with other users -assigned manually), a `forward_single` -provider, and embedded-outpost membership; its callback router includes the -new hostname. +## State and redeployment -For recovery or redeployment, follow the runbook's public-monitoring sequence: -update the persisted qBittorrent Server domains setting, apply the host-side Authentik blueprint and -redeploy Authentik, then Traefik and the Downloads pair. Merely changing the -qBittorrent defaults does not update a running installation. Retain native -authentication and CSRF/host protections; do not expose an unauthenticated API. -DNS must resolve the public hostname to Mercury, not to an AirVPN exit. +| Host path | State | +| --- | --- | +| `/data/qbittorrent/config` | Settings, torrent/resume state | +| `/data/qbittorrent/defaults` | Initial config, startup guard and resolver files | +| `/data/gluetun/secrets` | Root-restricted WireGuard private/preshared keys; Gluetun-only mounts | -Sonarr/Radarr/Prowlarr keep using the internal API. Only browser ingress uses -Mercury; torrent internet traffic still uses AirVPN through the home ISP. +- Prepare bind files/keys before deployment; address, country and reserved port are stack variables. +- Deploy Downloads before its network consumers; replace Gluetun/qBittorrent **together**. +- Arr DB/UI state: native API credentials, categories `sonarr`/`radarr`, roots and remote-path mappings. Restore/reconcile before jobs resume. +- Payload/library paths and mount boundaries: [Storage](storage.md#media-mounts). +- Backup coverage: [Backups](backups.md#local-downloads-recovery-gap); alerts: [Operations](operations.md#observability). -## Local storage and imports +## Subscription / savings -Existing host libraries stay at `/data/jellyfin/movies` and -`/data/jellyfin/tv_shows`. New downloads live under -`/data/jellyfin/torrents/{incomplete,movies,tv}`. +| Item | Value | +| --- | --- | +| AirVPN | GBP **56.06 / three years**, expires **2029-10-25** | +| Amortised cost | GBP 1.56/month / 18.69/year | +| Former Ultra.cc | GBP 4.50/month since 2024-05-25; no price changes | +| Saving | GBP 2.94/month / 35.31/year / 105.94 over three years | -Sonarr/Radarr receive one `/data/jellyfin:/media` mount so imports can hardlink -within one filesystem. The replacement library roots are `/media/tv_shows` -and `/media/movies`, rather than `/tv` and `/movies`, without moving -existing host files. Jellyfin's existing `/data/jellyfin:/media` mount stays -unchanged; download folders must not be included in its library roots. +- Excludes incremental electricity and renewal changes; auto-renewal unknown. -qBittorrent receives only `/data/jellyfin/torrents:/media/torrents`, not the -organised media libraries. All three applications see reported download paths -consistently. Repository/runbook categories are `sonarr` and `radarr`, with their -corresponding download folders. Both applications' hardlink imports and intended -seeding/removal behaviour are confirmed by the owner. +## Remaining validation -Deploy Downloads before the consumer stacks: it creates their external -`downloads` network. Updating Compose does not change download-client settings, -categories, roots or remote-path mappings stored in application databases. -During recovery, restore or reconcile that state before resuming jobs. -The runbook's old-queue migration steps are historical now that Ultra.cc is retired. - -## Alerting - -**Sonarr, Radarr and Prowlarr have alerting enabled**, by owner report on -2026-10-26. Connections are managed in each application's **Settings -> Connect**; -the destinations and selected events have not been recorded. - -This does not establish coverage for empty indexer searches, releases rejected -by quality/profile rules, or stalled torrents. A successful search with no -acceptable results is not normally a health failure. Missing-media or -stalled-download alerts need separate monitoring if required. - -Existing host/container and Discord notification coverage is documented in -[Operations](operations.md#observability). - -## Remaining validation / recovery gaps - -- Record the non-secret server country and reserved peer port if needed for - operations; never put device keys in these notes. -- Direct home-ISP egress and normal downloads are confirmed; working inbound - peer connectivity, DNS confinement and IPv6 denial are not yet fully recorded. -- Exercise tunnel failure, unavailable VPN at startup, Gluetun replacement and - host reboot; no unprotected internet fallback is acceptable. -- Add qBittorrent state/defaults and VPN secrets to the actual encrypted backup - policy; the owner confirms they are not yet covered. The documented - six-directory plan does not cover them. - -Seedbox retirement and the local import workflow are complete by owner report; -the former seedbox is no longer an available rollback assumption. - -The HDD array remains RAID 0 without redundancy. Hardlinks save space but are -not independent copies or backups. +- Record non-secret server country, tunnel address and reserved port. +- Prove inbound peer connectivity, DNS confinement and IPv6 denial. +- Exercise VPN failure, unavailable VPN at startup, Gluetun replacement and host reboot; **no unprotected fallback**. +- The retired seedbox is not a rollback target. diff --git a/docs/home-server/host.md b/docs/home-server/host.md index 54ee977..4ae6d15 100644 --- a/docs/home-server/host.md +++ b/docs/home-server/host.md @@ -4,117 +4,76 @@ id: home-server.host type: reference scope: [jupiter, hardware, operating-system, docker] sensitivity: private-infrastructure -last_reviewed: "2026-10-26" +last_reviewed: "2026-10-27" sources: - kind: owner-report - reference: "AirVPN local downloads live; Ultra.cc retired and rclone-seedbox service/FUSE mount removed, 2026-10-26" - - kind: owner-report - reference: "Hardware, OS, bare-metal Docker and data-root confirmation, 2026-10-06" - - kind: owner-report - reference: "hostnamectl, timedatectl, user/group records, Docker info/version and systemd units, 2026-10-06" - - kind: owner-report - reference: "Owner does not recognize backup-puller account; no independent host-config archive, 2026-10-06" - - kind: owner-report - reference: "Added local logging driver with max-size 10m and max-file 3 to /etc/docker/daemon.json, 2026-10-20" -related: [home-server.reference, home-server.storage, home-server.networking, home-server.deployment, home-server.operations] -update_triggers: [hardware-change, os-upgrade, kernel-upgrade, docker-reconfiguration, account-change, unit-change] -unknowns: - - exact-gpu-model - - jupiter-firewall-policy - - docker-package-installation-source - - backup-puller-account-purpose - - docker-logging-restart-and-container-recreation + reference: "Hardware/OS/runtime/accounts/systemd snapshot 2026-10-06; daemon logging change 2026-10-20; seedbox unit removed 2026-10-26" + - kind: live-inspection + reference: "GPU PCI ID 1002:68f9 identified as AMD Cedar, 2026-10-27" +related: [home-server.storage, home-server.networking, home-server.operations] +update_triggers: [hardware-change, os-upgrade, kernel-upgrade, docker-reconfiguration, account-change] +unknowns: [exact-gpu-board-model, docker-package-source, backup-puller-purpose, docker-logging-activation] --- -# Host +# Jupiter host + +## Hardware / OS | Component | Configuration | | --- | --- | -| Host | Jupiter; bare metal | -| OS | Debian GNU/Linux 13 (trixie); x86_64 | +| Platform | Bare metal; Debian 13 (trixie), x86_64 | | Kernel | `6.12.94+deb13-amd64` | -| CPU | AMD Ryzen 5 5600X; 6 cores / 12 threads; reported 4.65 GHz | +| CPU | Ryzen 5 5600X; 6 cores / 12 threads; reported 4.65 GHz | | RAM | 1 x 16 GB Corsair Vengeance LPX | -| GPU | AMD Radeon HD 5000/6000/7350/8350 Series; discrete; exact model unresolved | -| Motherboard | Gigabyte B550M DS3H | -| Firmware | `FB`; dated `2023-06-08` | +| GPU | AMD Cedar `1002:68f9`; exact board unknown | +| Board / firmware | Gigabyte B550M DS3H; `FB`, `2023-06-08` | | PSU | Corsair CV550 | -| SSD | Samsung 860 EVO; 1 TB; OS and SSD-backed caches | -| HDD | 2 x Seagate BarraCuda; 2 TB each; RAID 0 | -| Docker | Native host engine; data root `/var/lib/docker` | -| LAN | `192.168.1.56` | -| WireGuard | `10.0.0.2/24`; Mercury peer/server `10.0.0.1/24` | -| Time | `Europe/London`; RTC UTC; NTP active; clock synchronized at review | +| Time | `Europe/London`; RTC UTC; NTP active/synchronised at inspection | +| Disks / mounts | [Storage](storage.md); network addresses: [Networking](networking.md) | ## Docker runtime -| Setting | Observed value | +2026-10-06 supplied snapshot, not current-version telemetry. + +| Setting | Value | | --- | --- | -| Engine / API | Docker CE `29.8.2` / `1.56` | -| Compose CLI plugin | `v5.6.0`; not proof of Portainer's Compose implementation | +| Engine / API / Compose | CE `29.8.2` / `1.56` / plugin `v5.6.0` | | containerd / runc | `v2.3.6` / `1.5.1` | -| Storage | `overlayfs`; containerd snapshotter | -| Cgroups | `systemd`; v2 | -| Logging | `local` configured in `/etc/docker/daemon.json`; `max-size: 10m`, `max-file: 3`; activation not confirmed (previously observed default: `json-file`) | -| Firewall backend | `iptables` | -| Runtime security | AppArmor, seccomp, cgroup namespaces | +| Root / storage | `/var/lib/docker`; `overlayfs`, containerd snapshotter | +| Cgroups / firewall | systemd v2 / iptables | +| Security | AppArmor, seccomp, cgroup namespaces | | Swarm / live restore | Inactive / disabled | -Docker/containerd services and `docker.socket` are enabled. -Docker starts `/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock`. -Supplied Docker unit has no explicit `/data` mount dependency. -The former `rclone-seedbox.service` and FUSE mount are removed by owner report -on 2026-10-26; Docker workloads no longer depend on that remote import mount. +- Docker/containerd/socket enabled; dockerd args: `-H fd:// --containerd=/run/containerd/containerd.sock`. +- Supplied Docker unit has no explicit `/data` mount dependency. +- `wg-quick@wg0` active; separate from Gluetun/AirVPN. WireGuard/rclone apt-managed; retired seedbox unit removed. +- No host nginx; `unattended-upgrades` enabled, policy unknown. ### Docker log rotation -On 2026-10-20, the owner reported adding the following logging settings to -`/etc/docker/daemon.json`: +Owner-reported `/etc/docker/daemon.json`, **2026-10-20**: ```json { "log-driver": "local", - "log-opts": { - "max-size": "10m", - "max-file": "3" - } + "log-opts": {"max-size": "10m", "max-file": "3"} } ``` -This configures automatic rotation with roughly 30 MB of uncompressed log -retention per container; the `local` driver also compresses rotated logs. -It covers container stdout/stderr, not application log files written inside -containers or mounted volumes. - -A Docker daemon restart and recreation of existing containers are required to -apply this default to them; neither is confirmed by the owner report. Restarting -Docker can interrupt workloads because live restore was disabled in the supplied -snapshot. Explicit Compose/container logging settings override the daemon default. -Inspect a container's effective configuration with: +- Roughly 30 MB uncompressed/container; rotated files compressed. Covers stdout/stderr, not application files. +- Activation unconfirmed: restart daemon **and recreate existing containers**; explicit container logging overrides the default. +- Daemon restart interrupts workloads with live restore disabled. ```sh docker inspect --format '{{json .HostConfig.LogConfig}}' CONTAINER ``` -## Host administration +## Accounts -| Account / group | Identity | +| Identity | Configuration | | --- | --- | -| `jay` | UID/GID `1000:1000`; `/home/jay`; bash; member of `sudo`, `docker`, `video`, `backups` | -| `backup-puller` | UID/GID `1001:1001`; `/home/backup-puller`; bash; member of `backups`; origin/purpose not recognized by owner | -| `backups` | Shared group; GID `1002` | +| `jay` | UID/GID `1000:1000`; `/home/jay`; bash; `sudo,docker,video,backups` | +| `backup-puller` | UID/GID `1001:1001`; `/home/backup-puller`; bash; group `backups`; purpose unrecognised | +| `backups` | GID `1002` | -WireGuard and rclone were apt-managed in the supplied snapshot; -removing the seedbox service does not establish that the rclone package was -uninstalled. Backrest's separate rclone configuration is not the retired mount. -`wg-quick@wg0.service` is active in the supplied snapshot and remains separate -from the containerised Gluetun/AirVPN tunnel for [local downloads](downloads.md). -No host-level nginx on Jupiter; nginx still exists in application -containers. `unattended-upgrades.service` is enabled; effective update policy -not supplied. - -No independent host-configuration archive is maintained. `backup-puller` must -not be assumed to perform backups; identify SSH/cron/service dependencies before -removing or repurposing it. - -Hardware/versions are a dated snapshot, not live telemetry. +- Identify `backup-puller` SSH/cron/service dependencies before removal; its name is not backup evidence. diff --git a/docs/home-server/ideas-next-steps.md b/docs/home-server/ideas-next-steps.md deleted file mode 100644 index 690e5f9..0000000 --- a/docs/home-server/ideas-next-steps.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -schema_version: 1 -id: home-server.ideas-next-steps -type: plan -scope: [jupiter, mercury, private-access, recovery, downloads, power, services] -sensitivity: private-infrastructure -last_reviewed: "2026-10-26" -sources: - - kind: owner-report - reference: "AirVPN downloads live; GBP 56.06 three-year plan ending 2029-10-25; Ultra.cc/rclone retired; imports/hardlinks/seeding/removal and public UI confirmed; full isolation checks and backups outstanding, 2026-10-26" - - kind: owner-report - reference: "Access, device-loss recovery, hardware constraints, broadband and VPN preferences interview, 2026-10-22" - - kind: documentation - reference: "Planning discussion based on jupiter-stacks and home-server reference notes, 2026-10-22; proposals only, no live inspection or deployment" -related: - - home-server.reference - - home-server.networking - - home-server.authentication - - home-server.backups - - home-server.operations - - home-server.seedbox - - home-server.downloads - - home-server.storage - - home-server.host -update_triggers: [implementation, priority-change, access-requirements-change, pricing-change, power-measurement] -unknowns: - - live-routing-firewall-and-wireguard-configuration - - work-laptop-local-dns-and-lan-access-policy - - measured-wall-power-and-electricity-tariff - - airvpn-renewal-terms-and-complete-isolation-results - - immich-original-photo-backup-coverage ---- - -# Ideas / next steps - -Planning backlog from the 2026-10-22 discussion, updated with the owner's -2026-10-26 AirVPN cutover confirmation. Unchecked proposals remain -**recommendations, not implemented changes**; the completed downloads work -below is owner-reported deployed state. - -## Requirements confirmed with the owner - -| Area | Requirement / preference | -| --- | --- | -| Private administration | Portainer, Beszel, Dozzle, Backrest, Prowlarr, Radarr and Sonarr should stop being publicly reachable | -| Public applications | Keep normal user-facing applications public, including Vaultwarden | -| Personal devices | Owner-only admin access; VPN clients or certificates can be installed on personal phone/laptop | -| Work laptop | Browser-only admin access needed on home Wi-Fi; cannot install VPN clients or certificates | -| Device loss | Vaultwarden access remains essential; admin tools can wait until returning home | -| Vaultwarden recovery | Owner knows the master password; TOTP is backed up/restorable through Microsoft, with independently recoverable Microsoft access; owner report, not an observed recovery exercise | -| Private-access tooling | Prefer minimal infrastructure and no vendor-hosted coordination service; existing Cloudflare DNS/SSH use is acceptable | -| Hardware | Software/BIOS tuning only; no hardware purchases or removals | -| Broadband | Reported 500 Mbps download and upload; public trackers only | -| Download VPN | AirVPN selected and live; three-year plan purchased for GBP 56.06, expires Thursday, 25 October 2029 | -| New services | Interested in reliability, everyday tools, media, development and privacy | - -## Priority order - -1. Prepare independent recovery access, then introduce private admin ingress. -2. Make backups recoverable and add failure notifications. -3. Finish download-VPN isolation checks and recovery coverage; seedbox replacement is complete. -4. Measure and tune power use. -5. Add services that solve an actual day-to-day problem. - -## Private admin access - -### Preferred approach: plain WireGuard through Mercury - -Reuse Mercury's public address and existing WireGuard connection to Jupiter. -Give each personal device its own peer/key, narrowly scoped routes and firewall -permissions. No Tailscale account or self-hosted coordination service is needed. - -| Client | Intended access path | -| --- | --- | -| Work laptop on home Wi-Fi | LAN directly to private admin ingress; browser only | -| Personal device away from home | WireGuard to Mercury, then routed private access to Jupiter | -| Public internet | Mercury nginx to explicitly public applications only | - -Use split DNS: admin hostnames resolve to private addresses on the LAN and -through the VPN. Keep HTTPS certificates using the existing DNS-based challenge; -certificate issuance does not require a public website. - -Before choosing exact addresses/listeners, inspect live WireGuard `AllowedIPs`, -routing, firewall rules and Docker port publication. Check that the work laptop's -corporate DNS/proxy policy permits local access; do not bypass employer controls. - -### Implementation checklist - -- [ ] Prepare recovery access and a rollback route before restricting ingress. -- [ ] Add per-device WireGuard peers and a way to revoke a lost device's key. -- [ ] Configure LAN/VPN DNS for the private admin hostnames. -- [ ] Create private-only Traefik ingress; public requests must not reach admin - backends simply by supplying their hostnames. -- [ ] Replace or constrain Mercury's wildcard forwarding in - `jupiter-stacks/mercury/nginx/umbra.mom`, retaining all intended public apps. -- [ ] Apply the same boundary to Authentik's separate outpost callback routes - for Backrest and the Arr applications. -- [ ] Remove or restrict Portainer's direct `9123:9000` publication in - `stacks/portainer/portainer_start.sh`. -- [ ] Retain application authentication and Authentik MFA behind the private - boundary; VPN connectivity must not imply application administrator rights. -- [ ] Confirm private apps and authentication callbacks work from LAN and VPN, - but cannot be reached through public ingress or alternative published ports. -- [ ] Confirm public applications, especially Vaultwarden, remain accessible. - -Removing public DNS records or adding a login page is not sufficient isolation. -The network/proxy boundary must enforce the restriction. - -### Alternatives - -| Option | Assessment | -| --- | --- | -| Plain WireGuard | Preferred: reuse existing infrastructure, few devices, no hosted control service | -| Tailscale | Convenient, but adds the vendor dependency the owner prefers to avoid | -| Headscale | Self-hosted coordination, but more infrastructure to maintain than currently needed | -| mTLS | Device-certificate authentication; adds certificate distribution/recovery and cannot be used directly on the work laptop | - -mTLS rejects clients without a certificate but leaves the HTTPS endpoint -internet-facing. Mercury terminates public TLS, so browser client-certificate -enforcement would need to happen there, not merely between Mercury and Jupiter. - -## Recovery and reliability - -Keep Vaultwarden public with application login and MFA. Do not make access -depend on the new admin VPN or Authentik. - -- [ ] Maintain an encrypted recovery pack outside Jupiter: Mercury provider - console/SSH access, WireGuard re-enrolment instructions, Authentik recovery, - retained local admin credentials, backup credentials, restic key, stack - secrets and essential host configuration. -- [ ] Ensure retrieving/decrypting that pack does not depend on Jupiter, - Portainer or secrets available only inside Vaultwarden. -- [ ] Retain the existing Cloudflare SSH route during migration, with its - effective Access policy reviewed. It still depends on Jupiter's connector - and networking; it is not an out-of-band console. -- [ ] Restore an important service into an isolated location and record the - dependencies, time taken and acceptable data loss. -- [ ] Review backup coverage for Backrest configuration, host configuration, - Docker named volumes and Mercury. -- [ ] Establish whether Immich contains irreplaceable originals and where those - originals and the associated database are backed up. -- [ ] Make failed backup restart hooks visible; a successful snapshot must not - hide stopped Authentik, Portainer or Wardrowbe services. -- [ ] Add service, disk-health, capacity and backup-failure notifications using - Beszel and the existing Mercury uptime service where suitable. -- [ ] Add an external missed-backup heartbeat so Jupiter going offline cannot - prevent notification of its own failure. - -Private connectivity does not fix Authentik downtime. The documented backup plan -stops Authentik and ignores some restart failures; independent SSH/local recovery -remains necessary. See [Backups](backups.md) and [Operations](operations.md). - -## Local downloads instead of the seedbox - -**Completed by owner report on 2026-10-26:** -[local qBittorrent/Gluetun downloads through AirVPN](downloads.md) are live. -This is both a **cost saving** and an **architecture simplification**: local -storage and hardlink imports replace the remote seedbox and SFTP/FUSE dependency. - -The purchased **three-year AirVPN plan cost GBP 56.06** and expires -**Thursday, 25 October 2029**. Amortised over 36 months, that is approximately -GBP 1.56/month versus Ultra.cc's former GBP 4.50/month: a subscription saving of -**GBP 35.31/year**, or **GBP 105.94 over three years**, before extra electricity. -The former GBP 2.50/month VPN estimate is superseded by this actual purchase. - -### Completed work and remaining follow-up - -- [x] Deploy local qBittorrent behind Gluetun/AirVPN. -- [x] Confirm encrypted VPN egress uses the home ISP directly, not Mercury. -- [x] Confirm Sonarr and Radarr imports, hardlinks and intended seeding/removal. -- [x] Confirm public Web UI through Mercury/Traefik/Authentik plus native - qBittorrent login; this is an intentional change from the private-only proposal. -- [x] Retire Ultra.cc, handle retained files and remove the rclone-seedbox - service and FUSE mount. -- [ ] Complete peer-ingress, DNS/IPv6 leak and VPN-failure/startup/reboot checks. -- [ ] Add qBittorrent state/defaults and AirVPN secrets to encrypted off-host backups. - -A hardlink gives the same file data two names without storing a second full -copy. Hardlinks are confirmed for both import workflows; they are not backups. -The separate private-admin-access proposal above remains outstanding. - -## Electricity and compute efficiency - -Reported average CPU usage is approximately 1%, but CPU utilisation does not -measure wall-socket power. No power measurement or actual electricity tariff -was supplied. - -Illustrative costs at **25p/kWh**, using 365 days/year divided by 12: - -| Continuous average draw | Approximate monthly cost | -| --- | --- | -| 40 W | GBP 7.30 | -| 60 W | GBP 10.95 | -| 80 W | GBP 14.60 | - -At that illustrative tariff, saving 10 W continuously saves about GBP 18/year. -An extra average draw of about 16 W would consume the GBP 35.31/year subscription saving. -Count the incremental download workload, not the server's existing baseline. - -- [ ] Measure wall power and obtain the actual unit rate when practical. -- [ ] Inspect CPU idle states and frequency-scaling policy before BIOS tuning; - low CPU limits do not automatically save energy. -- [ ] Inspect RAM pressure and swapping during Immich processing and Wardrowbe - Ollama jobs; the host has 16 GB RAM. -- [ ] Schedule heavy jobs where useful and avoid unnecessary repeated scans. -- [ ] Review effective container log rotation; daemon defaults require activation - and recreation, and explicit Compose settings override them. -- [ ] Avoid aggressive HDD spindown while `/data` hosts active databases. -- [ ] Avoid consolidating unrelated application databases solely to reduce - container count; shared failures/upgrades may outweigh uncertain savings. - -No hardware changes are proposed. Leave spare CPU capacity idle unless a useful -workload justifies the added power and maintenance. - -## Optional service ideas - -These are candidates, not a deployment list. - -| Area | Idea | Constraint / reason | -| --- | --- | --- | -| Reliability | Notifications and external backup heartbeats | Start with existing monitoring rather than a second metrics stack | -| Privacy | AdGuard Home or Pi-hole | Choose one; household DNS availability becomes an operational dependency | -| Files | Syncthing for selected folders | Sync is not backup; check client support on the owner's devices | -| Bookmarks / reading | Linkding; FreshRSS | Small tools with a clear everyday purpose | -| Development | Renovate automation for existing Gitea workflows | Propose updates; avoid unattended production upgrades | -| Media | Profilarr for supported Arr profiles/custom formats | Add only if manual profile maintenance is a real problem | - -Defer Kubernetes, a large metrics stack, another identity provider or a general -cloud suite unless a concrete need emerges. diff --git a/docs/home-server/index.md b/docs/home-server/index.md index 3e407c4..817f585 100644 --- a/docs/home-server/index.md +++ b/docs/home-server/index.md @@ -2,64 +2,42 @@ schema_version: 1 id: home-server.reference type: reference -scope: [jupiter, mercury, downloads, shared-infrastructure] +scope: [jupiter, mercury, shared-infrastructure] sensitivity: private-infrastructure -last_reviewed: "2026-10-26" +last_reviewed: "2026-10-27" sources: - kind: owner-report - reference: "AirVPN local downloads live, Ultra.cc/rclone retired; GBP 56.06 three-year plan ending 2029-10-25 for savings and simpler architecture, 2026-10-26" - - kind: owner-report - reference: "Added ideas/next-steps planning page from owner discussion, 2026-10-22" - - kind: owner-report - reference: "Owner interview, 2026-10-06" - - kind: owner-report - reference: "Authentik migration, access-group motivation and six-directory backup plan, 2026-10-16" -related: - - home-server.host - - home-server.mercury - - home-server.seedbox - - home-server.downloads - - home-server.portainer - - home-server.deployment - - home-server.notes - - home-server.operations - - home-server.networking - - home-server.storage - - home-server.authentication - - home-server.backups - - home-server.ideas-next-steps -update_triggers: [topology-change, source-change, infrastructure-change] + reference: "Host inventory 2026-10-06; Authentik 2026-10-16; downloads 2026-10-26; ingress cutover 2026-10-27" +related: [home-server.host, home-server.mercury, home-server.networking, home-server.storage, home-server.authentication, home-server.downloads, home-server.deployment, home-server.portainer, home-server.notes, home-server.backups, home-server.operations, home-server.seedbox] +update_triggers: [topology-change, source-change] unknowns: [] --- # Home server -| Reference | Scope | +Each topic has one reference page; link to it rather than copying its details. + +| Topic | Canonical reference | | --- | --- | -| [Host](host.md) | Jupiter hardware; OS; Docker | -| [Mercury VPS](mercury.md) | Hosting; ingress; WireGuard; firewall | -| [Local downloads / AirVPN](downloads.md) | Live qBittorrent/Gluetun; local hardlink imports; three-year plan GBP 56.06, expires Thursday, 25 October 2029 | -| [Seedbox (retired)](seedbox.md) | Historical Ultra.cc setup; subscription and rclone/FUSE mount retired | -| [Portainer](portainer.md) | Script-managed container; state; backups | -| [Deployment](deployment.md) | GitHub; Portainer; environment values | -| [Notes](notes.md) | Webhook builder; static site; networks; deployment order | -| [Operations / decisions](operations.md) | Tradeoffs; monitoring; recovery gaps | -| [Networking](networking.md) | Mercury; WireGuard; DNS; ingress | -| [Storage](storage.md) | SSD; RAID 0; mounts; volumes | -| [Authentication](authentication.md) | Authentik; OIDC; per-user service access; forward-auth; secrets | -| [Backups](backups.md) | Backrest; coverage; retention; recovery | -| [Ideas / next steps](ideas-next-steps.md) | Proposed private access, recovery, savings and optional services; not deployed state | +| Hardware, OS, Docker and accounts | [Jupiter host](host.md) | +| VPS, host firewall, Fail2ban and Kuma runtime | [Mercury](mercury.md) | +| Traffic paths, DNS, listeners and proxy trust | [Networking](networking.md) | +| Disks, mounts, volumes and media paths | [Storage](storage.md) | +| OIDC, forward-auth, access policy and account linking | [Authentication](authentication.md) | +| VPN isolation, download configuration and subscription | [Local downloads / AirVPN](downloads.md) | +| Git workflow, prerequisites and ingress rollout | [Deployment](deployment.md) | +| Standalone container and persisted management state | [Portainer](portainer.md) | +| Documentation builder and publication | [Notes](notes.md) | +| Coverage, consistency hooks and recovery gaps | [Backups](backups.md) | +| Alerts, troubleshooting and outstanding work | [Operations](operations.md) | +| Retired remote-download service | [Seedbox archive](seedbox.md) | -## Evidence / agent contract +## Evidence conventions -- `owner-report`: supplied host state/configuration; not independently inspected. +- `owner-report`: supplied state; not independent inspection. - `repository`: intended configuration at `revision`; not deployment proof. -- `documentation`: upstream behaviour; not proof of deployed settings. -- `revision: working-tree`: uncommitted source; `base_revision`: base commit. -- `unknowns`: unresolved facts; never infer defaults as deployed state. -- `related`: stable document IDs; `update_triggers`: re-review conditions. -- On change: update affected prose, Mermaid, sources, unknowns, and `last_reviewed`. -- No credentials. Preserve evidence distinctions; no live status implied. - -Mermaid renders from versioned text; diagrams are manually maintained, not -automatically discovered. +- `live-inspection`: dated checks, limited to the recorded scope. +- `documentation`: upstream behaviour, not deployed settings. +- `working-tree` / `base_revision`: uncommitted configuration and its base. +- `unknowns`: unresolved facts; diagrams are manually maintained snapshots. +- Update sources and `last_reviewed` with changes; never store credentials here. diff --git a/docs/home-server/mercury.md b/docs/home-server/mercury.md index 333f6a9..27d0ac4 100644 --- a/docs/home-server/mercury.md +++ b/docs/home-server/mercury.md @@ -2,253 +2,74 @@ schema_version: 1 id: home-server.mercury type: reference -scope: [mercury, vps, hosting, nginx, wireguard, firewall] +scope: [mercury, vps, firewall, fail2ban, uptime-kuma] sensitivity: private-infrastructure -last_reviewed: "2026-10-26" +last_reviewed: "2026-10-27" sources: - kind: owner-report - reference: "Fasthosts plan, fastfetch, nginx sites, iptables and fail2ban output, 2026-10-06" - - kind: owner-report - reference: "nginx/WireGuard apt management and public IPv4/CGNAT rationale, 2026-10-06" - - kind: owner-report - reference: "Uptime service confirmed as Uptime Kuma; notifications received in Discord server Jupiter, channel #uptimekuma-alerts, 2026-10-23" - - kind: owner-report - reference: "Mercury uptime-kuma.sh supplied with bind mount, resource limits and log rotation, 2026-10-26" - - kind: owner-report - reference: "Mercury Uptime Kuma only checks WireGuard tunnel health and whether Jupiter is online; alerts Jay on Discord when down, 2026-10-26" - - kind: owner-report - reference: "Mercury monitored in Beszel; CPU above 90% for 10 minutes, memory above 90% for 10 minutes and any failed systemd services alerts configured, 2026-10-26" - - kind: owner-report - reference: "fail2ban-client version and status output: Fail2ban 1.1.0 with three active jails (nginx-botsearch, nginx-http-auth, sshd), 2026-10-26" - - kind: owner-report - reference: "fail2ban-client get output for each jail: maxretry, findtime, bantime and ignoreip, 2026-10-26" - - kind: owner-report - reference: "fail2ban-client logpath, journalmatch and actions output: sshd uses journal match _SYSTEMD_UNIT=ssh.service + _COMM=sshd; nginx jails use error.log/access.log; all three use nftables action, 2026-10-26" - - kind: owner-report - reference: "Non-comment jail overrides supplied from /etc/fail2ban/jail.local and /etc/fail2ban/jail.d/defaults-debian.conf, 2026-10-26" - - kind: owner-report - reference: "Fail2ban logtarget /var/log/fail2ban.log, dbfile /var/lib/fail2ban/fail2ban.sqlite3, dbpurgeage 86400 seconds and systemctl is-enabled output enabled, 2026-10-26" + reference: "Hosting/firewall snapshot 2026-10-06; Fail2ban CLI/config and Kuma runtime 2026-10-26" + - kind: live-inspection + reference: "Hostname mercury and nginx 1.26.3 inspected 2026-10-27; firewall/hosting not revalidated" - kind: repository repository: jupiter-stacks revision: working-tree - paths: - - mercury/stacks/uptime-kuma/docker-compose.yml - - mercury/stacks/uptime-kuma/README.md -related: [home-server.reference, home-server.host, home-server.networking, home-server.operations] -update_triggers: [hosting-renewal, vps-resize, os-upgrade, proxy-change, firewall-change, certificate-change, alerting-change] -unknowns: - - renewal-price-and-renewal-date - - creation-timestamp-timezone - - certificate-renewal-method - - wireguard-allowedips-and-keepalive - - backup-and-restore-policy - - uptime-kuma-exact-probes-and-alert-timing - - fail2ban-ban-escalation-action-details-log-rotation-and-recovery-access + paths: [mercury/stacks/uptime-kuma/docker-compose.yml] +related: [home-server.networking, home-server.operations, home-server.backups] +update_triggers: [hosting-renewal, vps-resize, os-upgrade, firewall-change, kuma-change] +unknowns: [renewal-price-and-date, creation-timestamp-timezone, certificate-renewal-method, mercury-backup-policy, fail2ban-enforcement-details-and-log-retention] --- # Mercury VPS -## Host / subscription - -| Field | Configuration | -| --- | --- | -| Provider | [Fasthosts](https://www.fasthosts.co.uk/); UK data centre | -| Role / OS hostname | Mercury / `my-vps` | -| Plan | `1-1-10`; KVM virtual machine | -| CPU | 1 vCore; reported AMD EPYC-Milan @ 2.00 GHz | -| RAM | 1 GB plan; guest reports 864.37 MiB | -| Disk | 10 GB NVMe SSD plan; guest root ext4, 9.64 GiB | -| OS | Debian GNU/Linux 13 (trixie); x86_64 | -| Kernel | `6.12.85+deb13-amd64` | -| Swap | Disabled | -| Public interface | `ens6`; `185.230.217.66/32` | -| WireGuard | Server `10.0.0.1/24`; Jupiter peer `10.0.0.2/24` | -| Created | `2026-03-01 20:48:51`; timezone unconfirmed | -| Payment | GBP 10.00 prepaid for one year; renewal terms unconfirmed | - -Capacities distinguish provider allocation from guest-visible values. - -## Ingress - -nginx runs directly in the VM, not in Docker; nginx and WireGuard are -apt-managed. Mercury provides static public IPv4 ingress because Jupiter's -home connection uses CGNAT. Residential-IP exposure is avoided by design. - -| Hostname | Upstream | -| --- | --- | -| `umbra.mom`, `*.umbra.mom` | `https://10.0.0.2:443` over WireGuard | -| `gitea.umbra.mom` | Same; dedicated registry location `/v2/` | -| `john.gatward.dev`, `samstoreymusic.com` | `https://10.0.0.2:443` | -| `uptime.umbra.mom` | `http://127.0.0.1:3001` | - -- HTTP -> HTTPS: `301`; unmatched default server: `418`. -- TLS terminates at nginx; upstream HTTPS terminates again at Jupiter Traefik. -- Upstream certificate verification disabled: `proxy_ssl_verify off`. -- Certificates: `/etc/letsencrypt/live//{fullchain.pem,privkey.pem}`; - `umbra.mom` certificate also serves its subdomains. -- Preserves `Host`; sets `X-Real-IP`, `X-Forwarded-For`, `X-Forwarded-Proto`; - forwards WebSocket upgrade headers. -- Gitea `/v2/`: unlimited request body; proxy timeouts `900s`. - -## Monitoring / notifications - -Mercury is now monitored by the **Beszel hub on Jupiter**, confirmed by the -owner on 2026-10-26. The following Mercury alerts are configured: - -| Alert | Trigger | -| --- | --- | -| CPU usage | Above 90% for 10 minutes | -| Memory usage | Above 90% for 10 minutes | -| Failed Services | Any failed systemd service | - -These are deployed alert settings, not proposed additions. Beszel's Failed -Services rule detects failed systemd units, not every error-level journal entry. -Alert settings are stored in the Beszel hub UI/database, not the agent Compose -file. Beszel cannot deliver these alerts while Jupiter or its hub is down. - -Uptime Kuma runs on Mercury, served at `https://uptime.umbra.mom` through -the local upstream `http://127.0.0.1:3001`. Its current monitoring scope is -**only the health of the WireGuard tunnel and whether Jupiter is online**. -It notifies **Jay on Discord when either is down**, using the **Jupiter** -Discord server's `#uptimekuma-alerts` channel. Coverage confirmed by the owner -on 2026-10-26; notification receipt previously confirmed on 2026-10-23. -It does not currently monitor individual containers or application health. - -The supplied `~/uptime-kuma.sh` is now represented by -`mercury/stacks/uptime-kuma/docker-compose.yml` in `jupiter-stacks`. -It retains image `louislam/uptime-kuma:2-slim`, container name `uptime-kuma`, -restart policy `unless-stopped`, loopback port `3001`, and bind mount -`/opt/uptime-kuma:/app/data`. Limits remain 300 MiB RAM and 0.5 CPU, with -10 MiB / 3-file log rotation (Compose explicitly selects `json-file`). -The adjacent README documents a stopped-data backup and migration into the -Mercury Portainer environment. Migration has not been confirmed; the repository -change alone does not replace the running container. nginx remains host-managed. - -Exact probe types, targets and alert timing have not been recorded. A failed -check over WireGuard can indicate a tunnel/path failure rather than a powered-off -Jupiter. Mercury monitors independently of Jupiter, but cannot report its own -complete outage through this instance; an external monitor is not yet confirmed. -See [Observability](operations.md#observability) for container-alerting guidance. - -## Firewall / fail2ban - -- UFW-managed iptables: INPUT/FORWARD `DROP`; OUTPUT `ACCEPT`. -- UFW allows TCP `22,80,443`; UDP `80,443,51820`. -- Docker forwarding has separate rules; INPUT policy alone does not define - container exposure. -- Fail2ban version: `1.1.0`; three active jails: `nginx-botsearch`, - `nginx-http-auth`, `sshd`. Confirmed from owner-supplied CLI output on - 2026-10-26. - -Read-only commands to check the installed version and active jails: - -```bash -sudo fail2ban-client version -sudo fail2ban-client status -``` - -Effective jail settings from owner-supplied CLI output on 2026-10-26: - -| Jail | Retry threshold (`maxretry`) | Detection window (`findtime`) | Ban duration (`bantime`) | IP/network exemptions (`ignoreip`) | -| --- | --- | --- | --- | --- | -| `sshd` | 5 | 600 seconds (10 minutes) | 600 seconds (10 minutes) | None | -| `nginx-http-auth` | 3 | 600 seconds (10 minutes) | 600 seconds (10 minutes) | None | -| `nginx-botsearch` | 2 | 600 seconds (10 minutes) | 3600 seconds (1 hour) | None | - -These thresholds count filter-matched failures within the detection window, -not arbitrary requests. No IP/network is explicitly exempt through `ignoreip` -in any of the three jails; other ignore mechanisms have not been inspected. -Ban escalation settings and enforcement action details have not yet been -recorded. Avoid deliberate failed SSH login -tests without a recovery route: the administrator's IP has no `ignoreip` -exemption. - -### Fail2ban log sources / enforcement - -Owner-supplied runtime output on 2026-10-26 confirms: - -| Jail | Monitored source | Configured action | -| --- | --- | --- | -| `sshd` | systemd journal: `_SYSTEMD_UNIT=ssh.service + _COMM=sshd`; no log file monitored | `nftables` | -| `nginx-http-auth` | `/var/log/nginx/error.log`; no journal match set | `nftables` | -| `nginx-botsearch` | `/var/log/nginx/access.log`; no journal match set | `nftables` | - -The `+` in the SSH journal match is an OR: entries matching `ssh.service` or -the `sshd` command are selected. All three jails use the `nftables` action; -the action name alone does not establish the exact blocked ports, chains or -IPv4/IPv6 coverage. Those action parameters have not yet been inspected. - -### Fail2ban persistent configuration - -Owner-supplied non-comment configuration on 2026-10-26: - -`/etc/fail2ban/jail.local`: - -```ini -[nginx-botsearch] -enabled = true -port = http,https -filter = nginx-botsearch -logpath = /var/log/nginx/access.log -maxretry = 2 -findtime = 600 -bantime = 3600 - -[nginx-http-auth] -enabled = true -filter = nginx-http-auth -port = http,https -logpath = /var/log/nginx/error.log -maxretry = 3 -``` - -`/etc/fail2ban/jail.d/defaults-debian.conf`: - -```ini -[DEFAULT] -banaction = nftables -banaction_allports = nftables[type=allports] - -[sshd] -backend = systemd -journalmatch = _SYSTEMD_UNIT=ssh.service + _COMM=sshd -enabled = true -``` - -The nginx jails explicitly target `http,https`. Defining -`banaction_allports` does not establish that any active jail uses all-port -banning. The SSH thresholds and nginx HTTP auth timing in the runtime table -are not explicitly set in these snippets; they are inherited from other -configuration/defaults. - -These host configuration files are outside the Docker Compose stacks. Their -backup coverage and any direct edits to `jail.conf` or filter/action files -have not been confirmed. - -### Fail2ban logging / history - -Owner-supplied runtime settings on 2026-10-26: +## Host | Setting | Value | | --- | --- | -| Fail2ban log destination (`logtarget`) | `/var/log/fail2ban.log` | -| Persistent database (`dbfile`) | `/var/lib/fail2ban/fail2ban.sqlite3` | -| Database purge age (`dbpurgeage`) | 86400 seconds (24 hours) | -| Start at boot (`systemctl is-enabled fail2ban`) | `enabled` | +| Provider / plan | Fasthosts UK; KVM `1-1-10` | +| CPU / RAM | 1 vCore, AMD EPYC-Milan reported; 1 GB plan / 864.37 MiB guest | +| Disk | 10 GB NVMe plan / 9.64 GiB ext4 root; no swap | +| OS / kernel | Debian 13 x86_64; `6.12.85+deb13-amd64` | +| Hostname | `mercury`; older snapshot: `my-vps` | +| Public interface | `ens6`; `185.230.217.66/32` | +| Created / payment | `2026-03-01 20:48:51`, timezone unknown; GBP 10 prepaid/year | +| Administration | From Jupiter: `ssh mercury`; nginx/WireGuard apt-managed | +| Certificates | `/etc/letsencrypt/live//{fullchain.pem,privkey.pem}`; renewal method unknown | -The purge age controls cleanup of old database ban history; it is not the ban -duration and does not define log-file retention. Log rotation and retained -log history have not yet been inspected. The database is not an established -long-term event archive, so a future historical ban-count widget must account -for cleanup and log rotation rather than treating it as complete history. +- Ingress, tunnel addresses and nginx configuration: [Networking](networking.md). +- Alert scope, thresholds and Discord destinations: [Operations](operations.md#observability). -Boot enablement does not by itself prove service health or successful -enforcement. Current bans can be inspected without changing configuration: +## Uptime Kuma runtime -```bash +- Supplied launch script: `~/uptime-kuma.sh`; Compose replacement in `mercury/stacks/uptime-kuma/docker-compose.yml` is **not confirmed deployed**. +- Image `louislam/uptime-kuma:2-slim`; container `uptime-kuma`; restart `unless-stopped`. +- Bind `/opt/uptime-kuma:/app/data`; loopback `127.0.0.1:3001`. +- Limits: **300 MiB / 0.5 CPU**; `json-file` logs **10 MiB x 3**. +- Stop before copying state for migration; preserve the bind directory. nginx stays host-managed. + +## Firewall / Fail2ban + +- Supplied firewall: UFW/iptables INPUT + FORWARD `DROP`; OUTPUT `ACCEPT`. +- Allows TCP `22,80,443`; UDP `80,443,51820`. Docker forwarding has separate rules. +- Fail2ban **1.1.0**, enabled at boot; effective settings from **2026-10-26**: + +| Jail | Source | Retries / window | Ban | +| --- | --- | --- | --- | +| `sshd` | journal: `_SYSTEMD_UNIT=ssh.service + _COMM=sshd` | 5 / 600s | 600s | +| `nginx-http-auth` | `/var/log/nginx/error.log` | 3 / 600s | 600s | +| `nginx-botsearch` | `/var/log/nginx/access.log` | 2 / 600s | 3600s | + +- All three: action `nftables`; `ignoreip` empty. SSH journal `+` means **OR**. +- nginx jails target `http,https`. Action names do not prove blocked chains, ports or IPv6 coverage. +- Persistent overrides: `/etc/fail2ban/jail.local` (nginx filters/paths/retries; botsearch timing) and `jail.d/defaults-debian.conf` (SSH systemd backend/match; nftables defaults). +- `banaction_allports=nftables[type=allports]` is defined; active use is unconfirmed. Other timing values are inherited. +- Log: `/var/log/fail2ban.log`; DB: `/var/lib/fail2ban/fail2ban.sqlite3`; `dbpurgeage=86400`. +- DB purge age is **not** ban duration or log retention; escalation, rotation and config backup remain unknown. +- No administrator IP exemption: retain recovery access before testing failed logins. + +```sh +sudo fail2ban-client version +sudo fail2ban-client status sudo fail2ban-client status sshd sudo fail2ban-client status nginx-http-auth sudo fail2ban-client status nginx-botsearch ``` - -Rules and versions are supplied snapshots, not live inspection. diff --git a/docs/home-server/networking.md b/docs/home-server/networking.md index bb08c44..2d660a2 100644 --- a/docs/home-server/networking.md +++ b/docs/home-server/networking.md @@ -2,188 +2,124 @@ schema_version: 1 id: home-server.networking type: reference -scope: [jupiter, mercury, airvpn, downloads, dns, ingress, wireguard, cloudflare] +scope: [jupiter, mercury, dns, ingress, wireguard, cloudflare] sensitivity: private-infrastructure -last_reviewed: "2026-10-26" +last_reviewed: "2026-10-27" sources: - kind: owner-report - reference: "AirVPN local downloads and direct home-ISP egress live; public qBittorrent UI and both authentication layers working; Ultra.cc/rclone mount retired; full failure/leak checks outstanding, 2026-10-26" + reference: "DNS/Cloudflare/network snapshots 2026-10-06; ingress cutover verified 2026-10-27" + - kind: live-inspection + reference: "Traefik/nginx configuration, source rejection, keepalive, WebSockets and tunnel MTU checked 2026-10-27; Immich not running" - kind: repository repository: jupiter-stacks - revision: working-tree - base_revision: 631e4fdfa4c7122e5eff38e11b070c17ff7a4a2a - paths: - - stacks/downloads/docker-compose.yml - - stacks/traefik/docker-compose.yml - - kind: owner-report - reference: "Network topology, Mercury nginx/iptables/fail2ban output, LAN DNS, 2026-10-06" - - kind: owner-report - reference: "Cloudflare ingress YAML and client SSH configurations, 2026-10-06" - - kind: owner-report - reference: "CGNAT rationale, Docker network and container inspection, 2026-10-06" - - kind: owner-report - reference: "Ultra.cc hostname, qBittorrent UI, SFTP rclone remote/systemd unit and Radarr/Sonarr bind mounts, 2026-10-06" - - kind: owner-report - reference: "Authentik fully deployed with all listed app integrations and Authelia retired, 2026-10-16" - - kind: repository - repository: jupiter-stacks - revision: 610e325ef6a98850511ce7a089b0b9a77bfecf15 - paths: - - stacks/traefik/docker-compose.yml - - stacks/cloudflared/docker-compose.yml - - stacks/gitea/docker-compose.yml - - stacks/jellyfin/docker-compose.yml - - stacks/audiobookshelf/docker-compose.yml - - kind: repository - repository: jupiter-stacks - revision: d09df456ad331b8beb9a40615114ea8aae2dced5 - paths: - - stacks/authentik/docker-compose.yml - - stacks/authentik/blueprints/jupiter.yaml -related: [home-server.reference, home-server.host, home-server.mercury, home-server.downloads, home-server.seedbox, home-server.authentication, home-server.operations] -update_triggers: [dns-change, proxy-change, tunnel-change, firewall-change, certificate-change, seedbox-change] -unknowns: - - public-dns-record-types-and-cloudflare-proxy-status - - cloudflare-access-applications-and-login-policies - - wireguard-allowedips-and-keepalive - - jupiter-firewall-policy - - traefik-forwarded-header-trust-configuration - - complete-airvpn-failure-dns-and-ipv6-isolation-results + revision: 12fb1b96e01fc062fdce4c216f11eb5d7ce716ed + paths: [stacks/traefik/docker-compose.yml, stacks/cloudflared/docker-compose.yml, mercury/nginx/conf.d/upstreams.conf, mercury/nginx/umbra.mom, mercury/nginx/john.gatward.dev, mercury/nginx/samstoreymusic.com] +related: [home-server.mercury, home-server.downloads, home-server.authentication, home-server.deployment] +update_triggers: [dns-change, proxy-change, tunnel-change, firewall-change, certificate-change] +unknowns: [public-dns-record-types-and-cloudflare-proxy-status, cloudflare-access-policies, wireguard-allowedips-and-keepalive, jupiter-firewall-policy] --- # Networking -## AirVPN downloads - -[VPN-isolated local downloads](downloads.md) are live by owner report on -2026-10-26. Gluetun connects directly to AirVPN through the home ISP, separate -from the existing Mercury tunnel. Ultra.cc and the rclone/FUSE mount are retired. -This cuts subscription costs and removes the remote-storage/import dependency. -Full failure, DNS and IPv6 isolation checks are still outstanding. - -Public monitoring at `qbittorrent.umbra.mom` is working: Mercury's wildcard -HTTPS ingress reaches Traefik, which joins `downloads` and applies Authentik -per-user/MFA protection before proxying to `gluetun:8080`. The outpost callback -hostname is registered separately. This does not route torrent egress through -Mercury; see the [public-monitoring deployment steps](downloads.md#public-monitoring). - -## HTTPS ingress / local downloads +## Application ingress ```mermaid --- config: themeCSS: | - .node rect { rx: 8px; ry: 8px; stroke-width: 1.5px; } - .cluster rect { fill: var(--infra-zone) !important; stroke: var(--infra-border) !important; stroke-dasharray: 5 5; rx: 12px; ry: 12px; } - .label, .nodeLabel, .cluster-label { color: var(--infra-text) !important; } - .edgeLabel, .edgeLabel p { background-color: var(--infra-zone) !important; color: var(--infra-text) !important; } - .flowchart-link { stroke: var(--infra-line) !important; } - marker path { fill: var(--infra-line) !important; stroke: var(--infra-line) !important; } - .infraClient rect { fill: var(--infra-client-fill) !important; stroke: var(--infra-client-stroke) !important; } - .infraEdge rect { fill: var(--infra-edge-fill) !important; stroke: var(--infra-edge-stroke) !important; } - .infraService rect { fill: var(--infra-service-fill) !important; stroke: var(--infra-service-stroke) !important; } - flowchart: - curve: basis - nodeSpacing: 35 - rankSpacing: 55 + text,.nodeLabel,.cluster-label { fill:var(--infra-text);color:var(--infra-text); } + .edgeLabel,.edgeLabel p { background:var(--infra-zone);color:var(--infra-text); } + .flowchart-link { stroke:var(--infra-line); } + marker path { fill:var(--infra-line);stroke:var(--infra-line); } + .cluster rect { fill:var(--infra-zone);stroke:var(--infra-border);stroke-dasharray:5 5;rx:12px;ry:12px; } + .cluster span,.cluster text { color:var(--infra-text)!important;fill:var(--infra-text)!important; } + .infraClient rect { fill:var(--infra-client-fill);stroke:var(--infra-client-stroke);rx:8px;ry:8px; } + .infraEdge rect { fill:var(--infra-edge-fill);stroke:var(--infra-edge-stroke);rx:8px;ry:8px; } + .infraService rect { fill:var(--infra-service-fill);stroke:var(--infra-service-stroke);rx:8px;ry:8px; } --- flowchart TB - Internet["Public clients"] - - subgraph VPS["MERCURY / PUBLIC EDGE"] - Nginx["nginx
185.230.217.66
WireGuard 10.0.0.1"] - Uptime["Uptime service
127.0.0.1:3001"] - Nginx -->|"uptime.umbra.mom / HTTP"| Uptime + accTitle: Public and LAN application ingress + accDescr: Public HTTPS terminates at Mercury; HTTP crosses encrypted WireGuard to Jupiter. LAN HTTPS bypasses Mercury. + Public["Public clients"]:::infraClient + LAN["LAN clients"]:::infraClient + subgraph Mercury["MERCURY / PUBLIC EDGE"] + Edge["nginx
185.230.217.66
WG 10.0.0.1"]:::infraEdge + Kuma["Uptime Kuma
127.0.0.1:3001"]:::infraService end - - subgraph Home["JUPITER / HOME SERVER"] - LAN["LAN clients
Jellyfin / Bookshelf local DNS"] - Traefik["Traefik
192.168.1.56
WireGuard 10.0.0.2"] - Apps["Application containers
Docker network: traefik"] - Arr["Radarr / Sonarr
Download control / media imports"] - Qbit["qBittorrent
Shared Gluetun namespace"] - Gluetun["Gluetun
WireGuard / firewall
downloads Docker network"] - Downloads["Local torrents / libraries
/data/jellyfin
Hardlink imports"] - Router["Home router / ISP
Encrypted VPN underlay"] - LAN -->|"HTTPS :443"| Traefik - Traefik -->|"Application routing"| Apps - Traefik -->|"Media management UIs"| Arr - Traefik -->|"Authentik + qBittorrent login / :8080"| Gluetun - Gluetun -->|"Web UI / API"| Qbit - Arr -->|"downloads network / gluetun:8080"| Gluetun - Arr -->|"Local hardlink imports"| Downloads - Qbit -->|"Writes downloads"| Downloads - Qbit -->|"VPN-only torrent traffic"| Gluetun - Gluetun -->|"Encrypted AirVPN WireGuard"| Router + subgraph Jupiter["JUPITER / HOME"] + Proxy["Traefik
LAN 192.168.1.56
WG 10.0.0.2"]:::infraEdge + Apps["Application containers"]:::infraService end - - AirVPN["AirVPN
Public VPN exit / reserved peer port"] - Peers["Torrent peers"] - Internet -->|"HTTPS :443"| Nginx - Nginx -->|"HTTPS :443 over WireGuard"| Traefik - Router -->|"Home ISP / not Mercury"| AirVPN - AirVPN <-->|"Torrent traffic"| Peers - - class Internet,LAN,Peers infraClient - class Nginx,Traefik,Router,AirVPN infraEdge - class Apps,Uptime,Arr,Gluetun,Qbit,Downloads infraService + Public -->|"HTTPS :443"| Edge + Edge -->|"HTTP :8081 / encrypted WireGuard"| Proxy + LAN -->|"HTTPS :443"| Proxy + Proxy -->|"HTTP / Docker networks"| Apps + Edge -->|"uptime.umbra.mom / HTTP"| Kuma ``` -## Cloudflare Tunnel +- Cutover verified by owner **2026-10-27**; browser/OIDC URLs remain HTTPS. +- CGNAT requires Mercury's public IPv4; no residential public ingress. +- Admin hostnames are still public: the tunnel listener is **not private admin access**. +- Torrent egress uses a separate path: [AirVPN](downloads.md#current-topology). + +### Listener and trust boundaries + +| Traefik entrypoint | Behaviour | +| --- | --- | +| `http`, TCP 80 | Redirect to HTTPS; not Mercury's upstream | +| `https`, TCP 443 | TLS + `letsencrypt` defaults; LAN access and transport rollback | +| `wireguard`, `10.0.0.2:8081` | HTTP; `mercury-only@docker` admits TCP source `10.0.0.1/32` only | + +- Public routers: `entrypoints=https,wireguard`; **no router-level TLS settings**. +- Local-only routers: HTTPS only, explicit TLS. Separate HTTPS/WireGuard fallbacks redirect unmatched non-apex hosts to `https://umbra.mom` at priority `1`. +- Forwarded headers trusted only from `10.0.0.1/32` on `https` and `wireguard`. +- nginx sets `Host`, `X-Forwarded-Host`, `X-Forwarded-Port`, `X-Forwarded-Proto`, `X-Real-IP` and `X-Forwarded-For`; client IP is `$remote_addr`, not an appended untrusted chain. +- Admission uses connection source, **not** `X-Forwarded-For`; forged headers do not bypass the allowlist. +- Security-header middleware: `sslProxyHeaders.X-Forwarded-Proto=https` preserves HSTS on the HTTP hop. +- Docker provider: opt-in labels, network `traefik`; file provider: `/data/traefik/dynamic`; custom certificates: `/data/traefik/certs`. +- ACME: Cloudflare DNS-01; `/data/traefik/acme/acme.json`; `umbra.mom` + `*.umbra.mom`. +- Authentication is per application/router, not a universal gate: [Authentication](authentication.md). + +### nginx upstream + +- Shared `jupiter_backend`: `10.0.0.2:8081`; HTTP/1.1; **16 cached idle connections per worker**, not a concurrency limit. +- `Connection` cleared for normal requests and registry `/v2/`; `upgrade` only for WebSockets. +- Config: `/etc/nginx/conf.d/upstreams.conf` + three domain files in `sites-available/`; `nginx.conf` must include `conf.d/*.conf` and `sites-enabled/*` inside `http`. +- Gitea `/v2/`: unlimited body; `900s` proxy timeouts. +- MTU **1420** on both WireGuard interfaces; full-size non-fragmenting probes passed, approximately **7-8 ms** RTT. No sustained throughput/CPU benchmark. +- Rollout and rollback: [Deployment](deployment.md#ingress-transport-deployment-and-rollback). + +## SSH / Cloudflare Tunnel ```mermaid --- config: themeCSS: | - .node rect { rx: 8px; ry: 8px; stroke-width: 1.5px; } - .cluster rect { fill: var(--infra-zone) !important; stroke: var(--infra-border) !important; stroke-dasharray: 5 5; rx: 12px; ry: 12px; } - .label, .nodeLabel, .cluster-label { color: var(--infra-text) !important; } - .edgeLabel, .edgeLabel p { background-color: var(--infra-zone) !important; color: var(--infra-text) !important; } - .flowchart-link { stroke: var(--infra-line) !important; } - marker path { fill: var(--infra-line) !important; stroke: var(--infra-line) !important; } - .infraClient rect { fill: var(--infra-client-fill) !important; stroke: var(--infra-client-stroke) !important; } - .infraCloud rect { fill: var(--infra-cloud-fill) !important; stroke: var(--infra-cloud-stroke) !important; } - .infraEdge rect { fill: var(--infra-edge-fill) !important; stroke: var(--infra-edge-stroke) !important; } - .infraService rect { fill: var(--infra-service-fill) !important; stroke: var(--infra-service-stroke) !important; } - flowchart: - curve: basis - nodeSpacing: 35 - rankSpacing: 45 + text,.nodeLabel { fill:var(--infra-text);color:var(--infra-text); } + .edgeLabel,.edgeLabel p { background:var(--infra-zone);color:var(--infra-text); } + .flowchart-link { stroke:var(--infra-line); } + marker path { fill:var(--infra-line);stroke:var(--infra-line); } + .infraClient rect { fill:var(--infra-client-fill);stroke:var(--infra-client-stroke);rx:8px;ry:8px; } + .infraCloud rect { fill:var(--infra-cloud-fill);stroke:var(--infra-cloud-stroke);rx:8px;ry:8px; } + .infraEdge rect { fill:var(--infra-edge-fill);stroke:var(--infra-edge-stroke);rx:8px;ry:8px; } + .infraService rect { fill:var(--infra-service-fill);stroke:var(--infra-service-stroke);rx:8px;ry:8px; } --- -flowchart TB - Shell["SSH client
Host jupiter / user jay"] - Git["Git over SSH
Host git.umbra.mom / user git"] - Cloud["Cloudflare Tunnel edge
Access policy unconfirmed"] - - subgraph Home["JUPITER / HOME SERVER"] - Connector["cloudflared
Locally configured ingress"] - SSH["Host sshd
192.168.1.56:22"] - Gitea["Gitea SSH
192.168.1.56:2222"] - Connector -->|"ssh.umbra.mom / SSH :22"| SSH - Connector -->|"git.umbra.mom / SSH :2222"| Gitea - end - - Shell -->|"cloudflared access ssh / ssh.umbra.mom"| Cloud - Git -->|"cloudflared access ssh / git.umbra.mom"| Cloud - Cloud <-->|"Tunnel traffic / initiated outbound by Jupiter"| Connector - - class Shell,Git infraClient - class Cloud infraCloud - class Connector infraEdge - class SSH,Gitea infraService +flowchart LR + accTitle: SSH through Cloudflare, separate from application ingress + accDescr: The client uses cloudflared; Jupiter's outbound connector reaches host SSH or Gitea SSH without Mercury or Traefik. + Client["SSH client
cloudflared access ssh"]:::infraClient + Edge["Cloudflare edge"]:::infraCloud + Tunnel["Jupiter cloudflared
outbound connector"]:::infraEdge + Host["Host sshd
192.168.1.56:22"]:::infraService + Git["Gitea SSH
192.168.1.56:2222"]:::infraService + Client --> Edge <--> Tunnel + Tunnel -->|"ssh.umbra.mom"| Host + Tunnel -->|"git.umbra.mom"| Git ``` -Client `cloudflared` transports SSH through Cloudflare; Jupiter's connector opens -the outbound tunnel. Origins still perform SSH authentication. No Mercury, -WireGuard, or Traefik hop on this path; no home-router port forwarding. - -| Ingress hostname | Origin | Client SSH user | -| --- | --- | --- | -| `ssh.umbra.mom` | `ssh://192.168.1.56:22` | `jay` | -| `git.umbra.mom` | `ssh://192.168.1.56:2222` | `git` | -| Unmatched | `http_status:404` | N/A | - -Both client configurations use `IdentityFile ~/.ssh/id_ed25519`. +- No Mercury, WireGuard, Traefik or home-router port forwarding on this path. +- Connector config: `/data/cloudflared/config.yaml` -> `/etc/cloudflared/config.yaml`; unmatched ingress: `http_status:404`. +- Cloudflare Access login/allow policies remain unconfirmed; SSH origins still authenticate users. ```sshconfig Host jupiter @@ -197,106 +133,26 @@ Host git.umbra.mom ProxyCommand cloudflared access ssh --hostname %h ``` -Local tunnel configuration is separate from Cloudflare Access applications. -Access login/provider/allow rules remain unconfirmed; `ProxyCommand` alone -does not establish enforcement. +## DNS -Ingress source: host `/data/cloudflared/config.yaml`, mounted at -`/etc/cloudflared/config.yaml`. - -## DNS / routes - -| DNS / route | Destination | +| Names | Destination | | --- | --- | -| Public service ingress | Mercury `185.230.217.66` | -| `jellyfin.local.umbra.mom` | Jupiter `192.168.1.56` | -| `bookshelf.local.umbra.mom` | Jupiter `192.168.1.56` | +| Public application names | Mercury `185.230.217.66` | +| `jellyfin.local.umbra.mom`, `bookshelf.local.umbra.mom` | Jupiter LAN `192.168.1.56`; bypass Mercury | | `ssh.umbra.mom`, `git.umbra.mom` | Cloudflare Tunnel | -| `uptime.umbra.mom` | Mercury nginx -> `http://127.0.0.1:3001` | -| `qbittorrent.umbra.mom` | Mercury -> Traefik -> Authentik -> Gluetun/qBittorrent `8080`; native login retained | -| `gluetun:8080` | Internal authenticated qBittorrent API on the `downloads` Docker network | -## Download connectivity +## Docker networks -qBittorrent now runs on Jupiter in Gluetun's network namespace. The enabled -Gluetun firewall and qBittorrent's `wg0` binding are configured for VPN-only -torrent egress. AirVPN's reserved peer port is allowed through the VPN firewall, -not published on Jupiter or forwarded on the home router. Working downloads -alone do not demonstrate inbound peer reachability or failure isolation. +2026-10-06 supplied snapshot; use service names, not container IPs. -Sonarr/Radarr and optional Prowlarr direct downloads use `gluetun:8080` with -native qBittorrent credentials, not the public Authentik-protected URL. -Their ordinary internet routes and Prowlarr/FlareSolverr indexer traffic remain -outside AirVPN. The Web UI also has a loopback-only `127.0.0.1:8080` publication -for private SSH forwarding. - -Imports now use local storage and hardlinks, not SFTP/FUSE. The former -[Seedbox](seedbox.md) page is historical; its service and mount are removed. -See [Storage](storage.md) for current placement and -[Local downloads](downloads.md) for the runbook and remaining checks. - -## Mercury - -[Mercury VPS](mercury.md): native nginx; WireGuard server `10.0.0.1/24`; -Jupiter client `10.0.0.2/24`. Hosting, TLS, firewall and fail2ban details are -maintained on that page. - -Home ISP uses CGNAT. Mercury supplies a static public IPv4 and forwards over -WireGuard; owner preference is to avoid public ingress via the residential IP. - -## Observed Docker networks - -Snapshot from supplied inspection, not fixed-address configuration. Container -IPs may change; use Docker service names. - -| Network | IPv4 subnet | Internal | Observed role | +| Network | Subnet | Internal | Role | | --- | --- | --- | --- | -| `traefik` | `172.18.0.0/16` | No | Reverse proxy and application ingress | -| `gitea_network` | `172.23.0.0/16` | No | Gitea, runner, notes builder, Havox sync | +| `traefik` | `172.18.0.0/16` | No | Application ingress | +| `gitea_network` | `172.23.0.0/16` | No | Gitea, runner, builder, Havox | | `cloudflared_cloudflare` | `172.26.0.0/16` | No | Tunnel connector | -| `gitea_data` | `192.168.96.0/20` | Yes | Gitea and PostgreSQL | -| `paperless_data` | `192.168.112.0/20` | Yes | Paperless, PostgreSQL, Redis | -| `dozzle_dozzle` | `172.27.0.0/16` | Yes | Dozzle and socket proxy | +| `gitea_data` | `192.168.96.0/20` | Yes | Gitea/PostgreSQL | +| `paperless_data` | `192.168.112.0/20` | Yes | Paperless/PostgreSQL/Redis | +| `dozzle_dozzle` | `172.27.0.0/16` | Yes | Dozzle/socket proxy | -Cloudflared's observed `172.26.0.2` matches the supplied proxied SSH login source. -An internal network alone does not isolate a multi-network container from -egress through its other networks. Empty network entries do not establish -whether they are obsolete or safe to remove. - -The newer `downloads` bridge is defined with IPv6 disabled and is not internal. -Gluetun, Traefik, Sonarr, Radarr and Prowlarr attach to it; qBittorrent shares -Gluetun's namespace rather than joining independently. Its subnet was not -recorded. This supplements, rather than re-inspects, the older table. - -## Jupiter: repository configuration - -- Traefik publishes TCP `80,443`; HTTP redirects to HTTPS. -- Docker provider: opt-in `traefik.enable=true`; external network `traefik`. -- File provider: `/data/traefik/dynamic`. -- ACME: Let's Encrypt; Cloudflare DNS-01; `/data/traefik/acme/acme.json`; - apex + `*.umbra.mom` certificate requested. -- HTTPS fallback: priority `1`; unmatched non-apex hosts redirect to `https://umbra.mom`. -- `cloudflared`: `/data/cloudflared` -> `/etc/cloudflared`; - stack-local bridge `cloudflare`; no published ports. - -## Authentication routing - -[Authentik](authentication.md) serves `auth.umbra.mom` through Traefik to -`authentik-server:9000`; the server joins the external `traefik` network. -The ingress diagrams show transport, not a universal authentication gate. -Native OIDC integrations are listed on the authentication page; Backrest, Notes, -Prowlarr, Radarr, Sonarr and qBittorrent -use Traefik middleware `authentik@docker` and the embedded outpost. -Dozzle (`logs.umbra.mom`) now uses OIDC, not forward-auth. - -On the six proxy-protected hostnames, a priority-1000 -`/outpost.goauthentik.io/` route goes straight to Authentik without forward-auth -to handle callbacks. Other application requests use their normal routers. -The middleware trusts forwarded headers; this is not evidence that the wider -Mercury/Traefik forwarded-header trust chain is configured. - -Authentik also publishes `127.0.0.1:9000` for private host access. -Repository-defined networks (not part of the older observed-network snapshot): -`authentik-data` is internal and connects PostgreSQL, server and worker; -the worker also joins `authentik-egress`. The server's additional `traefik` -attachment means the internal data network is not complete egress isolation. +- Newer networks: [Downloads](downloads.md), [Notes build](notes.md#networks-and-webhook-allowlist), [Authentik](authentication.md#state-secrets); not part of this snapshot. +- `internal` does not block egress through a container's other networks; unused-looking networks are not automatically safe to delete. diff --git a/docs/home-server/notes.md b/docs/home-server/notes.md index 353b761..d8d561f 100644 --- a/docs/home-server/notes.md +++ b/docs/home-server/notes.md @@ -2,112 +2,83 @@ schema_version: 1 id: home-server.notes type: reference -scope: [jupiter, notes, gitea, webhooks, stack-deployment] +scope: [jupiter, notes, gitea, webhooks] sensitivity: private-infrastructure -last_reviewed: "2026-10-16" +last_reviewed: "2026-10-27" sources: - kind: repository repository: jupiter-stacks revision: f39d0f4028f9fe70f838a0ec577d10ab11409f5c - paths: - - stacks/gitea/docker-compose.yml - - stacks/notes/docker-compose.yml - - stacks/notes/listener.py - - stacks/notes/nginx.conf + paths: [stacks/gitea/docker-compose.yml, stacks/notes/docker-compose.yml, stacks/notes/listener.py, stacks/notes/nginx.conf] - kind: owner-report - reference: "Gitea private-address egress rejection, Docker network overlap failure, network inventory and host routes, 2026-10-16" -related: [home-server.reference, home-server.deployment, home-server.networking, home-server.storage, home-server.authentication] -update_triggers: [notes-stack-change, builder-change, webhook-change, network-change, deployment-workflow-change] -unknowns: [successful-deployment-of-notes-build-network, successful-webhook-redelivery] + reference: "Private-address webhook rejection, subnet overlap and host/network inventory, 2026-10-16" +related: [home-server.deployment, home-server.networking, home-server.storage, home-server.authentication] +update_triggers: [builder-change, webhook-change, network-change] +unknowns: [successful-notes-build-network-deployment, successful-webhook-redelivery] --- -# Notes +# Notes publication -The repository configuration separates building the documentation from serving -it. The current network configuration is intended state, not confirmation that -the failed deployment has been recovered. +Repository intent; recovery from the previously failed deployment is unconfirmed. -## Services and build flow +```mermaid +--- +config: + themeCSS: | + text,.nodeLabel { fill:var(--infra-text);color:var(--infra-text); } + .edgeLabel,.edgeLabel p { background:var(--infra-zone);color:var(--infra-text); } + .flowchart-link { stroke:var(--infra-line); } + marker path { fill:var(--infra-line);stroke:var(--infra-line); } + .infraClient rect { fill:var(--infra-client-fill);stroke:var(--infra-client-stroke);rx:8px;ry:8px; } + .infraEdge rect { fill:var(--infra-edge-fill);stroke:var(--infra-edge-stroke);rx:8px;ry:8px; } + .infraStorage rect,.infraStorage path { fill:var(--infra-storage-fill);stroke:var(--infra-storage-stroke); } + .infraService rect { fill:var(--infra-service-fill);stroke:var(--infra-service-stroke);rx:8px;ry:8px; } +--- +flowchart LR + accTitle: Signed webhook to built documentation + accDescr: Gitea queues a signed push; a single builder writes the shared static volume; nginx serves it read-only. + Git["Gitea push
main"]:::infraClient + Builder["notes_builder :9000
HMAC check / queue / build"]:::infraEdge + Static[("notes_static
generated site")]:::infraStorage + Web["notes_web :8080
read-only nginx"]:::infraService + Git -->|"Signed POST"| Builder -->|"/site-output"| Static -->|"/usr/share/nginx/html"| Web +``` -| Component | Role | -| --- | --- | -| `notes_builder` | Zensical container running `/builder/listener.py`; receives signed Gitea webhooks on port `9000` and builds the `main` branch | -| `notes_web` | Unprivileged nginx serving the generated site on port `8080`; Traefik publishes `https://notes.umbra.mom` behind Authentik forward-auth | -| `notes_static` | Shared named volume: builder writes `/site-output`; nginx mounts `/usr/share/nginx/html` read-only | - -Gitea sends a push webhook to `http://notes_builder:9000/`. The listener checks -the `X-Gitea-Signature` HMAC against `WEBHOOK_SECRET`, queues accepted deliveries -and returns HTTP `202`. A single worker clones -`http://gitea:3000/jay/notes.git`, then runs: +- Web: `https://notes.umbra.mom`, Traefik + [Authentik forward-auth](authentication.md#forward-auth). +- Clone source: `http://gitea:3000/jay/notes.git`; requires `zensical.toml`, `pyproject.toml`, `uv.lock`. +- Listener `/builder/listener.py` checks `X-Gitea-Signature` with `WEBHOOK_SECRET`. +- **202 = queued**, not built. Single worker logs `Documentation build succeeded` after generated `index.html`. +- Publication replaces volume contents non-atomically; brief missing files possible. Starting an empty builder does not trigger a build. ```sh uv run --locked zensical build --clean --config-file zensical.toml ``` -The repository must contain `zensical.toml`, `pyproject.toml` and `uv.lock`. -After a successful build with a generated `index.html`, the worker replaces the -contents of `notes_static`. Publication is not atomic: nginx can briefly see -missing files during replacement. HTTP `202` means queued, not build completed; -look for `Documentation build succeeded` in the builder logs. - ## Networks and webhook allowlist -| Setting | Repository configuration | +| Setting | Value | | --- | --- | -| Build network | `notes_build`, owned by the Gitea stack and external to the Notes stack | -| Subnet | `10.90.0.0/29` | -| Builder address | `10.90.0.3` | -| Gitea allowlist | `GITEA__security__ALLOWED_HOST_LIST: "10.90.0.3:9000"` | -| Web network | `notes_web` joins `traefik`; the builder does not | +| Build network | `notes_build`, Gitea-owned / external to Notes; `10.90.0.0/29` | +| Builder IP / webhook | `10.90.0.3`; `http://notes_builder:9000/` | +| Gitea setting | `GITEA__security__ALLOWED_HOST_LIST="10.90.0.3:9000"` | +| Web network | `notes_web` on `traefik`; builder not attached | -Gitea 28 requires an explicit IP allow entry for a private destination. -`notes_builder:9000` alone did not permit the resolved Docker IP. Keep the -network subnet, builder static IP and allowlist consistent; do not broadly allow -all private destinations. - -The first proposed subnet, `172.30.90.0/29`, overlapped an Actions network using -`172.30.0.0/16`. The replacement does not overlap the owner-supplied network -inventory or routes. Recheck for collisions before rebuilding on another host. -The build network is not internal: the builder needs outbound access to install -Git, uv and locked Python dependencies. +- Gitea 28 requires resolved private IP allowlisting; hostname alone failed. Do not broadly allow private networks. +- Recheck subnet collisions on recovery; old `172.30.90.0/29` overlapped Actions' `172.30.0.0/16`. +- Build network is non-internal: dependency installation requires outbound access. ## Deployment -Stack definitions follow the [Portainer Git deployment workflow](deployment.md). -Changing this documentation does not deploy either stack. +1. Push stack changes; preserve Portainer values. Copy listener/nginx config into `/data/notes/{listener.py,nginx.conf}`; Git pull does not update binds. +2. Set matching `WEBHOOK_SECRET` in Notes and Gitea's push webhook; retain the internal webhook URL. +3. Redeploy **Gitea first**; confirm `notes_build` has the expected subnet/allowlist. +4. Redeploy Notes outside an active build; preserve `notes_static`, never remove volumes. +5. Wait for healthy Gitea and builder `Listening on 9000`; redeliver the webhook. +6. Confirm 202, build-success log and authenticated updated page. -1. Push the updated Compose definitions to `jupiter-stacks/main`. Preserve the - existing production environment settings in Portainer. -2. On Jupiter, ensure `/data/notes/listener.py` and `/data/notes/nginx.conf` contain - the corresponding repository files. These are read-only bind mounts; pulling - the stack repository does not populate or update them. -3. Set `WEBHOOK_SECRET` in the Notes stack environment and the same secret in the - Gitea Notes repository's push webhook. Keep the URL - `http://notes_builder:9000/`; do not put the secret in Git or these notes. -4. Update/redeploy the **Gitea stack first**. It creates `notes_build` and applies - the IP allow entry. Expect a brief Gitea interruption. -5. Confirm `docker network inspect notes_build` reports `10.90.0.0/29`, then - update/redeploy the **Notes stack**. Avoid interrupting an active build. - Preserve `notes_static`; do not remove volumes. -6. Wait for Gitea to be healthy and for `docker logs notes_builder` to show - `Listening on 9000`. Redeliver the failed push webhook in Gitea. -7. Confirm HTTP `202`, a successful build in the builder logs, and the updated - page through `https://notes.umbra.mom` after authentication. +## Health / troubleshooting -Starting the builder alone does not trigger an initial build. If the static -volume is empty, nginx cannot serve the site until an accepted webhook completes. - -## Health and troubleshooting - -`notes_web` uses `/` on port `8080` for its container health check. For Homarr on -the shared `traefik` network, use `http://notes_web:8080/`. - -The builder has no GET health endpoint or Compose health check; its listener -accepts signed POST requests only. Do not configure an ordinary HTTP GET ping -against `http://notes_builder:9000/`, or attach it to `traefik` just for a ping. - -If Notes reports `network notes_build declared as external, but could not be -found`, fix the Gitea network creation failure first. A subnet-overlap failure -requires an unused range, not deletion of unrelated Docker networks. If delivery -is accepted but the site does not update, inspect the builder logs for clone, -dependency installation, build or publication errors. +- Web probe: `http://notes_web:8080/` on `traefik`. +- Builder accepts signed POST only; no GET health endpoint/Compose healthcheck. Do not expose it on Traefik for probing. +- Missing external network: fix Gitea's network creation first. Subnet collision: choose a free range, **not deletion of unrelated networks**. +- Accepted delivery without update: inspect clone/dependency/build/publication errors in builder logs. diff --git a/docs/home-server/operations.md b/docs/home-server/operations.md index ad1173b..df6717e 100644 --- a/docs/home-server/operations.md +++ b/docs/home-server/operations.md @@ -2,201 +2,65 @@ schema_version: 1 id: home-server.operations type: reference -scope: [jupiter, mercury, design-decisions, monitoring, recovery] +scope: [jupiter, mercury, monitoring, troubleshooting] sensitivity: private-infrastructure -last_reviewed: "2026-10-26" +last_reviewed: "2026-10-27" sources: - kind: owner-report - reference: "Sonarr, Radarr and Prowlarr now have alerting enabled; destination and enabled events not supplied, 2026-10-26" - - kind: owner-report - reference: "AirVPN local downloads live, Ultra.cc/rclone retired; cost saving and simpler architecture; GBP 56.06 three-year plan ends 2029-10-25; imports/hardlinks confirmed, full isolation checks and backups outstanding, 2026-10-26" - - kind: owner-report - reference: "RAID/media tradeoff, CGNAT/public IPv4 rationale, no alerting and running monitoring/log containers, 2026-10-06" - - kind: owner-report - reference: "Outages over one day catastrophic; no independent credentials except restic key, recovery evidence, host-config archive or operational rules, 2026-10-06" - - kind: owner-report - reference: "OIDC and three-group motivation; Authentik fully deployed and Authelia retired; updated six-directory backup plan; independent recovery custody unchanged, 2026-10-16" - - kind: owner-report - reference: "Notifications received in Discord server Jupiter: Beszel in #beszel-alerts, Backrest in #backrest-alerts, and Mercury Uptime Kuma in #uptimekuma-alerts, 2026-10-23" - - kind: owner-report - reference: "Mercury Uptime Kuma only checks WireGuard tunnel health and Jupiter online status, notifying Jay on Discord when down; Kuma per-container monitoring not configured, 2026-10-26" - - kind: owner-report - reference: "Beszel sends Discord alerts for any systemd error or any container down for more than two minutes, 2026-10-26" - - kind: owner-report - reference: "Mercury monitored in Beszel; CPU above 90% for 10 minutes, memory above 90% for 10 minutes and any failed systemd services alerts configured, 2026-10-26" + reference: "24h outage tolerance 2026-10-06; Discord receipt 2026-10-23; Beszel/Kuma/Arr alert configuration 2026-10-26" + - kind: live-inspection + reference: "Traefik 3.7.13 startup health/log timing and subsequent route recovery, 2026-10-27" - kind: documentation - reference: "Beszel v0.21.0 upstream internal/site/src/lib/alerts.ts and internal/alerts/alerts_container.go: Container Health alerts detect Docker unhealthy status, 2026-10-26" -related: [home-server.reference, home-server.host, home-server.mercury, home-server.downloads, home-server.networking, home-server.storage, home-server.authentication, home-server.backups, home-server.deployment] -update_triggers: [data-priority-change, architecture-change, alerting-change, recovery-test] -unknowns: - - acceptable-data-loss-and-recovery-order-by-service - - data-criticality-outside-the-six-backed-up-directories - - tested-full-host-recovery-order - - monitoring-review-frequency - - other-alert-rules-thresholds-and-exact-uptime-probes - - arr-alert-destinations-and-enabled-events + reference: "Traefik v3.7 pkg/provider/docker/config.go health filtering; Beszel v0.21.0 alerts.ts/alerts_container.go health semantics" +related: [home-server.backups, home-server.networking, home-server.authentication, home-server.downloads, home-server.host] +update_triggers: [alerting-change, outage, recovery-test] +unknowns: [exact-uptime-probes-and-timing, other-alert-thresholds, arr-alert-destinations-and-events, monitoring-review-frequency] --- -# Operations / decisions - -## Owner decisions - -| Decision | Reason / accepted tradeoff | -| --- | --- | -| RAID 0 for HDD data | Capacity prioritized over disk redundancy; downloaded media can be reacquired | -| Back up important state | Six application directories covered, subject to exclusions; media redundancy is not the objective | -| Mercury public edge | Static public IPv4; home ISP uses CGNAT | -| No residential public ingress | Owner preference to avoid exposing the home IP | -| AirVPN instead of Ultra.cc | Live local downloads reduce cost and simplify architecture: no remote seedbox or SFTP/FUSE import dependency; GBP 56.06 prepaid for three years, expires Thursday, 25 October 2029 | -| Authentik instead of Authelia | Native OIDC rather than only forward-auth; retain forward-auth where needed | -| Application access | 2026-10-26: replace the former Admin/Developers/Clients groups with manual per-user service bindings; keep `jay` as administrator with access to every configured application; repository prepared, deployment unconfirmed | - -RAID 0 still stores important state alongside media: either HDD failure loses -the array; recovery depends on working backups. Owner intent is not evidence -that every important dataset is covered. - -The Authentik migration is complete by owner report; Authelia is retired. -Exact repository group names, app assignments and MFA policy are in -[Authentication](authentication.md). Group access is not the same as application -administrator privileges or Authentik superuser status. - -## Download migration - -[Local downloads](downloads.md) are live by owner report on 2026-10-26. -Direct home-ISP egress, both Arr hardlink imports, seeding/removal and the public -UI's Authentik plus qBittorrent login are confirmed. Ultra.cc is -cancelled/expired, retained files are handled and the old mount/service removed. -The subscription saving is approximately GBP 35.31/year before incremental -electricity, compared with the former GBP 4.50/month seedbox. - -Remaining operational work: complete peer-ingress, DNS/IPv6 and -VPN-failure/startup/reboot isolation checks, and back up qBittorrent state/defaults -and AirVPN secrets. Normal successful downloads do not prove fail-closed behaviour. -The retired seedbox must not be assumed available for rollback. +# Operations ## Observability -| Facility | Current configuration | +Owner-confirmed configuration; Discord server **Jupiter**, receipt confirmed 2026-10-23. + +| Source | Coverage / trigger | Destination | +| --- | --- | --- | +| Beszel hub on Jupiter | Jupiter + Mercury; reported systemd errors / container down >2 min | `#beszel-alerts` | +| Mercury Beszel rules | CPU >90% for 10 min; RAM >90% for 10 min; failed systemd units | `#beszel-alerts` | +| Uptime Kuma on Mercury | WireGuard path and Jupiter availability only; alerts Jay | `#uptimekuma-alerts` | +| Backrest | Notifications enabled; exact hook events unknown | `#backrest-alerts` | +| Sonarr / Radarr / Prowlarr | Settings -> Connect enabled; events/destinations unknown | Not recorded | +| Dozzle | Container logs via Docker socket proxy | Web UI | + +- Beszel UI/database stores rules. `Failed Services` detects failed units, not every journal error; `Container Health` detects Docker `unhealthy`. Exact stopped/missing-container rules need inspection. +- Beszel cannot alert when Jupiter/hub is down; Kuma is independent of Jupiter but cannot report its own complete outage. +- Kuma has no application/container probes. Arr notifications do not establish empty-search, rejected-release or stalled-torrent coverage. +- Backup notifications do not prove integrity, service restart or detection of a backup that never ran; see [Backups](backups.md). + +### Proposed monitoring additions + +- Add authenticated-safe application health probes, not proxy/login-page checks; start at 60s / two retries. +- Test outage **and recovery** delivery during maintenance; account for scheduled backup stops. +- Add external Mercury monitoring and missed-backup detection. +- Remote Docker checks require a secured connection; Mercury's socket cannot inspect Jupiter. Never expose an unauthenticated Docker API just for monitoring. + +## Traefik startup troubleshooting + +- Symptom: `middleware "security-headers@docker" does not exist` immediately after restart. +- Cause: shared middleware lives on Traefik's Docker labels; the provider filters its container while health is `starting`/unhealthy. +- Observed 2026-10-27: errors **11:41:07 UTC**, first healthy check **11:41:11**; Homarr/Authentik routes recovered. +- Action: inspect health + latest logs, then request affected routes. Persistent errors after healthy status require provider/label investigation. +- Do **not** disable health checks or admit unhealthy services globally. +- Possible fix: move shared middleware to the file provider and update references together; **not implemented**. +- `aliasHeadersStrategy` and encoded-path warnings are separate; review backend compatibility before selecting policies. No warning-related settings changed. + +## Outstanding work + +| Priority | Work / canonical detail | | --- | --- | -| Host/container monitoring | Beszel monitors Jupiter and Mercury; existing systemd/container alerts plus Mercury CPU, memory and failed systemd service alerts (owner-confirmed) | -| Container logs | Dozzle with Docker socket proxy present | -| Uptime monitoring | Uptime Kuma on Mercury at `uptime.umbra.mom`; WireGuard tunnel health and Jupiter online status only | -| Automatic alerting | Discord delivery configured for Beszel, Backrest and Uptime Kuma; receipt confirmed by owner. Sonarr, Radarr and Prowlarr alerting enabled by owner report; destinations/events not recorded | - -### Arr application alerting - -**Sonarr, Radarr and Prowlarr all have alerting enabled**, confirmed by the -owner on 2026-10-26. Notification destinations, enabled events and delivery -confirmation have not been recorded. These settings are application-managed -state, not declared in the Compose files. - -Do not infer that this covers searches returning no acceptable releases, -missing media or stalled downloads: those conditions are not equivalent to -application health issues or explicit download failures. Alerting for them -requires separate confirmation of the configured events or additional monitoring. -See [Local downloads / AirVPN](downloads.md#alerting). - -### Discord notifications - -The owner confirms receiving notifications in the Discord server **Jupiter** -as of 2026-10-23: - -| Source | Channel | -| --- | --- | -| Beszel | `#beszel-alerts` | -| Backrest | `#backrest-alerts` | -| Uptime Kuma on Mercury | `#uptimekuma-alerts` | - -Mercury's Uptime Kuma alerts **Jay** in `#uptimekuma-alerts` when the WireGuard -tunnel or Jupiter availability checks fail; this scope was confirmed on -2026-10-26. Individual containers and applications are not currently monitored -by Kuma. - -Beszel sends alerts to **`#beszel-alerts`** for **any systemd error** or **any -container down for more than two minutes**, as confirmed by the owner on -2026-10-26. These are configured alerts, not proposed additions. - -Mercury is also monitored in Beszel, with the following alerts configured by -owner report on 2026-10-26: - -| Mercury alert | Trigger | -| --- | --- | -| CPU usage | Above 90% for 10 minutes | -| Memory usage | Above 90% for 10 minutes | -| Failed Services | Any failed systemd service | - -These settings are stored in the Beszel hub UI/database, not the agent Compose -file. The failed-services rule covers failed systemd units, not all journal -errors. - -Exact Kuma probes and timing, other Beszel rules/thresholds and Backrest hook -conditions have not been recorded. Monitoring of Mercury independent of Jupiter and -missed-backup alerts remain unconfirmed. No webhook URLs or tokens are stored -in these notes. - -### Alert coverage and optional additions - -Beszel's systemd/container outage alerting above is owner-reported deployed -state. The upstream Beszel `0.21.0` **Container Health** rule specifically checks -Docker `unhealthy` status, and **Failed Services** checks failed systemd units, -not every error-level journal entry. The exact live rules and stopped/missing -container detection have not been independently inspected. - -The following are optional additions, not configured Kuma monitors: - -1. In Mercury's Uptime Kuma, add an **HTTP(s)** monitor for each important - application's health endpoint, or a **TCP Port** monitor where HTTP is not - available. Enable the existing Discord notification on each monitor. - Start with a 60-second interval and two retries to tolerate brief restarts. - Check the application itself, not just a proxy or authentication login page. - Use a stable health endpoint with expected status/body; do not disable - authentication or expose private services solely for monitoring. -2. For additional container-running-state checks, Kuma's **Docker Container** - monitor needs a Docker host connection to the relevant machine. Mercury's - Docker socket only describes Mercury, not Jupiter, and a Portainer environment - connection does not automatically provide Kuma with Docker access. Remote - Docker monitoring needs a separately secured connection; do not expose an - unauthenticated Docker API or mount Jupiter's Docker socket into Kuma merely - to add application availability checks. -3. During a planned maintenance window, stop a non-critical monitored service, - confirm Jay receives the outage alert, then restart it and confirm recovery. - Account for scheduled backup stops before enabling noisy alerts. - -Application probes detect service failures even when Docker still reports a -container as running, but are not an inventory of every container's state. -Beszel on Jupiter cannot deliver alerts while Jupiter or the Beszel hub is down; -keep Mercury's independent tunnel/host checks. - -The backup plan stops Authentik, interrupting new OIDC logins and forward-auth -access. Authentik/Wardrowbe restart hooks ignore errors, so backup completion -alone does not establish that authentication or applications recovered. - -## Recovery status - -| Item | Current status | -| --- | --- | -| Jupiter outage tolerance | At most 24 hours; longer is catastrophic to the owner | -| Recovery time | Not measured; 24-hour objective is not demonstrated | -| Acceptable data loss / RPO | Not defined | -| Independent recovery secrets | Restic encryption key only | -| Backup/integrity evidence | None supplied | -| Restore exercise | Never performed | -| Independent host-config archive | Not maintained | -| Operational rules / rollback policy | Not established | - -Backup scope is documented in [Backups](backups.md). The six-directory plan now -includes Authentik identity/MFA state and Wardrowbe data, but does not establish -OS, broader host-configuration or named-volume recovery. There is still no -independent Authentik admin/MFA or stack-secret recovery arrangement. - -## Proposed recovery storage - -Not implemented: - -- Private Git repository: sanitized host configuration and bootstrap instructions. -- Encrypted off-host/offline archive: required credentials and secret-bearing configuration. -- Independent access instructions: account recovery, archive location and decryption. - -Access/decryption must work without Jupiter or Portainer. A private Git -repository is not a substitute for protecting secret values. Restic key custody -alone does not provide Google Drive access. +| Recovery | Outage tolerance **24h**, not demonstrated. Define per-service RPO/order and exercise [restores](backups.md#recovery-limits). | +| Startup | Ensure WireGuard owns `10.0.0.2` before Traefik binds; persistent ordering/reboot exercise unverified. | +| VPN isolation | Complete [AirVPN failure/startup/DNS/IPv6 exercises](downloads.md#remaining-validation). | +| Exposure | Private admin ingress is not implemented; public hostnames and Portainer's direct port still exist. | +| Docker logs | Confirm [daemon default activation and container recreation](host.md#docker-log-rotation). | +| Identity | Confirm [per-user bindings and Homarr linking](authentication.md); transport verification did not establish them. | diff --git a/docs/home-server/portainer.md b/docs/home-server/portainer.md index b7f5825..90672fd 100644 --- a/docs/home-server/portainer.md +++ b/docs/home-server/portainer.md @@ -2,81 +2,49 @@ schema_version: 1 id: home-server.portainer type: reference -scope: [jupiter, portainer, deployment, configuration-state] +scope: [jupiter, portainer, configuration-state] sensitivity: private-infrastructure -last_reviewed: "2026-10-16" +last_reviewed: "2026-10-27" sources: - - kind: owner-report - reference: "Deployed container, ~/portainer_start.sh and updated Backrest plan, 2026-10-06" - - kind: owner-report - reference: "GitHub main/PAT access, Portainer environment values, manual redeployment and container inspection, 2026-10-06" - - kind: owner-report - reference: "Authentik fully deployed with all listed app integrations, including Portainer, 2026-10-16" + - kind: live-inspection + reference: "Image 2.45.3, mounts, publication, restart policy and routers inspected 2026-10-27" - kind: repository repository: jupiter-stacks - revision: d09df456ad331b8beb9a40615114ea8aae2dced5 - paths: - - stacks/portainer/portainer_start.sh - - stacks/authentik/blueprints/jupiter.yaml -related: [home-server.reference, home-server.storage, home-server.authentication, home-server.backups, home-server.deployment] -update_triggers: [script-change, portainer-upgrade, state-migration, backup-plan-change] -unknowns: [local-hostname-dns-resolution, successful-state-and-secret-restore] + revision: working-tree + base_revision: 12fb1b96e01fc062fdce4c216f11eb5d7ce716ed + reference: "Image correction 2.45.1 -> 2.45.3 uncommitted at review" + paths: [stacks/portainer/portainer_start.sh] +related: [home-server.authentication, home-server.deployment, home-server.backups] +update_triggers: [script-change, portainer-upgrade, state-migration] +unknowns: [local-hostname-dns-resolution, host-script-and-boot-invocation, successful-state-restore] --- # Portainer ## Deployment -Managed by handwritten `~/portainer_start.sh`, **not a Compose stack**. -Reference script: [portainer_start.sh](https://github.com/jayo60013/jupiter-stacks). +- Standalone shell script, **not Compose**: `stacks/portainer/portainer_start.sh`; supplied host copy `~/portainer_start.sh`. +- Working tree pins **2.45.3**, matching live; committed `12fb1b9` still pins **2.45.1**. Correct before using a fresh clone. +- Script stops/removes then recreates the container. Host copy/boot invocation not revalidated. | Setting | Deployed value | | --- | --- | -| Image | `portainer/portainer-ce:2.45.1` | -| Container | `portainer` | -| Restart policy | `always` | -| Network | External Docker network `traefik` | -| State | Host `/data/portainer` -> container `/data` | -| Docker API | `/var/run/docker.sock` bind mount | -| Host publication | TCP `9123` -> container `9000` | -| HTTPS routers | `portainer.umbra.mom`, `portainer.local.umbra.mom` | -| Traefik backend | HTTP; container port `9000` | -| TLS | `https` entrypoint; `letsencrypt` resolver | +| Image / container | `portainer/portainer-ce:2.45.3` / `portainer` | +| Restart / network | `always` / external `traefik` | +| State | `/data/portainer:/data`; not old `portainer_data` volume | +| Docker API | `/var/run/docker.sock` bind | +| Direct port | `9123:9000`; bypasses Traefik middleware | +| Public router | `portainer.umbra.mom`; `https,wireguard`; no router TLS labels | +| Local router | `portainer.local.umbra.mom`; HTTPS-only, explicit TLS/`letsencrypt` | +| Backend | HTTP `9000`; no forward-auth middleware | -Script stops/removes the existing container, then recreates it; bind-mounted -state persists. Requires Docker, the `traefik` network, and mounted `/data`. -Supplied routers attach no forward-auth middleware. Local router does not -establish local DNS resolution. +- Replace from independent SSH, not Portainer's UI; require mounted `/data`, Docker and `traefik`. +- Back up state first; preserve image/mounts/network/restart/port. Never run two instances against the same state; a stopped container is not a DB backup. +- Shared routing convention: [Networking](networking.md#listener-and-trust-boundaries). -## Authentication +## Persisted state -Native OIDC through [Authentik](authentication.md); client ID `portainer`; -issuer `https://auth.umbra.mom/application/o/portainer/`. -Both public and local HTTPS hostnames are registered as strict callbacks. -The updated Authentik blueprint grants `jay` direct access, with other users -assigned manually per application instead of through the retired `development` -group. Deployment of this access-policy migration is unconfirmed. Admission -does not itself assign Portainer administrator permissions. - -OAuth configuration is database/UI state, not configured by the container -startup script. The owner reports the integration complete; local-login and -account-linking settings were not supplied. Preserve `/data/portainer` for -both stack management and authentication configuration. - -## Stack management - -Portainer fetches , branch `main`, -using a GitHub PAT. Stack environment values/secrets are managed in Portainer. -Repository changes are pulled/redeployed manually; committing alone does not -update containers. See [deployment](deployment.md). - -## Backups - -Daily 03:00 UTC; Google Drive; last four snapshots. Backrest reads -`/userdata/portainer` from host `/data/portainer`. - -- Before snapshot: stop `portainer`; timeout `120s`; errors fatal. -- Snapshot end/error: start `portainer`; restart errors ignored. -- Restore remains untested; script itself is outside the listed backup paths. - -The former `portainer_data` named volume is not used by the deployed container. +- `/data/portainer` holds stack management, environment secrets, Git credentials and database/UI OAuth settings. +- Native OIDC/callbacks and access policy: [Authentication](authentication.md#native-oidc). +- Git pull/redeploy workflow: [Deployment](deployment.md). +- Backup schedule, hooks and restore limits: [Backups](backups.md). diff --git a/docs/home-server/seedbox.md b/docs/home-server/seedbox.md index cbccd11..4c89d3d 100644 --- a/docs/home-server/seedbox.md +++ b/docs/home-server/seedbox.md @@ -2,136 +2,29 @@ schema_version: 1 id: home-server.seedbox type: reference -scope: [seedbox, ultra-cc, qbittorrent, rclone, sftp, media-import] +scope: [retired-seedbox, ultra-cc] sensitivity: private-infrastructure -last_reviewed: "2026-10-26" +last_reviewed: "2026-10-27" sources: - kind: owner-report - reference: "Ultra.cc subscription active from 2024-05-25 until retirement, always GBP 4.50/month with no price changes, 2026-10-26" - - kind: owner-report - reference: "Ultra.cc cancelled/expired, retained files handled, rclone-seedbox service and mount removed; local AirVPN downloads live, 2026-10-26" - - kind: owner-report - reference: "Ultra.cc plan, remaining capacity, rclone remote/process and enabled systemd unit, 2026-10-06" - - kind: owner-report - reference: "apt-managed rclone, active FUSE mount and Radarr/Sonarr bind-mount inspection, 2026-10-06" - - kind: owner-report - reference: "Import-then-delete intent, Remove Completed enabled, sample ratio about 0.01 and global seeding ratio limit 1, 2026-10-06" - - kind: documentation - reference: "https://wiki.servarr.com/radarr/settings#remove-completed-downloads" - - kind: documentation - reference: "https://wiki.servarr.com/sonarr/settings#remove-completed-downloads" - - kind: repository - repository: jupiter-stacks - revision: 610e325ef6a98850511ce7a089b0b9a77bfecf15 - paths: - - stacks/radarr/docker-compose.yml - - stacks/sonarr/docker-compose.yml -related: [home-server.reference, home-server.downloads, home-server.networking, home-server.storage, home-server.backups] -update_triggers: [hosting-renewal, quota-change, remote-change, mount-change, media-import-change] -unknowns: - - total-traffic-allowance-and-reset-period - - renewal-behaviour - - rclone-cache-location-and-size-limit - - import-copy-move-settings - - qbittorrent-seeding-limit-action-and-per-torrent-overrides - - download-client-categories-and-api-removal-outcome - - mount-startup-ordering-relative-to-docker-containers - - seedbox-backup-policy + reference: "Former connection snapshot 2026-10-06; cancellation, retained files handled and mount/service removed 2026-10-26" +related: [home-server.downloads] +update_triggers: [archive-correction] +unknowns: [] --- -# Seedbox (retired) +# Seedbox archive -**Retired by owner report on 2026-10-26:** Ultra.cc is cancelled/expired, -retained files have been handled, and Jupiter's `rclone-seedbox.service` and -`/mnt/seedbox` FUSE mount are removed. The replacement is -[local qBittorrent through AirVPN](downloads.md), now live with working -Sonarr/Radarr hardlink imports and seeding/removal. +- **Retired 2026-10-26:** Ultra.cc cancelled/expired; retained files handled; rclone unit/FUSE mount removed. +- Replacement, costs and current operations: [Local downloads / AirVPN](downloads.md). +- Historical reference only; **not a rollback or reconstruction target**. -The change reduces subscription cost and simplifies the architecture by removing -remote storage and the SFTP/FUSE import dependency. AirVPN cost GBP 56.06 for -three years, ending **Thursday, 25 October 2029**, versus Ultra.cc's former -GBP 4.50/month. - -The Ultra.cc subscription had been active since **2024-05-25**, always at -**GBP 4.50/month**, with no price changes before retirement. - -Everything below is a **historical 2026-10-06 snapshot**, retained for reference, -not current service state or a service to recreate. - -## Former service / subscription - -| Field | Configuration | +| Former component | Value | | --- | --- | -| Provider / plan | [Ultra.cc](https://ultra.cc/); `Lancer-v2` | -| Host | `terra.usbx.me` | -| Account / home | `jayo60013` / `/home/jayo60013` | -| Cost | GBP 4.50/month | -| Reported expiration | `2026-10-25`; renewal behaviour unconfirmed | -| Disk | 1001 GB allocation; 984 GB available at review | -| Remaining traffic | 2 TB at review; total allowance/reset period unconfirmed | -| Download speed | Provider reports `Unlimited`; no numeric rate supplied | -| Upload speed | Provider reports `50000 Mbps`; not measured throughput | -| qBittorrent UI | | +| Provider / plan / host | Ultra.cc `Lancer-v2`; `terra.usbx.me` | +| Remote | rclone `seedbox`, SFTP; `seedbox:downloads/qbittorrent` | +| Mount / consumers | `/mnt/seedbox` -> Arr `/downloads`; remote-to-local hardlinks impossible | +| Removed unit | `/etc/systemd/system/rclone-seedbox.service`; user/group `jay` | +| Former options | `--allow-other --dir-cache-time 1m --vfs-cache-mode writes`; restart on failure, 10s delay | -## Jupiter connection - -Actual connection: **SFTP via rclone/FUSE**, not WebDAV or scheduled sync. - -| Component | Path / value | -| --- | --- | -| rclone remote | `seedbox`; type `sftp`; host `terra.usbx.me`; user `jayo60013` | -| SSH key file | `/home/jay/.ssh/id_ed25519`; key contents excluded | -| Remote source | `seedbox:downloads/qbittorrent` | -| Remote absolute path | `/home/jayo60013/downloads/qbittorrent` | -| Jupiter mount | `/mnt/seedbox` | -| Container source | `/downloads` in Radarr and Sonarr | -| Radarr library | Container `/movies` -> host `/data/jellyfin/movies` | -| Sonarr library | Container `/tv` -> host `/data/jellyfin/tv_shows` | - -rclone remote: `shell_type=unix`; checksum commands `md5sum`, `sha1sum`. -rclone is apt-managed. Observed FUSE mount: UID/GID `1000:1000`; -`rw,nosuid,nodev,allow_other`. - -## Mount lifecycle - -`/etc/systemd/system/rclone-seedbox.service`; enabled at boot. -User/group `jay`; `Type=simple`; wants/starts after `network-online.target`. - -```sh -/usr/bin/rclone mount seedbox:downloads/qbittorrent /mnt/seedbox \ - --allow-other \ - --dir-cache-time 1m \ - --vfs-cache-mode writes -``` - -Stop: `/bin/fusermount -u /mnt/seedbox`. -Restart: `on-failure`; delay `10s`; target `multi-user.target`. - -`--allow-other` permits other local users, subject to filesystem permissions. -`writes` caches write/read-write opens; read-only opens stream from the remote. -No explicit cache path/size limit is supplied in the unit. - -The remote mount is not a complete local replica or backup. Radarr/Sonarr -library destinations are on the HDD array; cross-filesystem hardlinks are -impossible. Mount startup ordering relative to Docker containers is unconfirmed. -Their `/downloads` binds use `rprivate`; host remounts are not automatically -propagated into existing containers. - -The FUSE-reported capacity is not evidence of the account quota; use the -provider allocation above. - -## Import / removal - -Intent: Radarr/Sonarr import required media, then remove completed downloads. -Owner reports `Completed Download Handling / Remove Completed` enabled. -qBittorrent global seeding ratio limit: `1.0`. - -Reported undeleted example: share ratio approximately `0.01`; seeded less -than one minute. That ratio does not meet the configured global limit. -`Completed` download status alone does not establish completed seeding. - -Upstream requirements: successful import, supported seeding goal reached, -client reports seeding complete, paused/stopped torrent, expected category. -Removal is requested through qBittorrent's API, not by deleting through rclone. -Limit action, torrent overrides and removal after reaching the goal remain -unconfirmed; no configuration change or successful-removal evidence recorded. +- This retired unit is unrelated to Backrest's Google Drive/rclone dependency. diff --git a/docs/home-server/storage.md b/docs/home-server/storage.md index 2fa0c76..6b30588 100644 --- a/docs/home-server/storage.md +++ b/docs/home-server/storage.md @@ -2,174 +2,73 @@ schema_version: 1 id: home-server.storage type: reference -scope: [jupiter, downloads, disks, raid, filesystems, docker-volumes, media-import] +scope: [jupiter, disks, raid, filesystems, docker-volumes, media-import] sensitivity: private-infrastructure -last_reviewed: "2026-10-26" +last_reviewed: "2026-10-27" sources: - kind: owner-report - reference: "Local AirVPN downloads live; Sonarr/Radarr imports, hardlinks and seeding/removal confirmed; retained seedbox files handled and rclone service/mount removed; download-state backups not yet added, 2026-10-26" + reference: "lsblk/mdadm/fstab/findmnt/volume snapshots 2026-10-06; local hardlinks/imports and remote-mount removal confirmed 2026-10-26" - kind: repository repository: jupiter-stacks revision: working-tree base_revision: 631e4fdfa4c7122e5eff38e11b070c17ff7a4a2a - paths: - - stacks/downloads/docker-compose.yml - - stacks/sonarr/docker-compose.yml - - stacks/radarr/docker-compose.yml - - kind: owner-report - reference: "lsblk filesystem output, RAID level, mount placement and Docker data root, 2026-10-06" - - kind: owner-report - reference: "Ultra.cc plan/capacity, seedbox rclone mount/systemd unit and Radarr/Sonarr bind-mount inspection, 2026-10-06" - - kind: owner-report - reference: "Deployed Portainer uses /data/portainer bind mount, not portainer_data, 2026-10-06" - - kind: owner-report - reference: "mdstat, mdadm scans/detail, fstab, findmnt and Docker volume/container inspection, 2026-10-06" - - kind: owner-report - reference: "Authentik deployed, Authelia retired; six-directory backup plan includes Authentik and Wardrowbe, 2026-10-16" - - kind: repository - repository: jupiter-stacks - revision: d09df456ad331b8beb9a40615114ea8aae2dced5 - paths: - - stacks/backrest/docker-compose.yml - - stacks/jellyfin/docker-compose.yml - - stacks/authentik/docker-compose.yml - - stacks/wardrowbe/docker-compose.yml - - stacks/traefik/docker-compose.yml -related: [home-server.reference, home-server.host, home-server.downloads, home-server.seedbox, home-server.portainer, home-server.backups, home-server.operations] -update_triggers: [disk-change, raid-change, mount-change, volume-change, backup-coverage-change, seedbox-change] -unknowns: [persistent-mdadm-config-and-initramfs-content, disk-health] + paths: [stacks/downloads/docker-compose.yml, stacks/sonarr/docker-compose.yml, stacks/radarr/docker-compose.yml] +related: [home-server.host, home-server.downloads, home-server.backups] +update_triggers: [disk-change, raid-change, mount-change, volume-change] +unknowns: [persistent-mdadm-config-and-initramfs, disk-health] --- # Storage -[AirVPN/local downloads](downloads.md) are live by owner report on 2026-10-26. -Downloads and libraries now share local storage, with Sonarr/Radarr hardlink -imports and seeding/removal confirmed. Existing host library paths are unchanged. -The Ultra.cc service and rclone/FUSE mount are retired, simplifying imports. +## Physical placement ```mermaid --- config: themeCSS: | - .node rect { rx: 8px; ry: 8px; stroke-width: 1.5px; } - .cluster rect { fill: var(--infra-zone) !important; stroke: var(--infra-border) !important; stroke-dasharray: 5 5; rx: 12px; ry: 12px; } - .label, .nodeLabel, .cluster-label { color: var(--infra-text) !important; } - .edgeLabel, .edgeLabel p { background-color: var(--infra-zone) !important; color: var(--infra-text) !important; } - .flowchart-link { stroke: var(--infra-line) !important; } - marker path { fill: var(--infra-line) !important; stroke: var(--infra-line) !important; } - .infraStorage rect, .infraStorage path { fill: var(--infra-storage-fill) !important; stroke: var(--infra-storage-stroke) !important; } - .infraCloud rect { fill: var(--infra-cloud-fill) !important; stroke: var(--infra-cloud-stroke) !important; } - .infraClient rect { fill: var(--infra-client-fill) !important; stroke: var(--infra-client-stroke) !important; } - .infraService rect { fill: var(--infra-service-fill) !important; stroke: var(--infra-service-stroke) !important; } - flowchart: - curve: basis - nodeSpacing: 30 - rankSpacing: 45 + text,.nodeLabel,.cluster-label { fill:var(--infra-text);color:var(--infra-text); } + .flowchart-link { stroke:var(--infra-line); } + marker path { fill:var(--infra-line);stroke:var(--infra-line); } + .cluster rect { fill:var(--infra-zone);stroke:var(--infra-border);stroke-dasharray:5 5;rx:12px;ry:12px; } + .cluster span,.cluster text { color:var(--infra-text)!important;fill:var(--infra-text)!important; } + .infraStorage rect,.infraStorage path { fill:var(--infra-storage-fill);stroke:var(--infra-storage-stroke); } + .infraEdge rect { fill:var(--infra-edge-fill);stroke:var(--infra-edge-stroke);rx:8px;ry:8px; } + .infraService rect { fill:var(--infra-service-fill);stroke:var(--infra-service-stroke);rx:8px;ry:8px; } --- -flowchart LR - subgraph Import["JUPITER / LOCAL MEDIA IMPORT"] - QBIT["qBittorrent
Gluetun / AirVPN"] - TORRENTS[("/data/jellyfin/torrents
incomplete / movies / tv")] - ARR["Radarr / Sonarr
/data/jellyfin mounted at /media"] - LIBRARY[("/data/jellyfin
movies / tv_shows libraries")] - QBIT -->|"Writes /media/torrents"| TORRENTS - TORRENTS -->|"Local download source"| ARR - ARR -->|"Hardlink imports / same filesystem"| LIBRARY +flowchart TB + accTitle: SSD system storage and non-redundant HDD application storage + accDescr: Docker volumes and caches are on SSD; service bind mounts, downloads and libraries are on the striped HDD array. + subgraph SSD["SSD / SAMSUNG 860 EVO / 1 TB"] + Root["sdc3 / ext4 root"]:::infraStorage + Docker["/var/lib/docker
/var/lib/containerd"]:::infraService + Cache["/home/jay/data
service caches"]:::infraService + Root --> Docker + Root --> Cache end - - subgraph Array["HDD ARRAY / APPLICATION DATA"] - direction TB - A["Seagate BarraCuda
sda1 / 2 TB"] - B["Seagate BarraCuda
sdb1 / 2 TB"] - RAID["Linux MD RAID 0
md0 / no redundancy"] - DATA[("/data
ext4")] - A --> RAID - B --> RAID - RAID --> DATA + subgraph HDD["HDD / 2 x SEAGATE BARRACUDA / 2 TB EACH"] + Disks["sdb1 + sda1"]:::infraStorage + RAID["md0 / RAID 0
3.64 TiB / no redundancy"]:::infraEdge + Data[("/data / ext4
bind mounts + media")]:::infraStorage + Disks --> RAID --> Data end - - subgraph System["SSD / SYSTEM"] - direction TB - SSD["Samsung 860 EVO
sdc / 1 TB"] - EFI["/boot/efi
sdc1 / FAT32"] - SWAP["Swap
sdc2"] - ROOT["/
sdc3 / ext4"] - DOCKER["/var/lib/docker
Named volumes"] - CACHE["/home/jay/data
Backrest / Jellyfin caches"] - SSD --> EFI - SSD --> SWAP - SSD --> ROOT - ROOT --> DOCKER - ROOT --> CACHE - end - - DATA -->|"Backs torrent storage"| TORRENTS - DATA -->|"Backs organised libraries"| LIBRARY - - class A,B,SSD,DATA,ROOT,TORRENTS,LIBRARY infraStorage - class RAID infraCloud - class EFI,SWAP infraClient - class DOCKER,CACHE,QBIT,ARR infraService ``` -RAID 0: striping; no redundancy; either HDD failure loses the array. +- Either HDD failure loses the array, including application state; [backup coverage](backups.md#coverage) is explicit, not all of `/data`. +- SSD cache paths: `/home/jay/data/{backrest/cache,jellyfin/cache,wardrowbe/ollama,wardrowbe/rembg}`. +- `/data/` holds service bind mounts; application-specific mappings live on each service page. +- Wardrowbe binds: `/data/wardrowbe/{postgres,uploads,redis}`; SSD models/caches above. -## Local downloads / imports +## RAID / mounts -The current path is entirely on Jupiter's HDD array: - -```text -qBittorrent -> /data/jellyfin/torrents/{incomplete,movies,tv} - -> Sonarr/Radarr via /data/jellyfin:/media - -> hardlinks in /data/jellyfin/{movies,tv_shows} -``` - -Sonarr's library root is `/media/tv_shows`; Radarr's is `/media/movies`. -qBittorrent receives only the torrents subtree at `/media/torrents`, not the -organised libraries. Jellyfin retains `/data/jellyfin:/media`; its library roots -must exclude the torrent folders. - -Hardlinks let imported files remain available while torrents seed without a -second full data copy. Removing one name does not remove the data while another -link remains; hardlinks are not independent copies or backups. The old remote -mount could not support cross-filesystem hardlinks to the local libraries. - -The six-directory Backrest plan does not cover media, torrent data, qBittorrent -state/defaults or VPN secrets. The owner confirms the latter recovery gap -remains. Historical remote storage details are on [Seedbox (retired)](seedbox.md); -retained files are handled and its mount/service are removed. - -## Filesystems - -Device names reflect the supplied snapshot; UUIDs identify filesystems. - -| Mount | Device | Filesystem | UUID | -| --- | --- | --- | --- | -| `/data` | `/dev/md0` | ext4 | `d60390a1-7db3-44cc-bbde-693c23e42001` | -| `/` | `/dev/sdc3` | ext4 | `7a5e0ee6-4a65-4f68-9128-b3b4f3406447` | -| `/boot/efi` | `/dev/sdc1` | FAT32 | `1DDE-CDF9` | -| swap | `/dev/sdc2` | swap | `4781ea5d-fba5-438d-8d97-6a0801669ca1` | - -MD members: `/dev/sda1`, `/dev/sdb1`; metadata `1.2`; array label `jupiter:0`; -MD UUID `c67fccaa-e541-bf2d-2bf6-83221086e0e9`. - -## RAID assembly / geometry - -Linux MD, inspected with mdadm; ext4 directly on the array, no intervening LVM. - -| Setting | Observed value | +| Setting | Snapshot value | | --- | --- | -| Device / scan name | `/dev/md0` / `/dev/md/0` | -| mdadm UUID | `c67fccaa:e541bf2d:2bf68322:1086e0e9` | -| Capacity | 3.64 TiB / 4.00 TB | -| Layout / chunk | `original` / 512 KiB | -| Member order | Slot 0: `/dev/sdb1`; slot 1: `/dev/sda1` | -| State at review | `clean`; 2 active members; no failed/spare devices | - -Scan output identifies the array; persisted mdadm configuration/initramfs were -not supplied. Assembly is not array creation; do not substitute `mdadm --create`. - -## Mount configuration +| Array | Linux MD `/dev/md0` (`/dev/md/0` scan name); ext4 directly, no LVM | +| MD UUID / label | `c67fccaa:e541bf2d:2bf68322:1086e0e9` / `jupiter:0` | +| Metadata / layout / chunk | `1.2` / `original` / 512 KiB | +| Member order | Slot 0 `/dev/sdb1`; slot 1 `/dev/sda1` | +| State | Clean, 2 active, no failed/spare members at inspection | +| `/data` options | `rw,relatime,stripe=256`; `/tmp` is tmpfs | +| SSD partitions | `sdc1` EFI; `sdc2` swap; `sdc3` root | Supplied `/etc/fstab`: @@ -180,50 +79,33 @@ UUID=d60390a1-7db3-44cc-bbde-693c23e42001 /data ext4 defaults 0 2 UUID=4781ea5d-fba5-438d-8d97-6a0801669ca1 none swap sw 0 0 ``` -Observed `/data`: `rw,relatime,stripe=256`; `/tmp`: tmpfs. -The former seedbox FUSE mount was service-managed, not listed in fstab; it has -now been removed. +- Device names are snapshots; UUIDs identify filesystems. +- Persisted mdadm/initramfs configuration unverified. **Assembly is not creation: do not use `mdadm --create`.** -## Placement +## Media mounts -| Host path | Backing / purpose | -| --- | --- | -| `/data/` | HDD array; service bind mounts | -| `/data/jellyfin/torrents/{incomplete,movies,tv}` | HDD array; local qBittorrent downloads | -| `/data/jellyfin/{movies,tv_shows}` | HDD array; organised media libraries; hardlink imports | -| `/data/qbittorrent/{config,defaults}` | HDD array; client state and startup defaults/scripts; not backed up | -| `/data/gluetun/secrets` | HDD array; root-restricted AirVPN WireGuard secrets; not backed up | -| `/home/jay/data/backrest/cache` | SSD; Backrest cache | -| `/home/jay/data/jellyfin/cache` | SSD; Jellyfin cache | -| `/var/lib/docker` | SSD; Docker state and default local named volumes | -| `/var/lib/containerd` | SSD; observed containerd overlayfs snapshot storage | -| `/data/portainer` | HDD array; deployed [Portainer](portainer.md) state; backed up | -| `/data/authentik/{postgres,data,blueprints}` | Authentik PostgreSQL, persistent files and custom blueprint; backed up | -| `/data/wardrowbe/{postgres,uploads}` | Wardrowbe database and uploads; backed up | -| `/data/wardrowbe/redis` | Wardrowbe Redis; excluded from backups | -| `/home/jay/data/wardrowbe/{ollama,rembg}` | SSD; Wardrowbe models/caches; outside backup plan | -| `/data/traefik/{acme,dynamic,certs}` | ACME state, dynamic configuration, certificates | +| Consumer | Host -> container | Paths | +| --- | --- | --- | +| qBittorrent | `/data/jellyfin/torrents:/media/torrents` | `incomplete`, `movies`, `tv`; no organised-library mount | +| Sonarr / Radarr | `/data/jellyfin:/media` | Roots `/media/tv_shows`, `/media/movies`; categories `sonarr` -> torrents `tv`, `radarr` -> torrents `movies` | +| Jellyfin | `/data/jellyfin:/media` | Library roots exclude `torrents` | -Cache placement is per mount, not globally SSD-backed. `/data` backups do not -implicitly include SSD-backed Docker volumes. -Authelia is retired; retention/deletion of its former `/data/authelia` directory -is unconfirmed. Authentik uses PostgreSQL, not the former Authelia SQLite store. +- Same-filesystem hardlink imports confirmed; no second full copy while seeding. +- Unlinking one name preserves data while another link exists; hardlinks are **not backups**. +- Download service/configuration: [AirVPN](downloads.md). Former FUSE mount is retired. -## Named-volume snapshot +## Named volumes -Inspected volumes below use driver `local`, no driver options, and -`/var/lib/docker/volumes//_data` on SSD. +Snapshot: driver `local`, no options; `/var/lib/docker/volumes//_data` on SSD. -| Volume | Running consumer / container path | +| Volume | Consumer path | | --- | --- | | `audiobookshelf_config` | Audiobookshelf `/config` | | `jellyfin_config` | Jellyfin `/config` | -| `notes_static` | Notes web `/usr/share/nginx/html`; builder `/site-output` | +| `notes_static` | Builder `/site-output`; web `/usr/share/nginx/html` | | `dozzle_dozzle_data` | Dozzle `/data` | | `ctq_ctq_postgres_data` | CTQ PostgreSQL `/var/lib/postgresql/data` | | `havox_src` | Havox web/sync `/git` | -Other volumes are present without a running consumer shown, including -`jellyfin_cache`, `notes_notes_static`, and monitoring volumes. Presence does -not prove use or justify deletion. Named volumes are outside the supplied -six-directory backup plan. +- `jellyfin_cache`, `notes_notes_static` and monitoring volumes had no shown running consumer; **not evidence they are safe to delete**. +- Named-volume recovery is separate from `/data` bind mounts: [Backups](backups.md#recovery-limits). diff --git a/zensical.toml b/zensical.toml index 16aa166..d0f1d68 100644 --- a/zensical.toml +++ b/zensical.toml @@ -24,7 +24,6 @@ nav = [ { "Storage" = "home-server/storage.md" }, { "Authentication" = "home-server/authentication.md" }, { "Backups" = "home-server/backups.md" }, - { "Ideas / next steps" = "home-server/ideas-next-steps.md" }, ] }, { "Books" = [ { "Designing Data-Intensive Applications" = [