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

4.9 KiB

schema_version, id, type, scope, sensitivity, last_reviewed, sources, related, update_triggers, unknowns
schema_version id type scope sensitivity last_reviewed sources related update_triggers unknowns
1 home-server.deployment reference
jupiter
portainer
github
stack-deployment
secrets
private-infrastructure 2026-10-27
kind reference
owner-report 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 revision paths
repository jupiter-stacks 12fb1b96e01fc062fdce4c216f11eb5d7ce716ed
stacks/traefik/docker-compose.yml
stacks/authentik/docker-compose.yml
stacks/downloads/docker-compose.yml
stacks/notes/docker-compose.yml
home-server.portainer
home-server.authentication
home-server.downloads
home-server.notes
home-server.networking
home-server.backups
deployment-workflow-change
repository-change
credential-rotation
github-pat-scopes-and-expiration
general-health-gates-and-approval-policy

Deployment

---
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
Gitea creates notes_build Notes Notes deployment
Secure Authentik + apply host blueprint Public authentication Authentication
Independent SSH session Replace Portainer Standalone deployment

Ingress transport deployment and rollback

Current routing convention: Networking. 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.
  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.
  • 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.
  • General approvals/drift policy and full-host recovery order remain undefined.