Files
notes/docs/home-server/deployment.md
T

106 lines
5.0 KiB
Markdown

---
schema_version: 1
id: home-server.deployment
type: reference
scope: [jupiter, portainer, github, stack-deployment, secrets]
sensitivity: private-infrastructure
last_reviewed: "2026-10-18"
sources:
- 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]
update_triggers: [deployment-workflow-change, repository-change, credential-rotation, rollback-policy-change]
unknowns:
- github-pat-scopes-and-expiration
- post-deployment-health-criteria
---
# 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 |
| 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
```
A Git commit is not deployment proof. Installed host Compose version is not
proof of Portainer's Compose implementation.
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.
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.
## 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.