Documentation

Node 22 is required. From the repository root:

npm ci
npm run dev          # http://localhost:3000
npm run typecheck && npm run lint && npm test

Database-backed tests need a throwaway PostgreSQL and skip themselves without one. Schema changes are applied by scripts/migrate.mjs. Deploy and rollback steps are in docs/RUNBOOK.md; the start-here overview is docs/PROJECT_GUIDE.md.

To be confirmed: Documentation gap: there is no consolidated first-time production install guide beyond the RUNBOOK deploy section.

The agent sends outbound HTTPS heartbeats and exchanges a one-time enrollment token for a credential stored in /var/lib/monitor-agent/credential. systemd install, run on the target host from the repo root with Node 20+:

npm ci && npm run agent:build
sudo MONITOR_URL=<your dashboard URL> MONITOR_ENROLLMENT_TOKEN=<token> scripts/install-agent.sh

Check with systemctl status monitor-agent and journalctl -u monitor-agent -f. MONITOR_URL must be https. A Docker-based agent is also described in docs/RUNBOOK.md. Source: docs/agent-install.md.

In the dashboard, create the server (Servers, Add server) or open an existing one and use its enrollment token. The token is valid for 15 minutes and single use. Re-enrolling an existing server supersedes its old credential.

Main pages: Dashboard, Servers and server detail, Agents, Incidents, Websites, Notifications and Configuration (monitoring, thresholds, maintenance windows, users, audit log). /status is the public status page and /tv is the wall display. Admins can create revocable TV kiosk keys under Configuration, Users. See section 4 of docs/PROJECT_GUIDE.md.

Check types are website, ssl, systemd_service, systemd_timer, docker_container, pm2_process and agent_heartbeat. Agents auto-create checks for systemd units, containers and PM2 processes they report (never for ones an admin archived). After a configured number of consecutive failures the worker opens an incident; it recovers after a configured number of successes. See docs/ARCHITECTURE.md.

Notifications go to Microsoft Teams, SMTP email and Power Automate; channel settings are in the dashboard and webhook/SMTP values are encrypted at rest. Maintenance windows suppress alerts. Variable names such as MONITOR_TEAMS_WEBHOOK_URL and MONITOR_SMTP_* are listed in docs/PROJECT_GUIDE.md section 10.

• Server shows stale with a No heartbeat incident: check systemctl status monitor-agent and the agent journal; 401s mean the credential was revoked or expired, so issue a new enrollment token.
• Red MONITORING STOPPED banner: the worker is not completing cycles; inspect worker logs.
• Alert delivery problem: fix the channel in the dashboard and retry from the incident page.

The full symptom table is in section 5 of docs/RUNBOOK.md.

Admin and viewer roles, rate-limited login, per-server agent credentials that expire and rotate, encrypted secrets and an append-only audit log. MFA is designed but not implemented. See docs/SECURITY.md and the security page.