[main]: document authentik
This commit is contained in:
8 files changed
+382
-76
No files matched your search
@@ -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>/`.
|
||||
|
||||
| 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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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["<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"]
|
||||
Rclone["<b>Host rclone / FUSE</b><br/>/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["<b>qBittorrent</b><br/>jayo60013.terra.usbx.me"]
|
||||
Downloads["<b>Remote download storage</b><br/>terra.usbx.me<br/>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
|
||||
<https://jayo60013.terra.usbx.me/qbittorrent/>.
|
||||
|
||||
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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
+57
-10
@@ -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[("<b>terra.usbx.me</b><br/>1001 GB allocation<br/>downloads/qbittorrent")]
|
||||
end
|
||||
|
||||
subgraph Import["JUPITER / REMOTE MEDIA IMPORT"]
|
||||
MOUNT["<b>/mnt/seedbox</b><br/>rclone / SFTP / FUSE<br/>Not a local replica"]
|
||||
ARR["<b>Radarr / Sonarr</b><br/>Container /downloads"]
|
||||
MOUNT -->|"Bind-mounted download source"| ARR
|
||||
end
|
||||
|
||||
subgraph Array["HDD ARRAY / APPLICATION DATA"]
|
||||
direction TB
|
||||
A["<b>Seagate BarraCuda</b><br/>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.
|
||||
Reference in new issue
Block a user