reterminal-dm4/emmc-provisioning/docs/DEPLOY-NEW-PROXMOX.md

Deploy CM4 eMMC Provisioning to a New Proxmox Instance

Step-by-step guide to deploy the provisioning service (host + LXC) on a new Proxmox server. For redeploy/update and troubleshooting, see PROXMOX-LXC-DEPLOYMENT.md.

---

Prerequisites (before running the deploy script)

Requirement	Details
Proxmox host	A Proxmox VE node (new or existing) where you want the service.
SSH as root	You must be able to run ssh root@YOUR_PROXMOX_HOST with key-based auth (no password prompt).
Proxmox storage	At least one active storage (e.g. local or local-lvm). Check on the host: pvesm status.
Host internet (recommended)	Needed so the deploy script can download the Debian 12 LXC template (if missing), and install usbboot and PiShrink on the host. Without internet, deploy still runs but you must install usbboot and PiShrink manually later.

Optional (set before deploy):

• DEPLOY_ROOTFS_STORAGE=local-lvm — Skip interactive storage choice when creating the LXC.
• DEPLOY_LXC_ROOT_PASSWORD=yourpassword — Set LXC root password and enable SSH.
• DEPLOY_LXC_SSH_KEY=/path/to/pub — Copy this key into the LXC (default: ~/.ssh/id_ed25519.pub or id_rsa.pub).
• CM4_BACKUPS_HOST_PATH=/mnt/storage/cm4-backups — Store backups on this host path (create the directory on the host if needed).
• Network (WAN/LAN):
  DEPLOY_LXC_WAN_BRIDGE=vmbr0 (default), DEPLOY_LXC_WAN_IP=dhcp (default),
  DEPLOY_LXC_LAN_BRIDGE=vmbr1, DEPLOY_LXC_LAN_SUBNET=10.20.50.1/24 — To add eth1 as provisioning LAN. Set these if you want the portal reachable from the LAN (e.g. http://10.20.50.1:5000); the dashboard listens on all interfaces.

---

Step 1: Run the deploy script

From your workstation (where the repo is cloned), run:

cd /path/to/reTerminal\ DM4

./emmc-provisioning/scripts/deploy-to-proxmox.sh root@YOUR_PROXMOX_HOST

Replace YOUR_PROXMOX_HOST with the Proxmox hostname or IP (e.g. 10.20.30.40).

Example with options:

DEPLOY_ROOTFS_STORAGE=local-lvm \
DEPLOY_LXC_ROOT_PASSWORD='YourSecurePassword' \
DEPLOY_LXC_LAN_BRIDGE=vmbr1 \
DEPLOY_LXC_LAN_SUBNET=10.20.50.1/24 \
./emmc-provisioning/scripts/deploy-to-proxmox.sh root@10.20.30.40

• On first run, the script will ask you to choose LXC rootfs storage (unless DEPLOY_ROOTFS_STORAGE is set). It then creates the LXC, installs host scripts, udev, systemd units, and the dashboard in the LXC.
• The script prints LXC IP (WAN) and, if you set DEPLOY_LXC_LAN_BRIDGE, LXC IP (LAN). The portal is reachable at http://<IP>:5000 on both; use the LAN IP from devices on the provisioning LAN.

---

Step 2: Install usbboot on the host (if host had no internet during deploy)

USB flash/backup needs rpiboot on the Proxmox host. If the deploy log said usbboot install failed or was skipped:

From your workstation:

scp emmc-provisioning/scripts/install-usbboot-on-host.sh root@YOUR_PROXMOX_HOST:/tmp/
ssh root@YOUR_PROXMOX_HOST "bash /tmp/install-usbboot-on-host.sh"

Or on the Proxmox host (if /tmp/emmc-provisioning-deploy is still there):

ssh root@YOUR_PROXMOX_HOST
bash /tmp/emmc-provisioning-deploy/scripts/install-usbboot-on-host.sh

---

Step 3: Add a golden image (required for Deploy)

To write an image to a device (Deploy), the host must have a golden image at /var/lib/cm4-provisioning/golden.img. Backup (read from device) works without it.

Option A — From the dashboard

1. Open http://<LXC-IP>:5000 (use the LXC IP from the deploy output).
2. Build a cloud-init image or upload/set an existing backup as golden (see dashboard Admin).

Option B — Copy an image from your machine

scp /path/to/your-golden.img root@YOUR_PROXMOX_HOST:/var/lib/cm4-provisioning/golden.img

---

Accessing the portal from the LAN

The dashboard listens on all interfaces (0.0.0.0:5000), so it is reachable on both WAN and LAN IPs when the LXC has two networks.

• Deploy with a LAN interface: set DEPLOY_LXC_LAN_BRIDGE=vmbr1 (and optionally DEPLOY_LXC_LAN_SUBNET=10.20.50.1/24) when running the deploy script. The LXC will get eth1 with the LAN IP (e.g. 10.20.50.1).
• From the provisioning LAN: open http://<LAN-IP>:5000 (e.g. http://10.20.50.1:5000). Devices on that subnet can use the portal without going through WAN.
• If you did not set a LAN bridge at deploy time, you only have one IP (WAN); use that for the portal. To add LAN later you would need to add eth1 to the container and reconfigure (see PROXMOX-LXC-DEPLOYMENT.md).

---

Step 4: (Optional) SSH into the LXC

If you set DEPLOY_LXC_ROOT_PASSWORD or had a default SSH key, you can already run:

ssh root@<LXC-IP>

Otherwise, enable root SSH and add your key:

./emmc-provisioning/scripts/setup-lxc-ssh.sh root@YOUR_PROXMOX_HOST
# Or with password: ROOT_PASSWORD='YourPassword' ./emmc-provisioning/scripts/setup-lxc-ssh.sh root@YOUR_PROXMOX_HOST ~/.ssh/id_ed25519.pub

---

Step 5: (Optional) Network boot (DHCP + TFTP on eth1)

Only if you deployed with DEPLOY_LXC_LAN_BRIDGE (and optionally DEPLOY_LXC_LAN_SUBNET) and want to offer network boot to devices on that LAN:

./emmc-provisioning/scripts/setup-network-boot-on-lxc.sh root@<LXC-IP>

See NETWORK-BOOT-LXC.md for details.

---

Step 6: (Optional) Install PiShrink on the host

If the deploy log said PiShrink install failed (e.g. no internet), and you want Shrink/Compress in the dashboard to work:

ssh root@YOUR_PROXMOX_HOST "bash /tmp/emmc-provisioning-deploy/scripts/install-pishrink-on-host.sh"

Or from your machine (stream the script): use the same pattern as in PROXMOX-LXC-DEPLOYMENT.md for install-pishrink-on-host.sh.

---

Summary checklist

Step	Action	Required?
1	Run deploy-to-proxmox.sh root@YOUR_PROXMOX_HOST	Yes
2	Install usbboot on host (if deploy couldn’t)	For USB flash/backup
3	Add golden.img for Deploy	For Deploy only
4	SSH to LXC (or use setup-lxc-ssh.sh)	Optional
5	Run setup-network-boot-on-lxc.sh (if using eth1 LAN)	Optional
6	Install PiShrink on host (if deploy couldn’t)	For Shrink/Compress

After deployment:

• Dashboard: http://<LXC-IP>:5000 (WAN). If you set DEPLOY_LXC_LAN_BRIDGE, also http://<LAN-IP>:5000 (e.g. http://10.20.50.1:5000) from the LAN.
• Golden image path (host and LXC): /var/lib/cm4-provisioning/golden.img
• Disable auto-flash: ssh root@YOUR_PROXMOX_HOST "rm /etc/cm4-provisioning/enabled"
• Enable again: ssh root@YOUR_PROXMOX_HOST "touch /etc/cm4-provisioning/enabled"

If you see "rpiboot failed or no device connected": The error is from the Proxmox host (where USB is connected). On the host run: tail -50 /var/lib/cm4-provisioning/flash.log to see the real rpiboot message. Ensure the reTerminal is in boot mode (eMMC disable jumper, USB slave port), then unplug/replug. See PROXMOX-LXC-DEPLOYMENT.md § "If rpiboot fails" for full steps.

Full reference: PROXMOX-LXC-DEPLOYMENT.md.