8233304ee2
<message>Enhance the README files to provide clearer instructions for deploying the CM4 eMMC provisioning service on Proxmox, including detailed prerequisites and deployment steps. Update the .gitignore to exclude deploy logs generated during the deployment process, ensuring a cleaner repository. Additionally, refine archived documentation for better historical context and clarity on the active provisioning workflow.
70 lines
4.7 KiB
Markdown
70 lines
4.7 KiB
Markdown
<!-- Revision: 2 -->
|
||
# 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](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](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](docs/PROXMOX-LXC-DEPLOYMENT.md) for USB errors, rpiboot failures, and monitoring. [docs/NETWORK-BOOT-TROUBLESHOOTING.md](docs/NETWORK-BOOT-TROUBLESHOOTING.md) for network boot issues.
|