From 97f6dc28ae5fcd6e416c52057a3f7cabceb88d59 Mon Sep 17 00:00:00 2001 From: John Gatward Date: Fri, 16 Oct 2026 13:05:11 +0100 Subject: [PATCH] [main]: document authentik --- docs/home-server/authentication.md | 169 ++++++++++++++++++++++------- docs/home-server/backups.md | 48 ++++++-- docs/home-server/deployment.md | 41 ++++++- docs/home-server/index.md | 6 +- docs/home-server/networking.md | 76 ++++++++++++- docs/home-server/operations.md | 26 ++++- docs/home-server/portainer.md | 25 ++++- docs/home-server/storage.md | 67 ++++++++++-- 8 files changed, 382 insertions(+), 76 deletions(-) diff --git a/docs/home-server/authentication.md b/docs/home-server/authentication.md index 3882e67..5e3b2e6 100644 --- a/docs/home-server/authentication.md +++ b/docs/home-server/authentication.md @@ -2,80 +2,173 @@ schema_version: 1 id: home-server.authentication type: reference -scope: [jupiter, authelia, forward-auth, secrets] +scope: [jupiter, authentik, oidc, forward-auth, access-groups, secrets] sensitivity: private-infrastructure -last_reviewed: "2026-10-06" +last_reviewed: "2026-10-16" sources: - kind: owner-report - reference: "Deployed Authelia file matches repository; Portainer supplies environment variables, 2026-10-06" + reference: "Authentik fully deployed, all listed app integrations complete and Authelia retired; OIDC and three-group motivation, 2026-10-16" - kind: owner-report - reference: "Portainer state added to Backrest plan, 2026-10-06" + 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: "No independent credential recovery except restic key, 2026-10-06" + reference: "Independent credential recovery unchanged: only restic key has independent custody, 2026-10-16" - kind: repository repository: jupiter-stacks - revision: 610e325ef6a98850511ce7a089b0b9a77bfecf15 + revision: d09df456ad331b8beb9a40615114ea8aae2dced5 paths: - - stacks/authelia/configuration.yml - - stacks/authelia/docker-compose.yml + - 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: - - authelia-file-placeholder-expansion-mechanism + - deployed-group-memberships + - per-application-local-login-and-account-linking-settings + - retired-authelia-data-retention --- # Authentication +Authentik replaces Authelia. The owner wanted native OIDC rather than only +forward-auth, with three access groups separating server administration, +development tools and client-facing services. The owner reports the migration +fully deployed, all integrations below complete and Authelia retired. +Configuration details below are repository evidence, not live inspection. + | Component | Configuration | | --- | --- | | Portal | `https://auth.umbra.mom` | -| Backend | File `/config/users_database.yml`; Argon2id | -| Second factor | TOTP; issuer `Jupiter` | -| Policy | Default deny; listed domains require `two_factor` | -| Session cookie domain | `umbra.mom` | -| Default redirect | `https://sonarr.umbra.mom` | -| Storage | SQLite `/data/db.sqlite3`; storage encryption key | -| Notifications | Filesystem `/data/notification.txt` | +| 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` | -Two-factor domains: `sonarr`, `radarr`, `prowlarr`, `logs`, `notes`, `backups` -under `umbra.mom`. +## Access groups -## Enforcement +Owner terminology maps to the blueprint's exact group names: -Protected routers attach `authelia@docker`: +| Intended group | Authentik group | Purpose / applications | +| --- | --- | --- | +| Admin | `admins` | Owner only; server health/operations: Backrest, Beszel, Dozzle, Notes, Prowlarr, Radarr, Sonarr | +| Developers | `development` | Development services: Gitea, Portainer | +| Clients | `clients` | Useful end-user services: Immich, Paperless, Wardrowbe | + +Each application has an enabled group binding; `policy_engine_mode: all`; +binding failure result is false. All three groups have `is_superuser: false`: +`admins` application access is not Authentik superuser status. +No group hierarchy or membership assignment is declared by this blueprint. +Membership in `admins` alone does not grant the development/client applications; +users needing multiple categories need the corresponding memberships. +Actual deployed membership assignments were not supplied. + +## 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 | Application hostname | Integration 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 | +| `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 | +| `wardrowbe` | `wardrobe.umbra.mom` | Compose OIDC settings for frontend and backend/workers | + +Dozzle's custom profile mapping emits `dozzle_roles: ["none"]` for `admins` +members and `[]` otherwise; application access is separately restricted to +`admins`. 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. + +## Forward-auth + +Backrest (`backups.umbra.mom`), Notes, Prowlarr, Radarr and Sonarr retain +proxy-based protection. Their routers attach `authentik@docker`: ```text -Traefik -> http://authelia:9091/api/authz/forward-auth +Traefik -> http://authentik-server:9000/outpost.goauthentik.io/auth/traefik ``` -`trustForwardHeader=true`; response headers: -`Remote-User, Remote-Groups, Remote-Email, Remote-Name`. +The embedded outpost serves five `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. -Policy applies only to requests routed through forward-auth. It is not a -global gate for every service or directly published port. +`trustForwardHeader=true`; forwarded response headers: -## Configuration / secrets +```text +X-authentik-username, X-authentik-groups, X-authentik-entitlements, +X-authentik-email, X-authentik-name, X-authentik-uid, X-authentik-jwt, +X-authentik-meta-jwks, X-authentik-meta-outpost, X-authentik-meta-provider, +X-authentik-meta-app, X-authentik-meta-version +``` -Host `/data/authelia/{configuration.yml,users_database.yml}` mounts read-only -under `/config`; `/data/authelia` also mounts read-write at `/data`. +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 | Stack variable overrides/secrets are managed in Portainer; Compose retains -non-secret configuration. Authelia environment: +non-secret configuration. Required Authentik stack secrets: ```text -AUTHELIA_SESSION_SECRET -AUTHELIA_STORAGE_ENCRYPTION_KEY -AUTHELIA_IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET +AUTHENTIK_SECRET_KEY +AUTHENTIK_DB_PASSWORD +OIDC_BESZEL_SECRET +OIDC_DOZZLE_SECRET +OIDC_GITEA_SECRET +OIDC_IMMICH_SECRET +OIDC_PAPERLESS_SECRET +OIDC_PORTAINER_SECRET +OIDC_WARDROWBE_SECRET ``` -Checked-in YAML also contains `${AUTHELIA_*}` placeholders. Container environment -injection alone does not prove mounted-file substitution; expansion mechanism -unconfirmed. +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: +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. -Authelia data remains outside the supplied backup plan. -[Portainer state](portainer.md) is covered; secret recovery remains untested. -No independent recovery arrangement exists for stack secrets. +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. diff --git a/docs/home-server/backups.md b/docs/home-server/backups.md index 0a05a87..1a228b7 100644 --- a/docs/home-server/backups.md +++ b/docs/home-server/backups.md @@ -4,7 +4,7 @@ id: home-server.backups type: reference scope: [jupiter, backrest, restic, google-drive, recovery] sensitivity: private-infrastructure -last_reviewed: "2026-10-06" +last_reviewed: "2026-10-16" sources: - kind: owner-report reference: "Backrest plan JSON, destination, key custody and no restore test, 2026-10-06" @@ -12,14 +12,18 @@ sources: 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: repository repository: jupiter-stacks - revision: 610e325ef6a98850511ce7a089b0b9a77bfecf15 + 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.storage, home-server.portainer, home-server.authentication, home-server.operations] update_triggers: [backup-plan-change, destination-change, hook-change, credential-change, restore-test] unknowns: @@ -47,19 +51,24 @@ 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 exclusion: `/userdata/gitea/gitea/packages`. +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. ## Consistency hooks Stop timeout `120s`; chains use `&&`. Errors: `ON_ERROR_FATAL`, -except Portainer restart (`ON_ERROR_IGNORE`). +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. | Event | Ordered commands / containers | | --- | --- | @@ -71,11 +80,29 @@ except Portainer restart (`ON_ERROR_IGNORE`). | `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 | Cold filesystem copies of applications/databases; no database dumps supplied. -Broker stays running. `docker start` does not wait for database readiness. -Hook failure can leave services stopped; recovery is not demonstrated. -Portainer restart failure does not fail the backup operation. +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. ## Backrest state @@ -90,8 +117,11 @@ Portainer restart failure does not fail the backup operation. ## Recovery limits -Only the four listed directories are covered. No supplied coverage for Authelia, -Traefik, Backrest configuration, Docker named volumes, OS, or Mercury. +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. diff --git a/docs/home-server/deployment.md b/docs/home-server/deployment.md index 3cc558e..e6362b6 100644 --- a/docs/home-server/deployment.md +++ b/docs/home-server/deployment.md @@ -4,12 +4,25 @@ id: home-server.deployment type: reference scope: [jupiter, portainer, github, stack-deployment, secrets] sensitivity: private-infrastructure -last_reviewed: "2026-10-06" +last_reviewed: "2026-10-16" sources: - 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] update_triggers: [deployment-workflow-change, repository-change, credential-rotation, rollback-policy-change] unknowns: @@ -44,5 +57,31 @@ 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. +## 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, seven 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, Paperless and Wardrowbe OIDC settings; five proxy-protected routers use `authentik@docker` | + +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. diff --git a/docs/home-server/index.md b/docs/home-server/index.md index 7e9daf6..d8de79b 100644 --- a/docs/home-server/index.md +++ b/docs/home-server/index.md @@ -4,10 +4,12 @@ id: home-server.reference type: reference scope: [jupiter, mercury, seedbox, shared-infrastructure] sensitivity: private-infrastructure -last_reviewed: "2026-10-06" +last_reviewed: "2026-10-16" sources: - 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 @@ -35,7 +37,7 @@ unknowns: [] | [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) | Authelia; policy; secrets | +| [Authentication](authentication.md) | Authentik; OIDC; access groups; forward-auth; secrets | | [Backups](backups.md) | Backrest; coverage; retention; recovery | ## Evidence / agent contract diff --git a/docs/home-server/networking.md b/docs/home-server/networking.md index 9140e05..7428385 100644 --- a/docs/home-server/networking.md +++ b/docs/home-server/networking.md @@ -2,9 +2,9 @@ schema_version: 1 id: home-server.networking type: reference -scope: [jupiter, mercury, dns, ingress, wireguard, cloudflare] +scope: [jupiter, mercury, seedbox, dns, ingress, wireguard, cloudflare, sftp] sensitivity: private-infrastructure -last_reviewed: "2026-10-06" +last_reviewed: "2026-10-16" sources: - kind: owner-report reference: "Network topology, Mercury nginx/iptables/fail2ban output, LAN DNS, 2026-10-06" @@ -12,6 +12,10 @@ sources: 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 @@ -21,19 +25,26 @@ sources: - 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.seedbox, home-server.authentication, home-server.operations] -update_triggers: [dns-change, proxy-change, tunnel-change, firewall-change, certificate-change] +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 + - seedbox-sftp-port-and-download-client-api-endpoint --- # Networking -## HTTPS ingress +## HTTPS ingress / seedbox connectivity ```mermaid --- @@ -66,16 +77,28 @@ flowchart TB LAN["LAN clients
Jellyfin / Bookshelf local DNS"] Traefik["Traefik
192.168.1.56
WireGuard 10.0.0.2"] Apps["Application containers
Docker network: traefik"] + Arr["Radarr / Sonarr
Download control / media imports"] + Rclone["Host rclone / FUSE
/mnt/seedbox"] LAN -->|"HTTPS :443"| Traefik Traefik -->|"Application routing"| Apps + Traefik -->|"Media management UIs"| Arr + Arr -->|"/downloads bind / host /mnt/seedbox"| Rclone + end + + subgraph Seed["ULTRA.CC / SEEDBOX"] + Qbit["qBittorrent
jayo60013.terra.usbx.me"] + Downloads["Remote download storage
terra.usbx.me
downloads/qbittorrent"] + Qbit -->|"Writes downloads"| Downloads end Internet -->|"HTTPS :443"| Nginx Nginx -->|"HTTPS :443 over WireGuard"| Traefik + Arr -->|"qBittorrent API / endpoint unconfirmed"| Qbit + Rclone -->|"Outbound SFTP / remote file access"| Downloads class Internet,LAN infraClient class Nginx,Traefik infraEdge - class Apps,Uptime infraService + class Apps,Uptime,Arr,Rclone,Qbit,Downloads infraService ``` ## Cloudflare Tunnel @@ -162,6 +185,28 @@ Ingress source: host `/data/cloudflared/config.yaml`, mounted at | `bookshelf.local.umbra.mom` | Jupiter `192.168.1.56` | | `ssh.umbra.mom`, `git.umbra.mom` | Cloudflare Tunnel | | `uptime.umbra.mom` | Mercury nginx -> `http://127.0.0.1:3001` | +| `terra.usbx.me` | Ultra.cc seedbox; rclone SFTP remote | +| `jayo60013.terra.usbx.me` | Provider-hosted qBittorrent UI under `/qbittorrent/` | + +## Seedbox connection + +The [Ultra.cc seedbox](seedbox.md) runs qBittorrent on `terra.usbx.me`, separate +from Jupiter and Mercury. Its provider-hosted UI is +. + +Jupiter's host-level `rclone-seedbox.service` initiates an outbound SFTP +connection to `terra.usbx.me`, user `jayo60013`, using +`/home/jay/.ssh/id_ed25519`. Remote `seedbox:downloads/qbittorrent` is exposed +through FUSE at `/mnt/seedbox`, then bind-mounted at `/downloads` in Radarr +and Sonarr. File reads use this mount; download control/removal uses qBittorrent's +API, not deletion through rclone. The exact configured download-client API +endpoint and SFTP port were not supplied; do not infer them from the UI URL. + +This is not a WebDAV mount, scheduled sync, or Mercury/WireGuard/Cloudflare +Tunnel ingress route. No home-router port forwarding is required for Jupiter's +outbound SFTP connection. Remote availability and the host mount are dependencies +for media imports; startup ordering relative to Docker remains unconfirmed. +See [Storage](storage.md) for remote versus local media placement. ## Mercury @@ -201,3 +246,24 @@ whether they are obsolete or safe to remove. - 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. +Seven applications use native OIDC; Backrest, Notes, Prowlarr, Radarr and Sonarr +use Traefik middleware `authentik@docker` and the embedded outpost. +Dozzle (`logs.umbra.mom`) now uses OIDC, not forward-auth. + +On the five 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. diff --git a/docs/home-server/operations.md b/docs/home-server/operations.md index e80030e..3132961 100644 --- a/docs/home-server/operations.md +++ b/docs/home-server/operations.md @@ -4,17 +4,19 @@ id: home-server.operations type: reference scope: [jupiter, mercury, design-decisions, monitoring, recovery] sensitivity: private-infrastructure -last_reviewed: "2026-10-06" +last_reviewed: "2026-10-16" sources: - 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" -related: [home-server.reference, home-server.host, home-server.mercury, home-server.networking, home-server.storage, home-server.backups, home-server.deployment] + - 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" +related: [home-server.reference, home-server.host, home-server.mercury, 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-four-backed-up-directories + - data-criticality-outside-the-six-backed-up-directories - tested-full-host-recovery-order - monitoring-review-frequency --- @@ -26,14 +28,21 @@ unknowns: | Decision | Reason / accepted tradeoff | | --- | --- | | RAID 0 for HDD data | Capacity prioritized over disk redundancy; downloaded media can be reacquired | -| Back up important state | Four application directories covered; media redundancy is not the objective | +| 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 | +| Authentik instead of Authelia | Native OIDC rather than only forward-auth; retain forward-auth where needed | +| Three access categories | Admin: owner only, server health/operations; Developers: development services such as Gitea/Portainer; Clients: useful end-user services such as Wardrowbe/Paperless | 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. + ## Observability | Facility | Current configuration | @@ -44,6 +53,9 @@ that every important dataset is covered. Monitoring does not imply notification delivery. Backup-hook failures, stopped services and storage failures require manual detection. +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 @@ -58,8 +70,10 @@ stopped services and storage failures require manual detection. | Independent host-config archive | Not maintained | | Operational rules / rollback policy | Not established | -Backup scope is documented in [Backups](backups.md). The four-directory plan -does not establish OS, host-configuration or named-volume recovery. +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 diff --git a/docs/home-server/portainer.md b/docs/home-server/portainer.md index 642dc19..b04af8f 100644 --- a/docs/home-server/portainer.md +++ b/docs/home-server/portainer.md @@ -4,18 +4,20 @@ id: home-server.portainer type: reference scope: [jupiter, portainer, deployment, configuration-state] sensitivity: private-infrastructure -last_reviewed: "2026-10-06" +last_reviewed: "2026-10-16" 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: repository repository: jupiter-stacks - revision: working-tree - base_revision: 610e325ef6a98850511ce7a089b0b9a77bfecf15 + 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] @@ -43,8 +45,21 @@ Reference script: [portainer_start.sh](https://github.com/jayo60013/jupiter-stac 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 Authelia middleware. Local router does not establish -local DNS resolution. +Supplied routers attach no forward-auth middleware. Local router does not +establish local DNS resolution. + +## Authentication + +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. +Application access requires Authentik group `development` (owner's Developers +category); this 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 diff --git a/docs/home-server/storage.md b/docs/home-server/storage.md index dc171b4..e57be18 100644 --- a/docs/home-server/storage.md +++ b/docs/home-server/storage.md @@ -2,28 +2,31 @@ schema_version: 1 id: home-server.storage type: reference -scope: [jupiter, disks, raid, filesystems, docker-volumes] +scope: [jupiter, seedbox, disks, raid, filesystems, docker-volumes, remote-storage] sensitivity: private-infrastructure -last_reviewed: "2026-10-06" +last_reviewed: "2026-10-16" sources: - kind: owner-report reference: "lsblk filesystem output, RAID level, mount placement and Docker data root, 2026-10-06" - kind: owner-report - reference: "Seedbox rclone mount and systemd unit, 2026-10-06" + 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: 610e325ef6a98850511ce7a089b0b9a77bfecf15 + revision: d09df456ad331b8beb9a40615114ea8aae2dced5 paths: - stacks/backrest/docker-compose.yml - stacks/jellyfin/docker-compose.yml - - stacks/authelia/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.seedbox, home-server.portainer, home-server.backups, home-server.operations] -update_triggers: [disk-change, raid-change, mount-change, volume-change, backup-coverage-change] +update_triggers: [disk-change, raid-change, mount-change, volume-change, backup-coverage-change, seedbox-change] unknowns: [persistent-mdadm-config-and-initramfs-content, disk-health] --- @@ -36,6 +39,7 @@ config: .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; } @@ -48,6 +52,16 @@ config: rankSpacing: 45 --- flowchart LR + subgraph Remote["ULTRA.CC / SEEDBOX"] + SEED[("terra.usbx.me
1001 GB allocation
downloads/qbittorrent")] + end + + subgraph Import["JUPITER / REMOTE MEDIA IMPORT"] + MOUNT["/mnt/seedbox
rclone / SFTP / FUSE
Not a local replica"] + ARR["Radarr / Sonarr
Container /downloads"] + MOUNT -->|"Bind-mounted download source"| ARR + end + subgraph Array["HDD ARRAY / APPLICATION DATA"] direction TB A["Seagate BarraCuda
sda1 / 2 TB"] @@ -74,14 +88,42 @@ flowchart LR ROOT --> CACHE end - class A,B,SSD,DATA,ROOT infraStorage + SEED -->|"Remote reads / SFTP via rclone"| MOUNT + ARR -->|"Import to /data/jellyfin/movies or tv_shows"| DATA + + class A,B,SSD,DATA,ROOT,SEED infraStorage class RAID infraCloud class EFI,SWAP infraClient - class DOCKER,CACHE infraService + class DOCKER,CACHE,MOUNT,ARR infraService ``` RAID 0: striping; no redundancy; either HDD failure loses the array. +## Seedbox storage / imports + +The [Ultra.cc seedbox](seedbox.md) is separate remote storage, not part of +Jupiter's RAID or SSD. Host `terra.usbx.me`, plan `Lancer-v2`: 1001 GB allocation, +984 GB available in the supplied 2026-10-06 snapshot. + +```text +/home/jayo60013/downloads/qbittorrent (seedbox) + -> rclone remote seedbox:downloads/qbittorrent + -> /mnt/seedbox (Jupiter SFTP/FUSE mount) + -> /downloads (Radarr / Sonarr bind mount) + -> /data/jellyfin/{movies,tv_shows} (imported library on HDD array) +``` + +`rclone-seedbox.service` manages the mount; it is not a scheduled sync or full +local replica. `--vfs-cache-mode writes` streams read-only opens; the cache +location and size limit are unconfirmed. Cross-filesystem hardlinks to the +local libraries are impossible. Host remounts do not automatically propagate +through the containers' `rprivate` binds. + +The six-directory Backrest plan does not cover the seedbox or media libraries; +the provider's own backup policy is unknown. FUSE-reported capacity does not +establish the account quota. Import/removal behaviour and mount details remain +documented on the [Seedbox](seedbox.md) page. + ## Filesystems Device names reflect the supplied snapshot; UUIDs identify filesystems. @@ -137,11 +179,16 @@ Seedbox FUSE mount is service-managed, not listed in fstab. | `/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/authelia` | Configuration, users, SQLite, notifications | +| `/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 | 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. ## Named-volume snapshot @@ -160,4 +207,4 @@ Inspected volumes below use driver `local`, no driver options, and 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 -four-directory backup plan. +six-directory backup plan.