Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

31 Commits

Folders and files

Repository files navigation

nirj-agent

Device management agent for Northern Ireland Raspberry Jam devices.

Persistent layout

Production state lives on a persistent filesystem mounted at /data, outside the root OverlayFS:

/data/nirj/
├── agent-repo/
├── agent-venv/
├── run.sh
├── config/config.yaml
├── state/
│   ├── state.yaml
│   ├── update.json
│   ├── current-manifest.json
│   └── target-manifest.json
├── logs/
└── cache/

install.sh refuses to install unless /data is already a mount point. Disk partitioning is intentionally a separate image/provisioning responsibility; guessing a block device in a curl | bash installer risks destroying data.

Bootstrap

The production copy of install.sh belongs in nirj-infra; the copy in this repository is the implementation template. Run it as root with the device identity:

curl -fsSL \
  https://raw.githubusercontent.com/NIRaspberryJam/nirj-infra/main/install.sh \
  | sudo bash -s -- --asset-id PI5-001 --device-type pi5

The installer installs prerequisites, clones nirj-agent, creates its venv, writes the stable /data/nirj/run.sh, creates the global CLI symlink, and enables the root-owned systemd service. Existing device configuration is preserved.

At each service start, run.sh fast-forwards the agent checkout, updates the venv, runs nirj-agent boot-prep, then starts the idle long-running process with nirj-agent up. Exit code 194 means boot preparation requested a reboot; the runner exits cleanly instead of starting the daemon during shutdown.

Update and OverlayFS flow

boot-prep downloads and validates the target manifest. If it differs from the current applied manifest while / is an overlay, the agent records pending_update, changes the generated wallpaper state, disables OverlayFS, syncs, and reboots. On the writable boot it records applying_update, applies the manifest, promotes the target manifest to current, restores OverlayFS, and reboots. Failures persist as failed with an error in update.json.

Overlay activity is determined from findmnt -n -o FSTYPE /; configuration changes use Raspberry Pi OS's raspi-config nonint interface and always require a reboot. overlay disable creates /data/nirj/state/overlay-disabled-once, which makes the next boot-prep skip OverlayFS manifest enforcement. The flag is consumed on that boot, so a later boot restores the manifest's configured OverlayFS state. When enabling OverlayFS, the agent enforces overlayroot=tmpfs:recurse=0 so separately mounted filesystems such as /data remain writable and persistent. Before disabling it, the agent temporarily normalizes the setting to overlayroot=tmpfs for compatibility with raspi-config.

Useful commands:

nirj-agent status
nirj-agent update check
sudo nirj-agent update apply
sudo nirj-agent boot-prep

nirj-agent overlay status
sudo nirj-agent overlay enable
sudo nirj-agent overlay disable

nirj-agent config get device.asset_id
sudo nirj-agent config set overlay.enabled true
sudo nirj-agent set-config asset-id PI5-002

status, update check, and config get do not mutate persistent state. System changes and configuration writes require root. set-config provides operator-friendly field names such as asset-id, while config set accepts the underlying dotted configuration key. update check downloads and validates in memory; root-owned boot/update commands persist the target.

The current schema applies APT package state and carries OverlayFS/background flags. When background.enabled is true, boot-prep renders the current state and device asset code over the installed base image. An XDG autostart watcher applies /data/nirj/cache/generated/wallpaper.png from inside the logged-in desktop session. boot-prep also reconciles the base image and autostart entry; when OverlayFS is active, it requests a writable reboot before persisting those files and then restores the configured overlay state. Raspberry Pi Desktop/PCManFM, XFCE, and GNOME are supported.

Python packages are installed into /data/nirj/python-venv. Package versions must be exact. Packages are installed from PyPI as wheels; direct URLs, Git repositories, editable installs, and arbitrary pip options are not accepted.

Once that environment exists, the agent configures the existing /home/jam account to use it in Bash and desktop login sessions, and sets VS Code's python.defaultInterpreterPath to /data/nirj/python-venv/bin/python. Log out and back in after the first application to pick up the session PATH. The Python extension must be installed in VS Code; workspaces with an already selected interpreter may need Python: Select Interpreter once. Explicitly activated virtual environments take precedence in new shells. System Python at /usr/bin/python3 is unchanged. Existing shell configuration, VS Code settings (including comments), and file ownership are preserved.

Package operation failures are logged and recorded in the agent state's errors list. Independent APT/Python operations continue, and shortcuts are only created for applications confirmed installed. A partial update leaves ready: false and does not promote the target manifest to current. The agent still starts, with the root left writable if an update required disabling OverlayFS. Retry with nirj-agent update apply or restart the service after fixing the package/repository issue; there is no periodic retry loop. Explicit apply commands return a failure exit status for partial updates.

APT installs block dependency removals by default. To permit replacements when installing specific packages, list them in apt.allow_dependency_removals:

apt:
  packages: [sonic-pi, pipewire-jack]
  allow_dependency_removals: [pipewire-jack]

Every allowlisted package must also appear in apt.packages. Ordinary packages are installed with --no-remove; allowlisted packages are installed separately, one at a time, without that restriction. This permits any removal APT requires for that installation, rather than allowing removal of specific dependency names. It is independent of apt.enforce, which governs previously managed packages omitted from the manifest. The permission is used only when a package needs installation; it does not trigger upgrades of already-installed packages.

