mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-08-01 16:58:06 +00:00

Files

T

ChuckBuildsandClaude Sonnet 5 8de706323a fix: install plugin/base requirements as root so ledmatrix.service can see them

ledmatrix-web.service runs as a non-root user, so "Reinstall plugin
requirements" installed packages into that user's ~/.local site-packages.
ledmatrix.service (the actual display, which loads and runs plugin code)
runs as root and can't see another user's user-site packages, so plugins
with dependencies not already present system-wide would silently fail at
runtime with ModuleNotFoundError even after a "successful" reinstall.
Reproduced and fixed live against a real device (weather plugin's astral
dependency, used for moon-phase data): confirmed the exact failure
("No module named 'astral'" on every almanac cycle) and confirmed it's
gone after this fix.

Adds scripts/fix_perms/safe_pip_install.sh, a root-owned wrapper (mirroring
the existing safe_plugin_rm.sh pattern) that validates the target is
requirements.txt at the project root or under plugin-repos/ or plugins/
before running pip install as root. configure_web_sudo.sh provisions a
narrowly-scoped sudoers rule for it. api_v3.py's install_base_requirements
and install_plugin_requirements actions now use it via `sudo -n`, falling
back to today's current-user-only install (with an explanatory note) if
the wrapper isn't set up yet, so existing installs don't regress.

Also uses --ignore-installed in the wrapper: root's site-packages often has
apt/dpkg-managed copies of common libraries (requests, etc.) with no pip
RECORD file, which pip refuses to upgrade in place and aborts the *entire*
requirements.txt install over — discovered this while testing the fix live,
since a plugin's other already-satisfied-for-the-web-user dependencies had
never actually been attempted as root before.

Also fixes a pre-existing bug in configure_web_sudo.sh where the
display_controller.py/start_display.sh/stop_display.sh sudoers entries used
PROJECT_DIR (scripts/install/, where this script lives) instead of
PROJECT_ROOT (where those files actually live) — visible as the script's
own "File access test" self-check failing. Verified fixed live.

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

2026-07-04 09:46:47 -04:00

fix_assets_permissions.sh

fix: Codacy security fixes, CVE dependency bumps, and code quality cleanup (#331 )

2026-05-15 10:19:55 -04:00

fix_cache_permissions.sh

Plugins (#145 )

2025-12-27 14:15:49 -05:00

fix_nhl_cache.sh

Plugins (#145 )

2025-12-27 14:15:49 -05:00

fix_plugin_permissions.sh

Plugins (#145 )

2025-12-27 14:15:49 -05:00

fix_web_permissions.sh

Plugins (#145 )

2025-12-27 14:15:49 -05:00

README.md

docs: refresh and correct stale documentation across repo (#306 )

2026-04-07 21:04:25 -04:00

safe_pip_install.sh

fix: install plugin/base requirements as root so ledmatrix.service can see them

2026-07-04 09:46:47 -04:00

safe_plugin_rm.sh

fix(plugins): prevent root-owned files from blocking plugin updates (#242 )

2026-02-12 19:28:05 -05:00

README.md

Permission Fix Scripts

This directory contains shell scripts for repairing file/directory permissions on a LEDMatrix installation. They're typically only needed when something has gone wrong — for example, after running parts of the install as the wrong user, after a manual file copy that didn't preserve ownership, or after a permissions-related error from the display or web service.

Most of these scripts require sudo since they touch directories owned by the ledmatrix service user or by root.

Scripts

fix_assets_permissions.sh — Fixes ownership and write permissions on the assets/ tree so plugins can download and cache team logos, fonts, and other static content.
fix_cache_permissions.sh — Fixes permissions on every cache directory the project may use (/var/cache/ledmatrix/, ~/.cache/ledmatrix/, /opt/ledmatrix/cache/, project-local cache/). Also creates placeholder logo subdirectories used by the sports plugins.
fix_plugin_permissions.sh — Fixes ownership on the plugins directory so both the root display service and the web service user can read and write plugin files (manifests, configs, requirements installs).
fix_web_permissions.sh — Fixes permissions on log files, systemd journal access, and the sudoers entries the web interface needs to control the display service.
fix_nhl_cache.sh — Targeted fix for NHL plugin cache issues (clears the NHL cache and restarts the display service).
safe_plugin_rm.sh — Validates that a plugin removal path is inside an allowed base directory before deleting it. Used by the web interface (via sudo) when a user clicks Uninstall on a plugin — prevents path-traversal abuse from the web UI.

When to use these

Most users never need to run these directly. The first-time installer (first_time_install.sh) sets up permissions correctly, and the web interface manages plugin install/uninstall through the sudoers entries the installer creates.

Run these scripts only when:

You see "Permission denied" errors in journalctl -u ledmatrix or the web UI Logs tab.
You manually copied files into the project directory as the wrong user.
You restored from a backup that didn't preserve ownership.
You moved the LEDMatrix directory and need to re-anchor permissions.

Usage

# Run from the project root
sudo ./scripts/fix_perms/fix_cache_permissions.sh
sudo ./scripts/fix_perms/fix_assets_permissions.sh
sudo ./scripts/fix_perms/fix_plugin_permissions.sh
sudo ./scripts/fix_perms/fix_web_permissions.sh

If you're not sure which one you need, run fix_cache_permissions.sh first — it's the most commonly needed and creates several directories the other scripts assume exist.