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 <(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):

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 <(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.