mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-10-04 14:25:08 +00:00

Files

T

ChuckandClaude Opus 5 12f3790994 fix(install): render the systemd units from their templates, not from heredocs (#547 )

* fix(install): render the systemd units from their templates, not from heredocs

The installers carried their own inline copies of units that also exist as
templates under systemd/, and the copies drifted.

install_service.sh renders ledmatrix.service from the template correctly, then
wrote ledmatrix-web.service from a heredoc that predated it -- missing
Wants=network-online.target, RestartSec=10, SyslogIdentifier, CacheDirectory,
CacheDirectoryMode and Environment=USE_THREADING=1. install_web_service.sh had
a third copy, and install_wifi_monitor.sh a fourth, that one already differing
from its template (syslog where the template says journal).

startup_validator.py compares the installed unit against the template, so a
rig installed this way warned on every boot -- and the remedy the warning
names, "re-run scripts/install/install_service.sh", reinstalled the same stale
copy. The warning could never clear. Reproduced on a live rig running exactly
that unit.

All three installers now render systemd/*.service through the same placeholder
substitution. The template gains a __USER__ placeholder rather than hardcoding
User=root, because the web interface runs as whoever installed it.

That last point was a second, independent cause of a permanent warning: the
validator substituted a fixed "root", so any non-root install reported drift
forever. It now reads User= from the installed unit -- an install-time
decision, not something the template dictates -- and compares everything else
strictly. first_time_install.sh already reads the installed User= the same way.

Tests cover a non-root web unit not warning, a genuinely changed directive in
that unit still warning, the User= fallback, and a grep-based guard that no
installer under scripts/install/ contains an inline unit body. That guard is
what found the install_wifi_monitor.sh copy.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014RRtqXDCnvnY6EQwhT5CV9

* fix(install): escape sed replacements, use mktemp, and make render failures fatal

Address CodeRabbit findings on install_service.sh, install_web_service.sh and
install_wifi_monitor.sh:

- Values interpolated into each script's sed expression (project root path,
  username) were not escaped, so a value containing &, \ or the | delimiter
  would corrupt the rendered systemd unit. Add a shared
  sed_escape_replacement() helper in the new scripts/install/lib_systemd_render.sh
  (sourced by all three scripts) and apply it to every sed replacement.
- install_service.sh rendered the main and web units to the predictable path
  /tmp/ledmatrix.service.tmp before installing them -- a symlink/TOCTOU race
  (CWE-377). Use mktemp for both, with a trap to clean up on exit.
- install_service.sh treated a missing template as a mere warning and then
  checked only whether a unit already existed at the destination before
  enabling/starting it, so a render failure could silently fall back to
  enabling a stale, previously-installed unit. Both unit blocks now exit
  non-zero on a missing template or a failed render.

Also rename the ambiguous loop variable `l` to `line` in
test/test_systemd_unit_drift.py (Ruff E741); ruff isn't wired into any CI
workflow in this repo today, so this isn't currently CI-blocking, but the
rename is trivial and correct regardless.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S3bPMESe2TfrGvbs1ef9c5

* test(install): cover sed_escape_replacement against sed-special characters

CodeRabbit asked for regression coverage using a project path containing an
ampersand; the earlier commits on this branch already fixed the escaping,
mktemp usage, and enable/start-on-fatal-render-failure findings, and the
l->line rename was already applied -- this closes the one remaining gap.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-09-11 08:41:19 -04:00

ledmatrix-dns-fix.service

feat(starlark,on-demand): the third-party fixes worth taking, plus a Home Assistant MQTT bridge (#538 )

2026-09-08 08:34:52 -04:00

ledmatrix-mqtt-bridge.service

feat(starlark,on-demand): the third-party fixes worth taking, plus a Home Assistant MQTT bridge (#538 )

2026-09-08 08:34:52 -04:00

ledmatrix-web.service

fix(install): render the systemd units from their templates, not from heredocs (#547 )

2026-09-11 08:41:19 -04:00

ledmatrix-wifi-monitor.service

fix: keep low-memory boards reachable under load (#464 )

2026-08-19 12:28:22 -04:00

ledmatrix.service

harden: cap malloc arenas, warn on unit drift, and grant the portal's sudo commands (#476 )

2026-08-21 14:29:45 -04:00

README.md

feat(starlark,on-demand): the third-party fixes worth taking, plus a Home Assistant MQTT bridge (#538 )

2026-09-08 08:34:52 -04:00

README.md

Systemd Service Files

This directory contains systemd service unit files for LEDMatrix services.

Service Files

ledmatrix.service - Main LED Matrix display service
- Runs the display controller (run.py)
- Starts automatically on boot
- Runs as root for hardware access
ledmatrix-web.service - Web interface service
- Runs the web interface conditionally based on config
- Starts automatically on boot if web_display_autostart is enabled
- Uses scripts/utils/start_web_conditionally.py
ledmatrix-wifi-monitor.service - WiFi monitor daemon service
- Monitors WiFi/Ethernet connectivity
- Automatically enables/disables access point mode
- Uses scripts/utils/wifi_monitor_daemon.py
ledmatrix-dns-fix.service - DNS single-request fix (optional)
- Re-applies options single-request to the resolver on every boot, because whatever manages resolv.conf regenerates it and drops the option again
- Works around glibc's parallel A/AAAA lookup stalling ~5s per name on routers that answer only the A query, which makes any plugin calling an external API slow or (for Starlark apps, which have a render timeout) fail outright
- Uses scripts/utils/apply_dns_single_request.sh
- Install only if external API calls are timing out; it is not part of a normal install
ledmatrix-mqtt-bridge.service - Home Assistant MQTT bridge (optional)
- Exposes the display to Home Assistant over MQTT Discovery: force a mode, stop on-demand, toggle power, set brightness
- Uses integrations/mqtt_bridge/ledmatrix_mqtt_bridge.py, which drives the web API rather than the display directly
- Needs integrations/mqtt_bridge/bridge_config.json; see that directory's README

Installation

These service files are installed by the installation scripts in scripts/install/:

install_service.sh installs ledmatrix.service
install_web_service.sh installs ledmatrix-web.service
install_wifi_monitor.sh installs ledmatrix-wifi-monitor.service
install_dns_fix.sh installs ledmatrix-dns-fix.service (opt-in, not run by the normal installer)
install_mqtt_bridge.sh installs ledmatrix-mqtt-bridge.service (opt-in)

Manual Installation

Important: the unit files in this directory contain __PROJECT_ROOT_DIR__ placeholders that the install scripts replace with the actual project directory at install time. Do not copy them directly to /etc/systemd/system/ — the service will fail to start with WorkingDirectory=__PROJECT_ROOT_DIR__ errors.

Always install via the helper script:
sudo ./scripts/install/install_service.sh
If you really need to do it by hand, substitute the placeholder first:
PROJECT_ROOT="$(pwd)"
sed "s|__PROJECT_ROOT_DIR__|$PROJECT_ROOT|g" systemd/ledmatrix.service \
  | sudo tee /etc/systemd/system/ledmatrix.service > /dev/null
sudo systemctl daemon-reload
sudo systemctl enable ledmatrix.service
sudo systemctl start ledmatrix.service

Service Management

# Check status
sudo systemctl status ledmatrix.service

# Start/stop/restart
sudo systemctl start ledmatrix.service
sudo systemctl stop ledmatrix.service
sudo systemctl restart ledmatrix.service

# Enable/disable autostart
sudo systemctl enable ledmatrix.service
sudo systemctl disable ledmatrix.service

# View logs
journalctl -u ledmatrix.service -f