Files
notes/docs/home-server/deployment.md
T
2026-10-27 12:21:10 +00:00

82 lines
4.9 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-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<br/>jupiter-stacks"]:::infraClient
Portainer["Portainer<br/>manual pull / redeploy"]:::infraEdge
Runtime["Running containers<br/>check routes + health"]:::infraService
Git --> Portainer --> Runtime
```
- Source: <https://github.com/jayo60013/jupiter-stacks>, branch `main`; GitHub PAT in Portainer.
- Stack values/secrets live in Portainer; AirVPN keys are root-restricted host files.
- Git updates do not populate bind-mounted files or application databases.
- Native Compose version does not establish Portainer's Compose implementation.
- Host apt, fstab/RAID, systemd and Mercury nginx are outside this workflow.
## 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.