oste/vigil repository overview

⁠Vigil

Self-hosted uptime and infrastructure monitoring. HTTP(S), TCP, ping, DNS, Docker container, and push/heartbeat checks, with Telegram, Discord, and webhook alerts, public status pages, and maintenance windows.

⁠Local development

# terminal 1 - API + monitor engine
cd server
npm install
npm run dev        # http://localhost:3001

# terminal 2 - frontend
cd client
npm install
npm run dev         # http://localhost:5173 (proxies /api to :3001)

Open http://localhost:5173⁠, you'll land on the first-run setup screen to create the single admin account.

⁠Self-hosted deployment (Docker)

1. Copy .env.example to .env and set a random JWT_SECRET:

   cp .env.example .env
   echo "JWT_SECRET=$(openssl rand -hex 32)" >> .env
   

   Copy

2a. Behind Traefik (matches an example.com-style setup with a traefik external network and a cloudflare cert resolver already configured):

docker compose up -d --build

Edit the Host() rule in docker-compose.yml to your own domain first.

2b. Standalone, exposed on a port directly:

docker compose -f docker-compose.standalone.yml up -d --build

Vigil will be on http://<host>:3001.

Data (SQLite DB) persists in the vigil-data volume.

⁠Docker container monitoring

The container mounts /var/run/docker.sock read-only so Vigil can inspect containers on the same host. When adding a "Docker container" monitor, Vigil lists running containers for you to pick from - no container ID copying required.

⁠Push / heartbeat monitors

For jobs that report in rather than get polled (e.g. a nightly backup script), add a "Push" monitor. You'll get a URL like:

https://vigil.example.com/api/push/<monitor-id>?status=up

Call it from your script on success (status=down and msg=... are also accepted). If no heartbeat arrives within 2x the configured interval, the monitor is marked down and alerts fire.

⁠Notification channels

Configured once under Notifications, then attached per-monitor:

• Telegram - bot token + chat ID
• Discord - incoming webhook URL
• Webhook - any URL that accepts a POST with a JSON payload (monitorName, status, message)

⁠Status pages

Create a status page under Status pages, pick which monitors to include, and share /status/<slug> - no login required to view it.