feat(lxc): git-native LXC templates — in-place updates, bundled updater, doc overhaul#3768
feat(lxc): git-native LXC templates — in-place updates, bundled updater, doc overhaul#3768BeerMan81 wants to merge 11 commits into
Conversation
Documents the sparse-cone.txt maintenance obligation, chroot build requirement, PUPPETEER_SKIP_DOWNLOAD, and intentional .git retention so Claude Code follows the correct conventions when working on the LXC template.
Replace the artifact-copy approach with a partial+sparse git clone directly into the container rootfs. The resulting template is git-native from first boot, allowing meshmonitor-update to manage future in-place updates without a migration step. Adds lxc/sparse-cone.txt to control which directories are materialized. Fixes PUPPETEER_SKIP_DOWNLOAD omission that would cause npm install to hang in headless containers. Pins to the exact release tag at clone time via --branch rather than a post-clone checkout.
Add lxc/meshmonitor-update — the in-place git-pull updater — to the repo so it ships inside every deployed container via the sparse-checkout cone (lxc/ is already in sparse-cone.txt). Add /usr/local/bin to PATH in /etc/environment so the self-install feature works correctly on the minimal Debian template, which omits /usr/local/bin from the default PATH.
…template - README: update Node 22->24, fix port 8080->3001, add meshmonitor-update and sparse-cone.txt to directory structure, update build description to reflect git clone approach, add in-place update section, remove references to non-existent test script - post-install.sh: rewrite as lean first-boot setup — auto-detects container IP, populates meshmonitor.env from example, sets ALLOWED_ORIGINS, adds /usr/local/bin to PATH, prints welcome summary with web UI URL - meshmonitor.conf: fix port 8080->3001, swap 512->1024 (npm build headroom), nesting=0->1 (required for systemd), comment out storage name placeholder
…t baked into template
build-lxc-template.sh now clones the repo and builds entirely inside the container chroot — setup-node, npm install, npm run build, and npm run build:server on the CI runner are redundant and wasted ~3min per release build. Also adds git and curl to the debootstrap install step which the build script now requires.
- Remove MESHTASTIC_NODE_IP references (configured via web UI since v4.0) - Replace 2.19.x version examples with <version> placeholder - Fix port 8080 -> 3001 (LXC has no Docker port mapping layer) - Fix swap 512 -> 1024 (npm build headroom) - Fix nesting=0 -> nesting=1 (required for systemd) - Remove local-lxc hardcoded storage name - Rewrite Step 4 to use post-install.sh instead of manual env editing - Rewrite Updating section: meshmonitor-update as primary in-place method - Update Limitations: in-place upgrade now supported via meshmonitor-update - Add troubleshooting entry for meshmonitor-update PATH issue
Note on CI workflow changes (
|
================================================
|
1 participant
Summary
LXC templates currently ship as pre-built artifacts with no
.gitdirectory.This means
meshmonitor-update— which requires a git clone — cannot run on afreshly-deployed container without a separate migration step. This PR fixes the
problem at its source:
build-lxc-template.shnow clones the MeshMonitor repodirectly into the container using a partial+sparse git clone (~8MB overhead),
so every deployed container is git-native from first boot and
meshmonitor-updateworks immediately. It also bundles
meshmonitor-updateinlxc/so it shipsinside every container, and overhauls the LXC documentation to reflect actual
current behaviour (port 3001 not 8080, Node 24 not 22, web-UI node config since
v4.0, in-place update path, correct container settings).
Changes
Build
lxc/build-lxc-template.sh— replaces artifact-copy approach withgit clone --depth 1 --filter=blob:none --sparseinto the container rootfs;all npm build steps now run inside the container chroot against the container's
own Node.js 24 (NodeSource), ensuring native modules compile for the correct ABI
lxc/sparse-cone.txt— new file controlling which top-level directories arematerialized in the container (
src,public,docker,scripts,lxc);decouples the cone list from the build script so it can be maintained independently
lxc/build-lxc-template.sh— addssudoto base system install (required bymeshmonitor-update'ssudo -u meshmonitor gitinvocation)lxc/build-lxc-template.sh— removes hardcodedMESHTASTIC_NODE_IPfrommeshmonitor.env.example(node connection configured via web UI since v4.0)lxc/build-lxc-template.sh— adds/usr/local/binto/etc/environment(missing from minimal Debian's default PATH; required after
meshmonitor-updateself-installs)
CI
.github/workflows/lxc-template-build.yml— removessetup-node,npm install,npm run build,npm run build:serversteps that are nowredundant (build script handles all of this inside the chroot); adds
gitandcurlto the debootstrap install stepmeshmonitor-update bundled
lxc/meshmonitor-update— the in-place updater now lives in the repo andships inside every deployed container via the
lxc/sparse cone; on first runit self-installs to
/usr/local/bin/Documentation
lxc/README.md— Node 22→24, port 8080→3001, updated directory structure,in-place update instructions, build prerequisites, correct build description
lxc/proxmox/post-install.sh— rewritten: auto-detects container IP, setsALLOWED_ORIGINSinmeshmonitor.env, populates env from example file,adds
/usr/local/binto PATH, prints web UI URL and first-run instructionslxc/proxmox/meshmonitor.conf— swap 512→1024 (npm build headroom duringupdates),
nesting=0→nesting=1(required for systemd), storage namecommented out with operator note
docs/deployment/PROXMOX_LXC_GUIDE.md— comprehensive update: removedMESHTASTIC_NODE_IPenv references (web UI since v4.0), corrected versionexamples, fixed port 8080→3001, swap and nesting values, rewrote Step 4 to
use
post-install.sh, addedmeshmonitor-updateas primary update path,updated Limitations to reflect in-place upgrades now supported, added
meshmonitor-updatePATH troubleshooting entryCLAUDE.md— added LXC Template Build section with sparse-cone maintenancerule, chroot build requirement,
PUPPETEER_SKIP_DOWNLOAD, and intentional.gitretention noteIssues Resolved
Relates to the community discussion at
#3572 where a user reported
meshmonitor-updatefailing on a freshly-deployed LXC template with "Cannotfind MeshMonitor source tree (requires git clone, not a pre-built template)".
Documentation Updates
lxc/README.md— updated (see Changes)lxc/proxmox/post-install.sh— rewritten (see Changes)lxc/proxmox/meshmonitor.conf— updated (see Changes)docs/deployment/PROXMOX_LXC_GUIDE.md— updated (see Changes)CLAUDE.md— LXC build rules addedTesting
Build:
lxc/build-lxc-template.shrun on a Debian 12 VM with NVMe storage.Completed in ~3 minutes with no errors across all 14 steps.
Deployment: Fresh LXC container (CT 310, Debian 12, 2GB RAM, unprivileged)
deployed from the built template. First-boot test sequence:
meshmonitor-update --dry-runpasses on first boot with no migration step..tsfiles changed).gitpresent in deployed container from first bootmeshmonitor-updateself-installs and detects install dir correctlypost-install.shauto-detects IP and setsALLOWED_ORIGINSFor existing containers (pre-v4.12.0 templates):
migrate-to-git.shhandles the one-time migration from pre-built artifact to git-native install.
Documented in
docs/deployment/PROXMOX_LXC_GUIDE.mdLimitations section.