From 762c8459cc5f3be4be3f361c623513d555b2a9d4 Mon Sep 17 00:00:00 2001 From: Tony Murray Date: Sun, 15 Nov 2026 09:02:44 -0600 Subject: [PATCH] Persist added Composer packages in /data Keep the packages added with lnms plugin:add in /data/composer/composer.plugins.json (LIBRENMS_COMPOSER_PLUGINS) and install them with lnms plugin:sync next to a copy of the image's dependencies in /data/composer/build. Containers use that build at startup, or the image's vendor when nothing was added. It is recreated when the list or the image's dependencies change, and startup falls back to the image's packages if that fails. The image's composer.json, composer.lock and vendor are root owned and never modified, so no ownership changes are needed in /opt/librenms. --- .github/workflows/test.yml | 46 ++++++ Dockerfile | 9 ++ README.md | 45 ++++++ rootfs/etc/s6-overlay/scripts/config | 18 ++- rootfs/etc/s6-overlay/scripts/fix-perms | 1 - rootfs/usr/bin/lnms | 6 + rootfs/usr/local/bin/artisan | 6 + rootfs/usr/local/bin/librenms-composer | 195 ++++++++++++++++++++++++ 8 files changed, 322 insertions(+), 4 deletions(-) create mode 100755 rootfs/usr/local/bin/librenms-composer diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 62c49cbd..42c50c8b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -84,6 +84,52 @@ jobs: env: LIBRENMS_IMAGE: ${{ env.BUILD_TAG }} LIBRENMS_CONTAINER: ${{ env.CONTAINER_NAME }} + - + name: Check Composer packages + run: | + set -euo pipefail + services=(librenms dispatcher syslogng snmptrapd) + package=socialiteproviders/saml2 + probe='require "/opt/librenms/vendor/autoload.php"; exit(class_exists("SocialiteProviders\\Saml2\\Provider") ? 0 : 1);' + loaded() { + for service in "${services[@]}"; do + timeout 180 bash -c 'until docker compose exec -T -u librenms "$1" php -r "$2" 2>/dev/null; do sleep 2; done' _ "$service" "$probe" + done + } + build() { + docker compose exec -T librenms stat -c %i /data/composer/build + } + + docker compose exec -T librenms lnms plugin:add "$package" + if docker compose exec -T librenms lnms plugin:add "$package" 0.0.0; then + echo "Composer accepted an unavailable version" + exit 1 + fi + # the image is left untouched + docker compose exec -T librenms sh -ec '! grep -q "$1" composer.json composer.lock && test ! -e "vendor-image/$1"' _ "$package" + + # packages survive container replacement without being installed again + before=$(build) + docker compose up -d --no-deps --force-recreate "${services[@]}" + loaded + test "$(build)" = "$before" + + # packages are installed again when the image changes + docker compose exec -T librenms sh -c "echo other-image > /data/composer/build/stamp" + docker compose restart "${services[@]}" + loaded + test "$(build)" != "$before" + + docker compose exec -T librenms lnms plugin:remove "$package" + docker compose restart "${services[@]}" + for service in "${services[@]}"; do + timeout 180 bash -c 'until [ "$(docker compose exec -T "$1" readlink /opt/librenms/vendor 2>/dev/null)" = vendor-image ]; do sleep 2; done' _ "$service" + done + docker compose exec -T librenms curl -sS -o /dev/null --fail --retry 5 --retry-connrefused http://127.0.0.1:8000/login + working-directory: test + env: + LIBRENMS_IMAGE: ${{ env.BUILD_TAG }} + LIBRENMS_CONTAINER: ${{ env.CONTAINER_NAME }} - name: Logs if: always() diff --git a/Dockerfile b/Dockerfile index 871dff5f..f2758052 100644 --- a/Dockerfile +++ b/Dockerfile @@ -108,6 +108,7 @@ ENV S6_BEHAVIOUR_IF_STAGE2_FAILS="2" \ S6_STAGE2_HOOK="/etc/s6-overlay/scripts/runtime-bundles" \ LIBRENMS_PATH="/opt/librenms" \ LIBRENMS_DOCKER="1" \ + LIBRENMS_COMPOSER_PLUGINS="/data/composer/composer.plugins.json" \ TZ="UTC" \ PUID="1000" \ PGID="1000" @@ -136,6 +137,14 @@ RUN apk --update --no-cache add -t build-dependencies \ && echo "foreach (glob(\"${LIBRENMS_PATH}/config.d/*.php\") as \$filename) include \$filename;" >> config.php \ && chown -R librenms:librenms ${LIBRENMS_PATH} \ && su librenms -s /bin/sh -c "COMPOSER_CACHE_DIR=/tmp composer install --no-dev --no-interaction --no-ansi" \ + && mv vendor vendor-image \ + && ln -s vendor-image vendor \ + && ln -s /usr/bin/composer composer.phar \ + && touch -d 2100-01-01 /usr/bin/composer \ + && chown root:root . composer.json composer.lock \ + && chown -R root:root vendor-image \ + && chmod go-w . composer.json composer.lock \ + && chmod -R go-w vendor-image \ && apk del build-dependencies \ && rm -rf .git \ html/plugins/Test \ diff --git a/README.md b/README.md index a3162ee9..819e3853 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,7 @@ ___ * [Syslog-ng container](#syslog-ng-container) * [Snmptrapd container](#snmptrapd-container) * [Add a LibreNMS plugin](#add-a-librenms-plugin) + * [Add a Composer package](#add-a-composer-package) * [Additional Monitoring plugins](#additional-monitoring-plugins) * [Custom alert templates](#custom-alert-templates) * [Contributing](#contributing) @@ -404,6 +405,50 @@ will be removed and yours will be used. > [!WARNING] > Container has to be restarted to propagate changes. +### Add a Composer package + +For example, install the Socialite SAML provider and restart the LibreNMS services. + +```console +$ docker compose exec librenms lnms plugin:add socialiteproviders/saml2 +$ docker compose restart librenms dispatcher syslogng snmptrapd +``` + +Use the service names in your Compose file. Add a version constraint after the +package name if needed. To uninstall, use `plugin:remove` and restart the same +services. + +Only the list of added packages is persisted, in +`/data/composer/composer.plugins.json`. The image's `composer.json`, +`composer.lock` and `vendor` folder are never modified. The added packages are +installed next to a copy of the image's dependencies in `/data/composer/build` +with `lnms plugin:sync`, which is run again when the container starts with a +new image. +Nothing is installed at startup if the list and the image are unchanged. + +> [!NOTE] +> All LibreNMS services must share `/data` and use the same `PUID` and `PGID`. +> Access to the Composer repositories is required after an image upgrade to +> install the packages again. If that fails, LibreNMS starts without them and +> an error is logged, restart the containers to try again. + +You can also provide `/data/composer/composer.plugins.json` yourself, the +packages it requires are installed when the container starts: + +```json +{ + "require": { + "socialiteproviders/saml2": "^4.8" + } +} +``` + +If you added packages with an older image, copy the list before upgrading: + +```console +$ docker compose exec librenms sh -c 'mkdir -p /data/composer && cp /opt/librenms/composer.plugins.json /data/composer/' +``` + ### Additional Monitoring plugins You can add a custom Monitoring plugin in `/data/monitoring-plugins/`. diff --git a/rootfs/etc/s6-overlay/scripts/config b/rootfs/etc/s6-overlay/scripts/config index f1458afd..8f97eb3b 100755 --- a/rootfs/etc/s6-overlay/scripts/config +++ b/rootfs/etc/s6-overlay/scripts/config @@ -94,7 +94,7 @@ sed -i -e "s/RANDOMSTRINGGOESHERE/${LIBRENMS_SNMP_COMMUNITY}/" /etc/snmp/snmpd.c # Init files and folders echo "Initializing LibreNMS files / folders..." -mkdir -p /data/config /data/logs /data/monitoring-plugins /data/plugins /data/rrd /data/weathermap /data/alert-templates +mkdir -p /data/config /data/logs /data/monitoring-plugins /data/plugins /data/rrd /data/weathermap /data/alert-templates /data/composer if [ -d "${LIBRENMS_PATH}/html/plugins/Weathermap" ]; then if [ -d "${LIBRENMS_PATH}/html/plugins/Weathermap/configs" ] && [ ! -L "${LIBRENMS_PATH}/html/plugins/Weathermap/configs" ]; then @@ -217,8 +217,8 @@ done # Fix perms echo "Fixing perms..." -chown librenms:librenms /data/config /data/monitoring-plugins /data/plugins /data/rrd /data/weathermap /data/alert-templates -find /data/logs ${LIBRENMS_PATH}/composer* ${LIBRENMS_PATH}/config.d ${LIBRENMS_PATH}/bootstrap ${LIBRENMS_PATH}/logs ${LIBRENMS_PATH}/storage ${LIBRENMS_PATH}/vendor \( ! -user librenms -o ! -group librenms \) -exec chown librenms:librenms {} + +chown librenms:librenms /data/config /data/monitoring-plugins /data/plugins /data/rrd /data/weathermap /data/alert-templates /data/composer +find /data/logs ${LIBRENMS_PATH}/config.d ${LIBRENMS_PATH}/bootstrap ${LIBRENMS_PATH}/logs ${LIBRENMS_PATH}/storage \( ! -user librenms -o ! -group librenms \) -exec chown librenms:librenms {} + chmod ug+rw /data/logs /data/rrd ${LIBRENMS_PATH}/bootstrap/cache ${LIBRENMS_PATH}/storage ${LIBRENMS_PATH}/storage/framework/* # Check additional Monitoring plugins @@ -256,3 +256,15 @@ for template in ${templates}; do echo " Adding ${template} alert template" ln -sf /data/alert-templates/${template} ${LIBRENMS_PATH}/resources/views/alerts/templates/${template} done + +# Use the image's Composer packages, or the build in /data/composer when +# packages were added with "lnms plugin:add" +echo "Checking Composer packages..." +if [ -f /data/composer/composer.plugins.json ]; then + chown librenms:librenms /data/composer/composer.plugins.json +fi +if [ "${SIDECAR_DISPATCHER:-0}" != "1" ] && [ "${SIDECAR_SYSLOGNG:-0}" != "1" ] && [ "${SIDECAR_SNMPTRAPD:-0}" != "1" ]; then + librenms-composer activate --prune +else + librenms-composer activate +fi diff --git a/rootfs/etc/s6-overlay/scripts/fix-perms b/rootfs/etc/s6-overlay/scripts/fix-perms index f8fcae0e..941de4ee 100755 --- a/rootfs/etc/s6-overlay/scripts/fix-perms +++ b/rootfs/etc/s6-overlay/scripts/fix-perms @@ -7,7 +7,6 @@ mkdir -p /data \ /var/run/php-fpm chown librenms:librenms \ /data \ - "${LIBRENMS_PATH}" \ "${LIBRENMS_PATH}/.env" \ "${LIBRENMS_PATH}/cache" \ "${LIBRENMS_PATH}/rrd" diff --git a/rootfs/usr/bin/lnms b/rootfs/usr/bin/lnms index 125ed55b..c5d4a0a1 100755 --- a/rootfs/usr/bin/lnms +++ b/rootfs/usr/bin/lnms @@ -1,5 +1,11 @@ #!/usr/bin/env sh +# Composer packages are kept in /data, the image is never modified +case "$1" in + plugin:add) shift; exec librenms-composer add "$@" ;; + plugin:remove) shift; exec librenms-composer remove "$@" ;; +esac + if [ "$(id -u -n)" = "librenms" -a "$(id -g -n)" = "librenms" ]; then php -f /opt/librenms/lnms "$@" else diff --git a/rootfs/usr/local/bin/artisan b/rootfs/usr/local/bin/artisan index 59849ec6..2f329d9d 100755 --- a/rootfs/usr/local/bin/artisan +++ b/rootfs/usr/local/bin/artisan @@ -1,4 +1,10 @@ #!/usr/bin/env sh +# Composer packages are kept in /data, the image is never modified +case "$1" in + plugin:add) shift; exec librenms-composer add "$@" ;; + plugin:remove) shift; exec librenms-composer remove "$@" ;; +esac + cd /opt/librenms || exit 1 gosu librenms:librenms php artisan "$@" diff --git a/rootfs/usr/local/bin/librenms-composer b/rootfs/usr/local/bin/librenms-composer new file mode 100755 index 00000000..739f6631 --- /dev/null +++ b/rootfs/usr/local/bin/librenms-composer @@ -0,0 +1,195 @@ +#!/usr/bin/env bash +# Composer packages added on top of the image (lnms plugin:add / plugin:remove). +# +# Only the list of added packages is persisted as the source of truth, in +# LIBRENMS_COMPOSER_PLUGINS. LibreNMS installs them next to a copy of the +# image's dependencies in /data/composer/build, which is recreated whenever +# the list or the image changes. The image's own files are never modified. +set -euo pipefail + +LIBRENMS_PATH=${LIBRENMS_PATH:-/opt/librenms} +image_vendor=vendor-image +data=/data/composer +list=${LIBRENMS_COMPOSER_PLUGINS:-${data}/composer.plugins.json} +build=${data}/build + +usage() { + cat >&2 < [] + lnms plugin:remove + librenms-composer list +EOL + exit 64 +} + +log() { + echo "$*" >&2 +} + +lock() { + mkdir -p "$data" + exec 9>"${data}/.lock" + flock 9 +} + +# Print the requirements of a package list as "name:constraint" lines. +requirements() { + [ -f "$1" ] || return 0 + php -r ' + $json = json_decode((string) file_get_contents($argv[1]), true); + if (! is_array($json)) { + fwrite(STDERR, "ERROR: $argv[1] is not valid JSON\n"); + exit(1); + } + foreach ($json["require"] ?? [] as $name => $constraint) { + echo "$name:$constraint\n"; + } + ' "$1" +} + +# Identifies what the image contributes to a build. +stamp() { + sha256sum <"${LIBRENMS_PATH}/composer.json" + sha256sum <"${LIBRENMS_PATH}/composer.lock" + php -r 'echo PHP_MAJOR_VERSION, ".", PHP_MINOR_VERSION, "\n";' +} + +# Is the build made from this image and the current package list? +valid() { + [ -f "${build}/vendor/autoload.php" ] && [ -f "${build}/stamp" ] || return 1 + [ "$(<"${build}/stamp")" = "$(stamp)" ] || return 1 + [ "$(requirements "${build}/composer.plugins.json")" = "$(requirements "$list")" ] +} + +# Start a build from the image's packages so only additions are downloaded. +# LibreNMS creates composer.json and composer.lock from the image's. +seed() { + rm -rf "$1" || return 1 + mkdir -p "$1" || return 1 + cp -R "${LIBRENMS_PATH}/${image_vendor}" "$1/vendor" +} + +# Run a LibreNMS plugin command against a build instead of the image. +plugin() { + local dir=$1 + shift + ( + cd "${LIBRENMS_PATH}" || exit 1 + COMPOSER="${dir}/composer.json" COMPOSER_VENDOR_DIR="${dir}/vendor" php lnms "$@" --no-ansi --no-interaction >&2 + ) +} + +record() { + cp "$list" "$1/composer.plugins.json" || return 1 + stamp >"$1/stamp" +} + +# Every step is checked: errexit is off when this runs as a condition. +rebuild() { + seed "${build}.new" || return 1 + plugin "${build}.new" plugin:sync || return 1 + record "${build}.new" || return 1 + rm -rf "$build" || return 1 + mv "${build}.new" "$build" +} + +cmd_change() { + local action=$1 status=0 + shift + lock + + if ! valid; then + if [ -n "$(requirements "$list")" ]; then + rebuild + elif [ "$action" = "remove" ]; then + log "No Composer packages have been added." + return + else + seed "$build" + fi + fi + + plugin "$build" "plugin:${action}" "$@" || status=$? + if [ -n "$(requirements "$list")" ]; then + record "$build" + fi + return "$status" +} + +cmd_list() { + requirements "$list" +} + +# Print the vendor directory to use, installing the packages first if the +# list or the image changed. Falls back to the image's packages rather than +# keeping LibreNMS down when that fails. +cmd_select() { + local vendor=$image_vendor reqs + lock + + if reqs=$(requirements "$list") && [ -n "$reqs" ]; then + if valid; then + vendor="${build}/vendor" + else + log "Installing Composer packages from ${list}..." + if rebuild; then + vendor="${build}/vendor" + else + log "ERROR: Failed to install the Composer packages from ${list}, they are NOT loaded." + fi + fi + elif [ "${1:-}" = "--prune" ]; then + # Sidecars leave it, the main container may still be using it. + rm -rf "$build" + fi + + echo "$vendor" +} + +# Point this container at the selected vendor directory. +cmd_activate() { + local vendor + vendor=$(gosu librenms:librenms "$0" select "$@") || vendor="" + if [ -z "$vendor" ]; then + log "ERROR: Failed to check Composer packages, added packages are NOT loaded" + vendor=$image_vendor + fi + if [ "$(readlink "${LIBRENMS_PATH}/vendor")" != "$vendor" ]; then + if [ "$vendor" != "$image_vendor" ]; then + log "Using Composer packages from ${vendor}" + fi + # Cached package discovery and config belong to the previous packages + rm -f "${LIBRENMS_PATH}"/bootstrap/cache/{packages,services,config,events,routes-v7}.php + ln -sfn "$vendor" "${LIBRENMS_PATH}/vendor" + fi +} + +export COMPOSER_HOME=${COMPOSER_HOME:-/home/librenms/.composer} + +cmd=${1:-} +shift || true +case "$cmd" in + add | remove) + if [ "$(id -u)" != "0" ]; then + log "ERROR: plugin:${cmd} must be run as root" + exit 1 + fi + if [ "$cmd" = "add" ]; then + [ $# -ge 1 ] && [ $# -le 2 ] || usage + else + [ $# -eq 1 ] || usage + fi + status=0 + gosu librenms:librenms "$0" change "$cmd" "$@" || status=$? + cmd_activate + if [ "$status" = "0" ]; then + log "Restart all LibreNMS containers to load the change." + fi + exit "$status" + ;; + activate) cmd_activate "$@" ;; + change) cmd_change "$@" ;; + select) cmd_select "$@" ;; + list) cmd_list ;; + *) usage ;; +esac