Install and maintain host monitoring
Install the optional Linux host collector, verify freshness, and troubleshoot the status page.
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.
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.jsonEnable 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.
touch deploy/monitor.enabled./deploy/stack.sh up./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