The manifest can also place agent-managed application launchers on the jam user's desktop. Each shortcut must include its corresponding APT package:

schema: 1
apt:
  packages:
    - code
    - python3-venv
    - sonic-pi
    - pipewire-jack
python:
  packages:
    jamkit: "0.1.0"
desktop:
  shortcuts:
    - vscode
    - sonic-pi

Sonic Pi shortcuts require both sonic-pi and pipewire-jack. The agent launches Sonic Pi through pw-jack from the desktop shortcut and a managed /usr/local/share/applications/sonic-pi.desktop menu override. Audio uses the desktop session; no HDMI or USB device names are configured. HDMI playback has been verified on one Pi; USB playback and live output switching still require device testing. Removing the shortcut also removes the menu override.

The agent also sets [config] quick_exec=1 in /home/jam/.config/libfm/libfm.conf, preserving other preferences. This makes PCManFM launch desktop shortcuts directly without the Execute dialog. It also applies to other executable files opened in PCManFM. The setting is persisted through the normal writable-boot setup; log out and back in if the running desktop has not picked it up. This does not change single/double-click behaviour.

Classroom VS Code profile

Reference a separately hosted YAML profile from the Pi manifest:

vscode:
  config_url: https://raw.githubusercontent.com/NIRaspberryJam/nirj-infra/main/configs/vscode.yaml

This requires code in apt.packages. Profiles use schema 1 and accept folder (a normalized path beneath /home/jam), extensions (publisher.extension IDs), disabled_extensions, settings (VS Code user settings), and runtime (password-store: basic or gnome-libsecret). The infrastructure example configures /home/jam/jam-day, Python and Python Debugger, disables built-in AI, welcome walkthroughs and GitHub Git authentication, and disables GitHub/Microsoft account providers and Copilot in managed desktop/menu launches.

Downloads require HTTPS, have a timeout and a 256 KiB limit, and are validated before replacing the target. The downloaded profile is embedded in the cached manifest snapshot. Its contents participate in the update hash, so changing the profile at the same URL triggers the normal writable-update flow. Pending updates use that snapshot across reboots. Publish the profile URL before deploying a manifest that references it. Windows manifests reject this Linux-only setting.

The agent merges settings into /home/jam/.config/Code/User/settings.json and runtime arguments into /home/jam/.vscode/argv.json, preserving unrelated values, JSON comments, symlinks, permissions and ownership. The existing managed Python interpreter is retained. Removed profile settings are not automatically erased. Required extensions are installed and verified as the home-directory owner, without optional extension-pack/dependency additions; existing extensions are not removed. Already installed extensions are retained rather than updated on every boot. Marketplace failures leave the update incomplete for retry.

Both the desktop shortcut and managed code.desktop menu override open the profile's folder in a new window, using /usr/share/pixmaps/vscode.png for the logo. jam-day is created if missing and existing work is never deleted by setup. Its session changes reset with root OverlayFS on reboot; it is not stored in /data. A workspace-trust prompt may still need acknowledgement on first use. The basic password store avoids VS Code keyring prompts but does not protect stored credentials with the OS keyring. Other applications' keyring prompts are unaffected. Verify login prompts and Python debugging on a Pi before rollout.

Desktop setup also sets show_mounts=0 in existing PCManFM monitor profiles and seeds both Pi HDMI profiles. All mounted-drive desktop icons are hidden, including USB sticks; mounted drives remain accessible through the file manager.

Development

python3 -m venv venv
source venv/bin/activate
python -m pip install -e '.[dev]'
python -m pytest -q

Read-only and setup commands can use --root to target a sandbox that mirrors the production /data/nirj layout:

nirj-agent --root .sandbox setup --asset-id TEST-001 --device-type pi5
nirj-agent --root .sandbox status
nirj-agent --root .sandbox config get device.asset_id
nirj-agent --root .sandbox manifest refresh
nirj-agent --root .sandbox plan

Commands that invoke APT, OverlayFS, reboot, or production configuration writes reject --root because those effects cannot be filesystem-sandboxed.

Inspect production operation with:

sudo systemctl status nirj-agent.service
sudo journalctl -u nirj-agent.service -f

Windows bootstrap

Native Windows installations use C:\ProgramData\nirj by default and run scripts/run-agent.ps1 as a startup Scheduled Task. The runner fast-forwards the configured branch, updates the virtual environment, and starts nirj-agent up. It intentionally does not run boot-prep, because APT, OverlayFS, and the Linux desktop setup are not applicable on Windows. At startup, the agent downloads and validates the Windows manifest, promotes it to the current manifest, and reports ready: true. Linux-only manifest settings are rejected instead of being ignored.

Run the production install.ps1 from nirj-infra in an elevated PowerShell session:

$installer = Join-Path $env:TEMP "install-nirj-agent.ps1"
irm `
  "https://raw.githubusercontent.com/NIRaspberryJam/nirj-infra/main/nirj-agent/install.ps1" `
  -OutFile $installer
& $installer -AssetId "WIN-001"

This bootstrap installs and starts the agent but does not yet reconcile Windows software. Windows package management requires a separate Winget manifest section and provider.

Inspect the task and follow its log with:

Get-ScheduledTask -TaskName "nirj-agent"
Get-Content "C:\ProgramData\nirj\logs\agent.log" -Wait

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages