Files
infrastructure/proxmox/lxc/ct-102-keycloak/scripts

Proxmox automation

CT 102 Keycloak provisioning profile

The replacement Keycloak LXC uses CT 104 as its measured reference. CT 104 currently exposes 2 vCPUs, 4 GiB RAM, 1 GiB swap and a 12 GiB root filesystem; the complete running stack uses about 626 MiB RAM and 2.6 GiB disk. CT 102 is therefore provisioned with the same CPU and memory allocation but a moderately larger root disk for parallel image versions, package updates and Ansible staging:

Setting CT 102 value
CT ID / hostname 102 / keycloak
OS Debian 13, amd64
Container type unprivileged LXC with nesting enabled
CPU 2 cores
Memory 4096 MiB
Swap 1024 MiB
Root disk 16 GiB, thin-provisioned LXC storage
Network vmbr0, 10.0.0.4/24, gateway 10.0.0.1, IPv6 disabled
Boot / protection start on boot, protection enabled after creation
Time zone Europe/Berlin
Initial root SSH not required; the hook installs and hardens OpenSSH
Post-install hook /usr/local/sbin/ghostnet-keycloak-ansible-bootstrap-hook.sh

The Community Scripts Podman helper does not currently expose a swap variable, so the reviewed launcher sets pct set 102 --swap 1024 after successful creation and then verifies the complete PVE configuration. The 2026-10-12 PVE preflight established local as the active template storage and local-lvm as the active thin-provisioned container storage, with sufficient free capacity.

The website-generated launcher is stored as provision-ct102-keycloak.sh, not as the ambiguous install.sh. It contains no password or private key. It pins the Community Scripts ProxmoxVE and core repositories to the revisions audited on 2026-10-12, verifies the downloaded Podman entry script, names every material CT setting explicitly, and rejects an occupied CT ID instead of silently allowing the helper to choose another one.

Before running it, install the two hooks documented below on the PVE host and verify that CT 102 no longer exists. Then execute the reviewed host copy as root:

/usr/local/sbin/provision-ct102-keycloak.sh

The launcher deliberately does not delete or replace an existing container. After Community Scripts returns, it configures 1024 MiB swap and treats the otherwise non-fatal post-install hook result as mandatory: the PVE profile, Debian release, Podman installation, SSH service, account UIDs and unattended ansible-deploy sudo path must all pass before the launcher reports success. The reviewed launcher copy has SHA-256 5105ff39bbbf6959a91fc2e5bda67cbf3bcf3eacdae4dcac5d70f5d0a636bd6f.

ghostnet-lxc-baseline.sh

The versioned source now lives at ../../../shared/scripts/ghostnet-lxc-baseline.sh. This script is the optional Community Scripts post-install hook. Install the reviewed version on the Proxmox host as:

/usr/local/sbin/ghostnet-lxc-baseline.sh

The host-side copy is owned by root:root with mode 0750. Verify its SHA-256 against the reviewed repository copy before executing it.

The Community Scripts field must contain that absolute path. The hook runs as root on the Proxmox host after the guest has been provisioned and started. Community Scripts supplies CTID; for a controlled rerun the CT ID can also be passed as the first argument:

/usr/local/sbin/ghostnet-lxc-baseline.sh 104

The script is deliberately limited. It:

  • requires an existing, running, unprivileged Debian 12 or newer LXC;
  • aborts before account creation if UID/GID 1000 or 1001 is assigned or owns files unexpectedly;
  • installs ca-certificates, openssh-server and sudo only when missing; it does not use the hook as a general package-upgrade mechanism;
  • creates or validates locked ghost-agent UID/GID 1000 and ghost UID/GID 1001 accounts;
  • grants only ghost membership in sudo;
  • prepares protected, empty authorized_keys files without truncating an existing file;
  • disables SSH socket activation, enables and restarts the classic SSH service, validates its syntax and reports the guest host-key fingerprint.
  • removes only the known dangling wtmpdb-rotate.timer enable link left by the Debian 13 package transition, and only when its target is absent and no installed package owns that target.

It intentionally does not install public or private keys, set passwords, change root authentication, write an SSH hardening drop-in, configure a firewall, alter application users, or install application workloads. Those steps remain host-specific and require positive and negative access tests.

The script is idempotent for an already compliant guest. Any identity or numeric-owner mismatch stops the hook instead of guessing a replacement UID. Community Scripts retains the created LXC if the hook fails and writes hook output to /var/log/community-scripts/post-install-<CTID>.log on the Proxmox host.

