reterminal-dm4/emmc-provisioning

reTerminal DM4 eMMC provisioning

Automatically deploy or backup the CM4 eMMC when the reTerminal is connected in USB boot mode or when it boots over the network. Uses cloud-init for first-boot configuration.

Revisions are tracked project-wide; see repo root README.md and scripts/bump-revision.sh.

---

Project layout

emmc-provisioning/
├── README.md                 ← You are here
├── docs/                     Documentation
│   ├── DEPLOY-NEW-PROXMOX.md         ★ START HERE: full deploy guide (host prep, LXC, scripts, network boot)
│   ├── EMMC-PROVISIONING-GUIDE.md   Golden image creation, cloud-init, PiShrink
│   ├── PROXMOX-LXC-DEPLOYMENT.md    Reference: what is deployed, redeploy, troubleshooting
│   ├── NETWORK-BOOT-LXC.md          Network boot architecture (PXE/dnsmasq, interfaces)
│   ├── NETWORK-BOOT-DEPLOYMENT-FLOW.md  Full data flow for network boot provisioning
│   ├── NETWORK-BOOT-TROUBLESHOOTING.md  Troubleshooting network boot issues
│   ├── DEVICE-DNS-DHCP-RESOLVCONF.md Device DNS from DHCP, resolv.conf, cloud-init
│   ├── DNSMASQ-DNS-FILESERVER.md    dnsmasq DNS and file.server on LXC
│   ├── PROXMOX-HOST-COMPARISON.md   Diff between Proxmox hosts (fixes checklist)
│   ├── PREPARE-IMAGE-FOR-CLOUDINIT.md  How to shrink and prep a golden image
│   ├── BACKUP-DEVICE-CONFIG-AUDIT.md   Audit of backup image contents
│   ├── DEVICE-REMOVABLE-PACKAGES.md    Packages to purge from the device image
│   ├── EDIT-CLOUDINIT-ON-DEVICE.md     Edit NoCloud files on-device or in .img.xz
│   └── PORTAL_STYLING_GUIDE.md      Dashboard UI styling reference
├── host/                     Scripts that run on the provisioning host (Proxmox host)
│   ├── flash-emmc-on-connect.sh     rpiboot + wait for Backup/Deploy choice, then dd
│   ├── cm4-flash-trigger.sh         Called by udev; starts the flash job
│   ├── build-cloudinit-image.sh     Build golden image with cloud-init
│   └── run-shrink-on-host.sh        PiShrink (optional)
├── scripts/                  Deployment and one-off scripts
│   ├── deploy-to-proxmox.sh         Deploy to Proxmox host + LXC
│   ├── sync-portal-files-to-lxc.sh  Sync cloud-init/first-boot assets to file server (LXC)
│   ├── deploy-dashboard-to-lxc.sh   Deploy dashboard to LXC
│   └── ... (other deploy/monitor scripts)
├── dashboard/                Flask web UI (runs in LXC or standalone)
│   ├── app.py
│   └── README.md
├── cloud-init/               First-boot and file-server assets
│   ├── first-boot.sh               Main first-boot script (two-phase provisioning)
│   ├── first-boot.conf             Active config (not committed with secrets)
│   ├── first-boot.conf.example     Reference config
│   ├── user-data-remote-gnss.example  Example cloud-init user-data
│   └── fileserver/                  Assets served by the portal file server
│       ├── README.md                Layout reference
│       ├── steps/                   Step scripts (01–13) sourced by first-boot.sh
│       ├── chromium-kiosk-no-select/  Chromium extension (disable text selection)
│       ├── start-chromium.sh        Chromium kiosk launcher
│       ├── five-tap-close-chromium.py  5-tap overlay (Wayland layer-shell)
│       └── ...                      Desktop files, config, theme, splash
├── lxc/                      LXC config snippets (dnsmasq, nftables)
└── network-client/           For network-booted devices
    ├── provisioning-client.sh      Register + poll, then Deploy or Backup
    └── README.md

---

Quick start

1. New deployment: Follow docs/DEPLOY-NEW-PROXMOX.md — covers Proxmox host prep, LXC creation, host scripts, network boot, and portal file sync.
2. Full setup reference: docs/EMMC-PROVISIONING-GUIDE.md for golden image creation, cloud-init, PiShrink.
3. Redeploy / update: Re-run scripts/deploy-to-proxmox.sh root@HOST — updates scripts, dashboard, udev, and systemd without touching your golden image or enabled flag.
4. Sync portal files: After deploy or when kiosk/first-boot assets change: scripts/sync-portal-files-to-lxc.sh root@<LXC-IP>.
5. Troubleshooting: docs/PROXMOX-LXC-DEPLOYMENT.md for USB errors, rpiboot failures, and monitoring. docs/NETWORK-BOOT-TROUBLESHOOTING.md for network boot issues.