From 7343501b25701497c95ef5d52cd0f0539e8cb031 Mon Sep 17 00:00:00 2001
From: "l.kirchner" <l.kirchner@noreply.gitea.luki-net.org>
Date: Thu, 21 May 2026 23:05:38 +0200
Subject: [PATCH] Add docs/adding-a-script.md

---
 docs/adding-a-script.md | 118 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 docs/adding-a-script.md

diff --git a/docs/adding-a-script.md b/docs/adding-a-script.md
new file mode 100644
index 0000000..1a6ea39
--- /dev/null
+++ b/docs/adding-a-script.md
@@ -0,0 +1,118 @@
+# Adding a new script
+
+Two files per app, both sourcing the shared libs at runtime.
+
+## 1. `install/<app>-install.sh` — runs inside the LXC
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+APP="myapp"
+LIB_URL="${LIB_URL:-https://gitea.luki-net.org/luki-net/proxmox-scripts/raw/branch/main/lib}"
+source <(curl -fsSL "$LIB_URL/install.func")
+
+[[ "$EUID" -eq 0 ]] || { msg_err "Must run as root"; exit 1; }
+
+setup_base_apt git some-package          # base packages + extras
+create_system_user myapp /opt/myapp
+
+# ... app-specific install ...
+
+write_systemd_unit myapp "$(cat <<EOF
+[Unit]
+Description=my app
+After=network-online.target
+
+[Service]
+ExecStart=/opt/myapp/bin/myapp
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+EOF
+)"
+
+wait_for_http "http://127.0.0.1:8080/" 30
+apt_cleanup
+msg_ok "$APP installation finished"
+```
+
+### Helpers from `lib/install.func`
+
+| Helper | Purpose |
+|--------|---------|
+| `msg_info` / `msg_ok` / `msg_warn` / `msg_err` | colored logging |
+| `setup_base_apt [pkg...]` | apt update + base packages (ca-certificates curl openssl tzdata gnupg) + extras |
+| `apt_cleanup` | autoremove + autoclean |
+| `create_system_user USER HOME` | `useradd --system`, idempotent |
+| `write_systemd_unit NAME CONTENT` | write unit file + daemon-reload + `enable --now` |
+| `wait_for_http URL [TIMEOUT]` | retry-curl until 2xx (default 30s) |
+
+## 2. `ct/<app>.sh` — runs on the Proxmox host
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+APP="myapp"
+APP_DESCRIPTION="short tagline"
+APP_PORT="8080"
+
+LIB_URL="${LIB_URL:-https://gitea.luki-net.org/luki-net/proxmox-scripts/raw/branch/main/lib}"
+INSTALL_SCRIPT_URL="${INSTALL_SCRIPT_URL:-https://gitea.luki-net.org/luki-net/proxmox-scripts/raw/branch/main/install/myapp-install.sh}"
+
+# App-specific defaults
+DEFAULT_HOSTNAME="myapp"
+DEFAULT_DISK="10"
+DEFAULT_CORES="2"
+DEFAULT_RAM="1024"
+
+source <(curl -fsSL "$LIB_URL/build.func")
+
+# Override the default summary printer with whatever the app needs.
+print_app_summary() {
+  cat <<EOF
+  Web UI:   http://$IP_CT:$APP_PORT
+EOF
+}
+
+run_installer
+```
+
+### What `run_installer` does
+
+1. `preflight_pve` — root + Proxmox check
+2. `show_header` — banner
+3. `prompt_lxc_config` — interactive prompts (skipped if vars are already set via env)
+4. `resolve_debian_template` — picks the latest matching template, downloads if missing
+5. `create_lxc` — `pct create` with all gathered settings, generates `ROOT_PASSWORD`
+6. `bootstrap_install_script "$INSTALL_SCRIPT_URL"` — installs curl in the LXC, downloads + runs the in-container installer
+7. `print_summary` — calls your `print_app_summary` + LXC root password
+
+## 3. Add to README
+
+Append a row to the "Available scripts" table in `README.md` with the one-liner:
+
+```bash
+bash -c "$(curl -fsSL https://gitea.luki-net.org/luki-net/proxmox-scripts/raw/branch/main/ct/myapp.sh)"
+```
+
+## 4. Commit
+
+```bash
+git add ct/myapp.sh install/myapp-install.sh README.md
+git commit -m "Add myapp installer"
+git push
+```
+
+## Tips
+
+- **Idempotency**: install scripts may be re-run if a build fails midway. Guard expensive steps (`[[ ! -x ... ]]`, `[[ ! -f ... ]]`).
+- **Credentials**: write generated passwords to `/root/<app>.credentials` (chmod 600). The host-side `print_app_summary` can `pct exec` to read them back.
+- **Env-driven non-interactive use**:
+  ```bash
+  CTID=200 HOSTNAME=myapp DISK_SIZE=30 RAM=4096 IPCFG=dhcp \
+    bash -c "$(curl -fsSL .../ct/myapp.sh)"
+  ```
+- **Local testing**: set `LIB_URL` to your fork's URL or a feature branch to test lib changes without touching `main`.