The current reviewed copy has SHA-256 111f1b70e47e3a2f6a1bcce22cb0ec50aacd8fbcff37d87fbcf853a318381b10. An earlier copy with SHA-256 a0ee32a8fc2854c29a83b17b4e0cdb5ad55cde36de92d562f6bd890dc93ae89e was installed on the Ghostnet Proxmox host and rerun against CT 104 on 2026-10-06. The convergence run performed no package transaction, preserved both authorized-key files and passed the subsequent access and SSH-denial tests.

ghostnet-keycloak-ansible-bootstrap-hook.sh

This is the CT-102-specific Community Scripts post-install hook for the reproducible Keycloak rebuild. It calls the generic baseline above and then establishes only the transport and privilege boundary needed by Ansible:

  • it refuses any CT ID other than 102, any helper application other than Podman, a hostname other than keycloak, or a guest without 10.0.0.4;
  • it creates or validates ghost-agent 1000:1000, ghost 1001:1001 and ansible-deploy 1002:1002;
  • it installs the three role-specific public keys, limited to the documented management networks; the embedded keys must remain identical to ../ansible/files/ssh/keycloak-{ghost-agent,ghost,ansible-deploy}.pub;
  • it keeps ghost-agent and ansible-deploy passwords locked, grants only ansible-deploy reviewed NOPASSWD: ALL, and leaves ghost on Debian's password-gated sudo policy;
  • it disables SSH root/password authentication, empties the helper's temporary root authorized_keys, and validates SSH and sudo before returning success.

The hook does not configure nftables, Podman, PostgreSQL or Keycloak. Those states belong to the Ansible roles and their idempotence tests.

The reviewed repository copy currently has SHA-256 0e0499bc44834fdcc7d31814a8b2b4a2bed527fc8d4051e66d6cd92ac32b86c3. Verify the PVE-host copy against it before selecting the hook.

Install both reviewed scripts on the PVE host before launching the helper:

install -o root -g root -m 0750 \
  ghostnet-lxc-baseline.sh \
  /usr/local/sbin/ghostnet-lxc-baseline.sh

install -o root -g root -m 0700 \
  ghostnet-keycloak-ansible-bootstrap-hook.sh \
  /usr/local/sbin/ghostnet-keycloak-ansible-bootstrap-hook.sh

In the Podman helper's advanced settings, set the post-install hook to the absolute PVE-host path:

/usr/local/sbin/ghostnet-keycloak-ansible-bootstrap-hook.sh

Do not put this CT-specific path in a global Community Scripts defaults file. The helper executes it as PVE root after starting the new LXC and writes its output to /var/log/community-scripts/post-install-102.log. A non-zero hook exit is reported by the helper but does not roll back the already-created container or make the helper remove it; inspect the log and the resulting guest before any rerun.

The script deliberately cannot provision the personal ghost password. Set it without exposing it in chat or shell history:

pct exec 102 -- passwd ghost

After the hook, independently verify the new SSH host-key fingerprint through the PVE console, replace the obsolete CT-102 known-hosts entry, test all three positive/negative access paths, and only then run the Ansible preflight.

prepare-keycloak-cutover-dump.sh

This PVE-root operator script starts the final write freeze and therefore causes a deliberate Keycloak outage. It refuses to run unless CT 104, CT 102 and CT 103 are running, both PostgreSQL services are healthy, CT 102 remains empty and gated, and both NPM Keycloak proxy hosts still target CT 104 at 10.0.0.16.

After the explicit confirmation it stops only the CT 104 Keycloak application, leaves its PostgreSQL running, creates and catalogs a custom-format pg_dump --no-owner --no-acl, records the non-secret schema/realm summary, and transfers all root-only artifacts through PVE into CT 102. SHA-256 is checked at the source, on PVE and at the destination. If any step fails before the target transfer has been fully verified, the trap attempts to restart CT 104 Keycloak. On success CT 104 deliberately remains stopped to prevent new writes during restore and cutover.

Install the reviewed script as root on PVE and invoke it only at the agreed outage window:

install -o root -g root -m 0700 \
  prepare-keycloak-cutover-dump.sh \
  /usr/local/sbin/prepare-keycloak-cutover-dump.sh

GHOSTNET_CUTOVER_CONFIRMATION=STOP_CT104_AND_PREPARE_FINAL_KEYCLOAK_DUMP \
  /usr/local/sbin/prepare-keycloak-cutover-dump.sh

The final output supplies the CT 102 dump path and digest required by ../ansible/playbooks/restore.yml. Do not restart CT 104 or open the CT 102 application gate between these two steps.

The current reviewed script has SHA-256 7bc07d03230e208d28465e07bee16370d80293541eeea97f4f28e5d1b946a291.