tidy up notes
This commit is contained in:
15 files changed
+669
-2078
No files matched your search
@@ -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/<client-id>/`.
|
||||
- Confidential authorization-code clients; strict callbacks; shared MFA flow.
|
||||
- Issuer: `https://auth.umbra.mom/application/o/<client-id>/`.
|
||||
|
||||
| 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).
|
||||
+42
-118
@@ -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.
|
||||
+57
-116
@@ -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 | <https://github.com/jayo60013/jupiter-stacks> |
|
||||
| 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<br/>jupiter-stacks"]:::infraClient
|
||||
Portainer["Portainer<br/>manual pull / redeploy"]:::infraEdge
|
||||
Runtime["Running containers<br/>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: <https://github.com/jayo60013/jupiter-stacks>, 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.
|
||||
+73
-152
@@ -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<br/>torrent interface wg0"]:::infraService
|
||||
VPN["Gluetun<br/>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.
|
||||
+38
-79
@@ -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.
|
||||
@@ -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.
|
||||
+27
-49
@@ -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.
|
||||
+51
-230
@@ -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/<domain>/{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/<domain>/{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.
|
||||
+104
-248
@@ -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["<b>Public clients</b>"]
|
||||
|
||||
subgraph VPS["MERCURY / PUBLIC EDGE"]
|
||||
Nginx["<b>nginx</b><br/>185.230.217.66<br/>WireGuard 10.0.0.1"]
|
||||
Uptime["<b>Uptime service</b><br/>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<br/>185.230.217.66<br/>WG 10.0.0.1"]:::infraEdge
|
||||
Kuma["Uptime Kuma<br/>127.0.0.1:3001"]:::infraService
|
||||
end
|
||||
|
||||
subgraph Home["JUPITER / HOME SERVER"]
|
||||
LAN["<b>LAN clients</b><br/>Jellyfin / Bookshelf local DNS"]
|
||||
Traefik["<b>Traefik</b><br/>192.168.1.56<br/>WireGuard 10.0.0.2"]
|
||||
Apps["<b>Application containers</b><br/>Docker network: traefik"]
|
||||
Arr["<b>Radarr / Sonarr</b><br/>Download control / media imports"]
|
||||
Qbit["<b>qBittorrent</b><br/>Shared Gluetun namespace"]
|
||||
Gluetun["<b>Gluetun</b><br/>WireGuard / firewall<br/>downloads Docker network"]
|
||||
Downloads["<b>Local torrents / libraries</b><br/>/data/jellyfin<br/>Hardlink imports"]
|
||||
Router["<b>Home router / ISP</b><br/>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<br/>LAN 192.168.1.56<br/>WG 10.0.0.2"]:::infraEdge
|
||||
Apps["Application containers"]:::infraService
|
||||
end
|
||||
|
||||
AirVPN["<b>AirVPN</b><br/>Public VPN exit / reserved peer port"]
|
||||
Peers["<b>Torrent peers</b>"]
|
||||
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["<b>SSH client</b><br/>Host jupiter / user jay"]
|
||||
Git["<b>Git over SSH</b><br/>Host git.umbra.mom / user git"]
|
||||
Cloud["<b>Cloudflare Tunnel edge</b><br/>Access policy unconfirmed"]
|
||||
|
||||
subgraph Home["JUPITER / HOME SERVER"]
|
||||
Connector["<b>cloudflared</b><br/>Locally configured ingress"]
|
||||
SSH["<b>Host sshd</b><br/>192.168.1.56:22"]
|
||||
Gitea["<b>Gitea SSH</b><br/>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<br/>cloudflared access ssh"]:::infraClient
|
||||
Edge["Cloudflare edge"]:::infraCloud
|
||||
Tunnel["Jupiter cloudflared<br/>outbound connector"]:::infraEdge
|
||||
Host["Host sshd<br/>192.168.1.56:22"]:::infraService
|
||||
Git["Gitea SSH<br/>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.
|
||||
+55
-84
@@ -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<br/>main"]:::infraClient
|
||||
Builder["notes_builder :9000<br/>HMAC check / queue / build"]:::infraEdge
|
||||
Static[("notes_static<br/>generated site")]:::infraStorage
|
||||
Web["notes_web :8080<br/>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.
|
||||
+52
-188
@@ -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. |
|
||||
@@ -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 <https://github.com/jayo60013/jupiter-stacks>, 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).
|
||||
+17
-124
@@ -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 | <https://jayo60013.terra.usbx.me/qbittorrent/> |
|
||||
| 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.
|
||||
+60
-178
@@ -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["<b>qBittorrent</b><br/>Gluetun / AirVPN"]
|
||||
TORRENTS[("<b>/data/jellyfin/torrents</b><br/>incomplete / movies / tv")]
|
||||
ARR["<b>Radarr / Sonarr</b><br/>/data/jellyfin mounted at /media"]
|
||||
LIBRARY[("<b>/data/jellyfin</b><br/>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<br/>/var/lib/containerd"]:::infraService
|
||||
Cache["/home/jay/data<br/>service caches"]:::infraService
|
||||
Root --> Docker
|
||||
Root --> Cache
|
||||
end
|
||||
|
||||
subgraph Array["HDD ARRAY / APPLICATION DATA"]
|
||||
direction TB
|
||||
A["<b>Seagate BarraCuda</b><br/>sda1 / 2 TB"]
|
||||
B["<b>Seagate BarraCuda</b><br/>sdb1 / 2 TB"]
|
||||
RAID["<b>Linux MD RAID 0</b><br/>md0 / no redundancy"]
|
||||
DATA[("<b>/data</b><br/>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<br/>3.64 TiB / no redundancy"]:::infraEdge
|
||||
Data[("/data / ext4<br/>bind mounts + media")]:::infraStorage
|
||||
Disks --> RAID --> Data
|
||||
end
|
||||
|
||||
subgraph System["SSD / SYSTEM"]
|
||||
direction TB
|
||||
SSD["<b>Samsung 860 EVO</b><br/>sdc / 1 TB"]
|
||||
EFI["<b>/boot/efi</b><br/>sdc1 / FAT32"]
|
||||
SWAP["<b>Swap</b><br/>sdc2"]
|
||||
ROOT["<b>/</b><br/>sdc3 / ext4"]
|
||||
DOCKER["<b>/var/lib/docker</b><br/>Named volumes"]
|
||||
CACHE["<b>/home/jay/data</b><br/>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/<service>` 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/<service>` | 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/<name>/_data` on SSD.
|
||||
Snapshot: driver `local`, no options; `/var/lib/docker/volumes/<name>/_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).
|
||||
Reference in new issue
Block a user