Install and maintain host monitoring

Install the optional Linux host collector, verify freshness, and troubleshoot the status page.

Operations task guideUpdated Oct 27, 2026

Scope and prerequisites

Application metrics and host collection are separate. Host monitoring is optional per environment, does not discover machines automatically, and is not long-term monitoring or cluster aggregation. Application history is instance-local in memory and resets on restart.

Work from the application repository root on the deployment host. Confirm Docker context and DOCKER_HOST point to that host and retain the existing deploy/stack.env. The installer requires Linux, systemd, Python 3, and sudo.

Install and check the collector

Confirm the timer is active, the latest service result succeeded, and the snapshot is readable. The service is a oneshot, so inactive after a successful run is normal. Resolve installation failures before enabling integration.

Run on the deployment host
sudo bash deploy/monitor/install.sh
sudo systemctl is-active bosapi-monitor.timer
sudo systemctl show bosapi-monitor.service -p Result -p ExecMainStatus
sudo journalctl -u bosapi-monitor.service -n 30 --no-pager
test -r /var/lib/bosapi-monitor/local.json

Enable application integration

After the snapshot exists, create the local marker. Use up for a new installation or a source upgrade requiring a build; use start for a compatible existing image when only runtime configuration changes. Choose one; the application may be recreated with a brief interruption.

Create the marker
touch deploy/monitor.enabled
New deployment or source upgrade
./deploy/stack.sh up
Compatible existing image, configuration change only
./deploy/stack.sh start
  • Use stack.sh for subsequent operations to retain the monitoring overlay; the base Compose file alone omits it.

Verify and troubleshoot

  • Allow approximately 30–60 seconds, checking for up to 120 seconds. Confirm sampled_at in local.json advances, /app/monitor/local.json is readable in the container, BOS_MONITOR_NODE_DIR=/app/monitor, and stack.sh status reports healthy services.
  • As a super administrator, open System status and check node identity, sampling time, and collection errors. Initial CPU or network rates may be absent until successive samples; snapshots older than 90 seconds are stale.
  • For empty or stale nodes, trace the timer, host JSON, container mount and variable, backend snapshot, and page in order. Working application metrics do not prove host collection is configured.
  • TLS checks require separately configured BOS_MONITOR_TLS_TARGETS; page hints are not durable alerts or external notifications. Verify each instance separately.

Disable and recover

To completely disable a newly enabled integration, remove deploy/monitor.enabled during a change window and run ./deploy/stack.sh start. Only after it succeeds, disable the timer and stop any running service. Confirm application health and removal of the mount and variable. This also stops TLS checks forwarded by the overlay.

If monitoring was already enabled, restore the previous scripts, units, overrides, and timer state during upgrade recovery instead of fully disabling it. Retain collector files for investigation; database migrations are not reversed.

Match capabilities and procedures to your deployment version. Read the documentation scope

BOS API · TYPEX

Sales consultation is unavailable

Sales reception could not be initialized. Please try again later. Documentation and free self-hosting remain available.

Read the docsSelf-host for free