proxmox-scripts/docs/adding-a-script.md

Adding a new script

Two files per app, both sourcing the shared libs at runtime.

1. install/<app>-install.sh — runs inside the LXC

#!/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

#!/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 -c "$(curl -fsSL https://gitea.luki-net.org/luki-net/proxmox-scripts/raw/branch/main/ct/myapp.sh)"

4. Commit

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:

  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.