busbar-designer/deploy/README.md

Deploy

Three scripts here, plus the systemd unit.

File	Where it runs	What it does
proxmox-lxc.sh	Proxmox VE host as root	Creates an unprivileged Debian 12 LXC, then runs install.sh inside it.
install.sh	inside an LXC/VM/server	Clones the repo, sets up Python venv, installs deps, starts systemd unit.
update.sh	inside the LXC/VM/server	git pull + refresh Python deps + systemctl restart.
busbar-designer.service	systemd	Unit file template; install.sh substitutes paths/user/port.

All scripts are idempotent (safe to re-run) and use only stdlib + Debian-shipped tools (pct, pveam, whiptail, git, python3). No external dependencies.

---

Step 0 — push to your Gitea (one time)

# on your laptop, in this repo
git remote add gitea https://gitea.local/me/busbar-designer.git
git push gitea main

If your Gitea uses a self-signed cert, set GIT_SSL_NO_VERIFY=1 everywhere (or install the cert into the system trust store).

---

Path A — Proxmox VE host (recommended)

One-liner from the Proxmox shell:

bash -c "$(curl -fsSL https://gitea.local/me/busbar-designer/raw/branch/main/deploy/proxmox-lxc.sh)"

(Substitute https://gitea.local/me/busbar-designer/raw/branch/main/deploy/proxmox-lxc.sh with your repo's raw URL. Gitea's raw URL format is https://<host>/<user>/<repo>/raw/branch/<branch>/<path>.)

You'll get whiptail prompts for:

• Container ID (defaults to next available)
• Hostname (busbar-designer)
• Disk size (4 GB), cores (2), RAM (1024 MB)
• Storage pool, network bridge, IP (dhcp or 1.2.3.4/24,gw=1.2.3.1)
• Repo URL & branch
• Skip TLS verify? (yes if your Gitea uses self-signed certs)

The script will:

1. Download Debian 12 template if missing.
2. Create the LXC, start it.
3. Inside the LXC: clone the repo, install everything, enable systemd.
4. Print the URL + root password + management commands.

To skip prompts (CI / scripted re-deploys):

CTID=210 HOSTNAME=busbar DISK_SIZE=4 CORES=2 RAM=1024 \
BRIDGE=vmbr0 IP=dhcp STORAGE=local-lvm \
REPO_URL=https://gitea.local/me/busbar-designer.git BRANCH=main \
bash deploy/proxmox-lxc.sh

---

Path B — inside an existing LXC / VM / bare server

Already have a Debian 12 / Ubuntu 22.04 / 24.04 host? Just run the installer:

REPO_URL=https://gitea.local/me/busbar-designer.git \
bash -c "$(curl -fsSL https://gitea.local/me/busbar-designer/raw/branch/main/deploy/install.sh)"

Defaults to /opt/busbar-designer, user busbar, port 5000. Override with INSTALL_DIR, SVC_USER, PORT.

---

Updating

From the Proxmox host:

pct exec 210 -- bash /opt/busbar-designer/deploy/update.sh

From inside the LXC:

sudo bash /opt/busbar-designer/deploy/update.sh

The updater does git fetch + reset --hard on the tracked branch, refreshes Python deps, restarts the service.

Optional: auto-deploy via Gitea webhook

In your Gitea repo → Settings → Webhooks → Add Webhook (Gitea):

• URL: http://<lxc-ip>:5050/hook (you'd need to add a tiny webhook listener; not built-in)
• Trigger: Push
• Branch filter: main

Out of the box there's no webhook endpoint — the simplest path is a cron */5 * * * * root bash /opt/busbar-designer/deploy/update.sh if you want polling, or just SSH and re-run update.sh after each push.

---

Backup & restore

Everything user-generated lives in /opt/busbar-designer/data/busbar.db (SQLite, single file).

# Backup (from Proxmox host)
pct exec 210 -- cat /opt/busbar-designer/data/busbar.db > busbar-backup-$(date +%F).db

# Restore
cat busbar-backup-2026-05-24.db | pct exec 210 -- bash -c \
  'systemctl stop busbar-designer && cat > /opt/busbar-designer/data/busbar.db && chown busbar:busbar /opt/busbar-designer/data/busbar.db && systemctl start busbar-designer'

Or via Proxmox's own LXC backup (vzdump) which captures the whole rootfs.

---

Troubleshooting

Symptom	Fix
pveversion: command not found	The Proxmox script is not running on a PVE host. Use install.sh directly inside the LXC.
Git clone fails with TLS error	Set GIT_SSL_NO_VERIFY=1 env var, or install your Gitea CA cert into /usr/local/share/ca-certificates.
Service starts, then dies	pct exec <CTID> -- journalctl -u busbar-designer -n 100. Usually the build123d wheel didn't install — Debian 12 ships Python 3.11 which is fine.
Browser shows 502 / can't connect	Check the LXC's IP with pct exec <CTID> -- ip a. If using DHCP, the IP may have changed.
pveam download fails	Run pveam update on the host first.