--- schema_version: 1 id: home-server.deployment type: reference scope: [jupiter, portainer, github, stack-deployment, secrets] sensitivity: private-infrastructure last_reviewed: "2026-10-27" sources: - kind: owner-report 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: 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 ```mermaid --- config: themeCSS: | text,.nodeLabel { fill:var(--infra-text);color:var(--infra-text); } .flowchart-link { stroke:var(--infra-line); } marker path { fill:var(--infra-line);stroke:var(--infra-line); } .infraClient rect { fill:var(--infra-client-fill);stroke:var(--infra-client-stroke);rx:8px;ry:8px; } .infraEdge rect { fill:var(--infra-edge-fill);stroke:var(--infra-edge-stroke);rx:8px;ry:8px; } .infraService rect { fill:var(--infra-service-fill);stroke:var(--infra-service-stroke);rx:8px;ry:8px; } --- flowchart LR accTitle: Manual Git-backed stack deployment accDescr: Pushing configuration does not deploy it; Portainer must pull and redeploy before runtime checks. Git["Push main
jupiter-stacks"]:::infraClient Portainer["Portainer
manual pull / redeploy"]:::infraEdge Runtime["Running containers
check routes + health"]:::infraService Git --> Portainer --> Runtime ``` - Source: , branch `main`; GitHub PAT in Portainer. - Stack values/secrets live in Portainer; AirVPN keys are root-restricted host files. - Git updates do not populate bind-mounted files or application databases. - Native Compose version does not establish Portainer's Compose implementation. - Host apt, fstab/RAID, systemd and Mercury nginx are outside this workflow. ## Prerequisites / order | 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) | ## Ingress transport deployment and rollback Current routing convention: [Networking](networking.md#listener-and-trust-boundaries). Owner confirmed cutover complete **2026-10-27**. 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. - 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. ## Reconstruction limits - 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.