105 lines
3.9 KiB
Markdown
105 lines
3.9 KiB
Markdown
# 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.
|