A workspace you can run.

Install locally

Requires Docker Engine, Docker Compose v2 and Git. Port 8000 serves the workspace; Prometheus uses 9090 and Grafana uses 3000. All three bind to loopback by default.

git clone https://github.com/AryanSharma9917/SystemMonitoring.git
cd SystemMonitoring
cp .env.example .env

Edit .env: set a unique GRAFANA_ADMIN_PASSWORD, then approve your exact target origins. Example:

MONITOR_APPROVED_ORIGINS=["https://api.example.com"]

Replace that example with your own origin. Internal targets must also appear in MONITOR_PRIVATE_ORIGINS. Metadata and link-local destinations remain blocked.

docker compose up --build -d
docker compose exec fastapi python -m system_monitoring.admin

The administrator command prompts for a password. Open http://localhost:8000, sign in, and choose Add service. Enter an approved health URL and configure its interval, timeout, expected status and failure threshold. Wait for its first observation.

No default application password or public signup exists. Recover access using the same command with --reset-password; this revokes all sessions.

Demonstrate an outage

Use a separate demo installation: the optional Compose file replaces target approvals with its local sample service. Its unauthenticated controls must stay local.

docker compose -f docker-compose.yml -f compose.demo.yml up --build -d
# Create an administrator if this installation is new:
docker compose -f docker-compose.yml -f compose.demo.yml exec fastapi python -m system_monitoring.admin
# Bash: enter the password without placing it in command history.
read -r -s -p "Administrator password: " MONITOR_ADMIN_PASSWORD
export MONITOR_ADMIN_PASSWORD
python3 scripts/demonstrate-outage.py
unset MONITOR_ADMIN_PASSWORD

The script registers a sample, waits for a scheduled success, changes it to HTTP 503, verifies one incident, then restores HTTP 200 and verifies recovery. It normally takes 30–45 seconds. Inspect the workspace and Grafana afterwards.

Notifications require a configured generic webhook receiver. The browser verification runs its own local receiver, checks a retry and recovery, and can record the complete workflow:

uv sync --locked
uv run --locked playwright install chromium
uv run --locked python scripts/check-browser.py --record --artifacts browser-artifacts

See the complete demonstration guide for controls and dashboard checks.

Recorded workflow: text walkthrough

1. Sign in and create Payments API with an approved local URL.
2. Observe a successful check, return 503 and run another check. Inspect the new incident.
3. Return 200, check again and inspect the resolved incident and response-time chart.
4. Pause, resume and edit the service. Open Notifications to see outage and recovery delivered after a transient retry.
5. Return to the overview, reload the session and sign out.

The recording uses manual checks for a short interface tour. The separate outage script verifies automatic scheduling, while the normal browser check verifies mobile layout.

How the pieces connect

Run one application process per installation. SQLite is the source of truth; its migrations run on startup. Webhooks use at-least-once delivery, with a stable event ID for receiver deduplication. A single destination is configured per installation.

Prepare an HTTPS installation

The repository includes an optional Caddy reverse proxy with automatic certificates. Point your own domain at your server, open TCP ports 80 and 443, and keep application, Prometheus and Grafana ports private.

# Add your real domain to .env:
# MONITOR_DOMAIN=monitor.example.com
docker compose -f docker-compose.yml -f compose.production.yml up --build -d
docker compose -f docker-compose.yml -f compose.production.yml exec fastapi python -m system_monitoring.admin

The production overlay enforces secure cookies, forwards the public scheme and blocks operational routes at the proxy. Do not combine it with the demonstration overlay. Follow the deployment runbook for DNS, firewall, trust boundaries, TLS checks, maintenance and rollback.

Back up before upgrading

Use the SQLite backup command instead of copying a live database file. It creates a consistent snapshot, checks integrity and refuses to overwrite existing files. Store encrypted copies off the server.

docker compose exec -T fastapi python -m system_monitoring.backup backup \
  /var/lib/system-monitoring/monitoring.sqlite3 \
  /var/lib/system-monitoring/snapshot.sqlite3

Copy the snapshot off the volume promptly. Restoration writes to a new path, revokes saved sessions and clears stale leases. Stop the application before switching database paths. See backup, restore and rollback procedures.

Choose the right scope

• One administrator, one application process and one customer per isolated installation.
• HTTP status checks, not synthetic user journeys, distributed tracing or machine resource collection.
• Observed success uses retained valid checks. It is not time-weighted uptime or an SLA. Blocked checks are excluded and disclosed.
• No multi-tenant accounts, billing, regional collectors, built-in high availability or guaranteed notification delivery.

For support or a pilot discussion, open a project issue. Describe the use case without posting credentials or confidential infrastructure details.