# 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 — owner `jtr`)

All repos are private, under user `jtr` at `git.pterois.co.uk`. Property-neutral
names, since the stack deploys at multiple hotels:

| Repo | Contents | Provisioned to |
|------|----------|----------------|
| `proxmox-helpers` | 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).

> Repos live under user `jtr` (there are no Forgejo orgs). The `FORGEJO_BASE`
> default in the wizard is `https://git.pterois.co.uk/jtr`.

## 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). All repos are public, so no token needed:

```bash
bash <(curl -fsSL https://git.pterois.co.uk/jtr/proxmox-helpers-hotel-manage-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, 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. (Leave the Forgejo token blank — the repos are public.)

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 https://git.pterois.co.uk/jtr/proxmox-helpers-hotel-manage-stack/raw/branch/main/add-app.sh)
```

Reads `/root/hnf-credentials.txt` for the shared secret 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

- All repos are public, so no Forgejo token is needed to install or update.
  The wizard still accepts a token (used only if you later make the repos
  private again — it gets embedded in each LXC's git remote for the updater).
- `install-stack.sh` is idempotent-ish: existing LXCs are skipped (started if
  stopped) rather than recreated, so a re-run resumes a partial install.