Initial commit: stack

2026-07-01 12:09:54 +00:00 · 2026-07-01 12:09:54 +00:00 · fe16a07dd7
commit fe16a07dd7
11 changed files with 2058 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,105 @@
+# Proxmox Helpers — HNF Stack Installer
+
+tteck-style helper scripts that provision the stack onto a fresh Proxmox host —
+no local copy of the repo required on the host.
+
+## Install vs. update — two separate paths
+
+- **Install** (creating an LXC) runs **on the Proxmox host**, because `pct` only
+  exists on the hypervisor. That's what these scripts are for.
+- **Updates** (git pull + `docker compose up --build`) are driven **from the
+  management container** over SSH — no hypervisor access needed. Push to a
+  service repo → Forgejo webhook → management redeploys that LXC in place.
+
+So the management container never creates LXCs; it only updates, monitors and
+backs up what these scripts provisioned.
+
+## Repo layout (Forgejo — org `proxmox-helpers`)
+
+Property-neutral names, since the stack deploys at multiple hotels:
+
+| Repo | Contents | Provisioned to |
+|------|----------|----------------|
+| `stack` | Installer scripts + `docs/` + `infrastructure/` reference | run on the Proxmox host |
+| `auth` | central auth service | LXC 101 |
+| `portal` | PWA portal shell | LXC 102 |
+| `management` | updater + Kuma + backup | LXC 105 |
+| `noticeboard` | starter app | LXC 112 |
+| `kitchen`, `cashup`, … | one repo per app | added later |
+
+Postgres (LXC 100) and NPM (LXC 103) have no repo — the installer generates
+their compose files inline (they carry secrets / are pure infra).
+
+> Owner assumed to be a Forgejo org named `proxmox-helpers`. If your repos live
+> under a user account or a different org, adjust the URLs below and the
+> `FORGEJO_BASE` default in the wizard.
+
+## One-time host prep
+
+Add the internal bridge to `/etc/network/interfaces`, then `ifreload -a`:
+
+```
+auto vmbr1
+iface vmbr1 inet static
+    address  10.10.10.1/24
+    bridge-ports none
+    bridge-stp off
+    bridge-fd 0
+```
+
+The installer will offer to download the Ubuntu 22.04 template if missing.
+
+## Run the installer (foundation)
+
+On the Proxmox host shell (as root):
+
+**Public repo:**
+```bash
+bash <(curl -fsSL https://git.pterois.co.uk/proxmox-helpers/stack/raw/branch/main/install-stack.sh)
+```
+
+**Private repo** (raw fetch needs the same token you'll paste into the wizard):
+```bash
+TOKEN=xxxxxxxx
+bash <(curl -fsSL -H "Authorization: token $TOKEN" \
+  https://git.pterois.co.uk/proxmox-helpers/stack/raw/branch/main/install-stack.sh)
+```
+
+The wizard collects site name, domain, NPM LAN IP/gateway, office IP for
+offsite restriction, admin credentials, the Forgejo base URL + access token,
+and a backup target. It then provisions the six foundation LXCs (postgres,
+auth, portal, npm, management, noticeboard), health-checks each, and configures
+the NPM proxy routes.
+
+Secrets are written to `/root/hnf-credentials.txt` (chmod 600) — copy this
+offsite.
+
+## Add an app later
+
+On the Proxmox host (again, because it creates an LXC):
+
+```bash
+bash <(curl -fsSL -H "Authorization: token $TOKEN" \
+  https://git.pterois.co.uk/proxmox-helpers/stack/raw/branch/main/add-app.sh)
+```
+
+Reads `/root/hnf-credentials.txt` for the shared secret, Forgejo token and
+office IP, provisions a new LXC, optionally creates a dedicated postgres DB,
+clones the app repo, and prints the NPM route / Uptime Kuma / webhook /
+deploy-map lines to finish wiring it in. After that, ongoing updates flow
+through the management container automatically.
+
+## Replicating to another hotel
+
+Same command on the new host. Only the wizard answers differ per site:
+`DOMAIN`, NPM LAN IP + gateway (that site's LAN pool), and `OFFICE_IP_CHECK`.
+The internal `10.10.10.0/24` network and all service IPs are identical
+everywhere, so the repos are reused unchanged.
+
+## Notes
+
+- The Forgejo token is embedded in each LXC's git remote URL so the management
+  updater can `git pull` on webhook without extra credentials. Use a
+  dedicated, least-privilege token (read:repository).
+- `install-stack.sh` is idempotent-ish: existing LXCs are skipped (started if
+  stopped) rather than recreated, so a re-run resumes a partial install.