vigil

Vigil

Microservices Status Page. Monitors a distributed infrastructure and sends alerts (Slack, SMS, etc.).

Vigil is an open-source Status Page you can host on your infrastructure, used to monitor all your servers and apps, and visible to your users (on a domain of your choice, eg. status.example.com).

It is useful in microservices contexts to monitor both apps and backends. If a node goes down in your infrastructure, you receive a status change notification in a Slack channel, Email, Twilio SMS or/and XMPP.

Tested at Rust version: rustc 1.91.1 (ed61e7d7e 2025-11-07)

** Crafted in Budapest, Hungary.**

** See a live demo of Vigil on Crisp Status Page.**

:newspaper: The Vigil project was announced in a post on my personal journal.

Who uses it?

_ You use Vigil and you want to be listed there? Contact me._

Features

• Monitors your infrastructure services automatically
• Notifies you when a service gets down or gets back up via a configured channel:
  • Email
  • Twilio (SMS)
  • Slack
  • Zulip
  • Telegram
  • Pushover
  • Gotify
  • XMPP
  • Matrix
  • Cisco Webex
  • Webhook
• Generates a status page, that you can host on your domain for your public users (eg. https://status.example.com)
• Allows publishing announcements, eg. let your users know that a planned maintenance is upcoming

How does it work?

Vigil monitors all your infrastructure services. You first need to configure target services to be monitored, and then Vigil does the rest for you.

There are three kinds of services Vigil can monitor:

• HTTP / TCP / SSH / ICMP services: Vigil frequently probes an HTTP, TCP, SSH or ICMP target and checks for reachability
• Application services: Install the Vigil Reporter library eg. on your NodeJS app and get reports when your app gets down, as well as when the host server system is overloaded
• Local services: Install a slave Vigil Local daemon to monitor services that cannot be reached by the Vigil master server (eg. services that are on a different LAN)

It is recommended to configure Vigil, Vigil Reporter or Vigil Local to send frequent probe checks, as to ensure you are quickly notified when a service gets down (thus to reduce unexpected downtime on your services).

Hosted alternative to Vigil

Vigil needs to be hosted on your own systems, and maintained on your end. If you do not feel like managing yet another service, you may use Crisp Status instead.

Crisp Status is a direct port of Vigil to the Crisp customer support platform.

Crisp Status hosts your status page on Crisp systems, and is able to do what Vigil does (and even more!). Crisp Status is integrated to other Crisp products (eg. Crisp Chatbox & Crisp Helpdesk). It warns your users over chatbox and helpdesk if your status page reports as dead for an extended period of time.

As an example of a status page running Crisp Status, check out Enrich Status Page.

How to use it?

Installation

Vigil is built in Rust. To install it, either download a version from the Vigil releases page, use cargo install or pull the source code from master.

Install from packages:

Vigil provides pre-built packages for Debian-based systems (Debian, Ubuntu, etc.).

Important: Vigil only provides 64 bits packages targeting Debian 11 & 12 for now (codenames: bullseye & bookworm). You will still be able to use them on other Debian versions, as well as Ubuntu.

First, add the Vigil APT repository (eg. for Debian bookworm):

echo "deb [signed-by=/usr/share/keyrings/valeriansaliou_vigil.gpg] https://packagecloud.io/valeriansaliou/vigil/debian/ bookworm main" > /etc/apt/sources.list.d/valeriansaliou_vigil.list

curl -fsSL https://packagecloud.io/valeriansaliou/vigil/gpgkey | gpg --dearmor -o /usr/share/keyrings/valeriansaliou_vigil.gpg

apt-get update

Then, install the Vigil package:

apt-get install vigil

Then, edit the pre-filled Vigil configuration file:

nano /etc/vigil/vigil.cfg

Finally, restart Vigil:

service vigil restart

Install from Cargo:

If you prefer managing vigil via Rust's Cargo, install it directly via cargo install:

cargo install vigil-server

Ensure that your $PATH is properly configured to source the Crates binaries, and then run Vigil using the vigil command.

Install from source:

The last option is to pull the source code from Git and compile Vigil via cargo:

cargo build --release

You can find the built binaries in the ./target/release directory.

Install libssl-dev (ie. OpenSSL headers) and libstrophe-dev (ie. XMPP library headers; only if you need the XMPP notifier) before you compile Vigil. SSL dependencies are required for the HTTPS probes and email notifications.

Install from Docker Hub:

You might find it convenient to run Vigil via Docker. You can find the pre-built Vigil image on Docker Hub as valeriansaliou/vigil.

Pre-built Docker version may not be the latest version of Vigil available.

First, pull the valeriansaliou/vigil image:

docker pull valeriansaliou/vigil:v1.29.0

Then, seed it a configuration file and run it (replace /path/to/your/vigil/config.cfg with the path to your configuration file):

docker run -p 8080:8080 -v /path/to/your/vigil/config.cfg:/etc/vigil.cfg valeriansaliou/vigil:v1.29.0

In the configuration file, ensure that:

• server.inet is set to 0.0.0.0:8080 (this lets Vigil be reached from outside the container)
• assets.path is set to ./res/assets/ (this refers to an internal path in the container, as the assets are contained there)

Vigil will be reachable from http://localhost:8080.

Configuration

Use the sample config.cfg configuration file and adjust it to your own environment.

You can also use environment variables with string interpolation in your configuration file, eg. manager_token = ${VIGIL_MANAGER_TOKEN}.

Available configuration options are commented below, with allowed values:

[server]

• log_level (type: string, allowed: debug, info, warn, error, default: error) — Verbosity of logging, set it to error in production
• inet (type: string, allowed: IPv4 / IPv6 + port, default: [::1]:8080) — Host and TCP port the Vigil public status page should listen on
• workers (type: integer, allowed: any number, default: 4) — Number of workers for the Vigil public status page to run on
• mcp_server (type: boolean, allowed: true, false, default: false) — Whether to enable MCP server or not (allows AI Agents to access public data from probes on HTTP path: /mcp/probes)
• manager_token (type: string, allowed: secret token, default: no default) — Manager secret token (ie. secret password)
• reporter_token (type: string, allowed: secret token, default: no default) — Reporter secret token (ie. secret password)

[assets]

• path (type: string, allowed: UNIX path, default: ./res/assets/) — Path to Vigil assets directory

[branding]

• page_title (type: string, allowed: any string, default: Status Page) — Status page title
• page_url (type: string, allowed: URL, no default) — Status page URL
• company_name (type: string, allowed: any string, no default) — Company name (ie. your company)
• icon_color (type: string, allowed: hexadecimal color code, no default) — Icon color (ie. your icon background color)
• icon_url (type: string, allowed: URL, no default) — Icon URL, the icon should be your squared logo, used as status page favicon (PNG format recommended)
• logo_color (type: string, allowed: hexadecimal color code, no default) — Logo color (ie. your logo primary color)
• logo_url (type: string, allowed: URL, no default) — Logo URL, the logo should be your full-width logo, used as status page header logo (SVG format recommended)
• website_url (type: string, allowed: URL, no default) — Website URL to be used in status page header
• support_url (type: string, allowed: URL, no default) — Support URL to be used in status page header (ie. where users can contact you if something is wrong)
• custom_html (type: string, allowed: HTML, default: empty) — Custom HTML to include in status page head (optional)

[metrics]

• poll_interval (type: integer, allowed: seconds, default: 120) — Interval for which to probe nodes in poll mode
• poll_retry (type: integer, allowed: any number, default: 2) — Number of times to retry probing a failing node in poll mode
• poll_retry_wait (type: integer, allowed: milliseconds, default: 500) — Time to hold for before retrying a last failed poll probe (for each poll_retry attempted)
• poll_http_status_healthy_above (type: integer, allowed: HTTP status code, default: 200) — HTTP status above which poll checks to HTTP replicas reports as healthy
• poll_http_status_healthy_below (type: integer, allowed: HTTP status code, default: 400) — HTTP status under which poll checks to HTTP replicas reports as healthy
• poll_delay_dead (type: integer, allowed: seconds, default: 10) — Delay after which a node in poll mode is to be considered dead (ie. check response delay)
• poll_delay_sick (type: integer, allowed: seconds, default: 5) — Delay after which a node in poll mode is to be considered sick (ie. check response delay)
• poll_parallelism (type: integer, allowed: any number, default: 4) — Maximum number of poll threads to be ran simultaneously (in case you are monitoring a lot of nodes and/or slow-replying nodes, increasing parallelism will help)
• push_delay_dead (type: integer, allowed: seconds, default: 20) — Delay after which a node in push mode is to be considered dead (ie. time after which the node did not report)
• push_system_cpu_sick_above (type: float, allowed: system CPU loads, default: 0.90) — System load indice for CPU above which to consider a node in push mode sick (ie. UNIX system load)
• push_system_ram_sick_above (type: float, allowed: system RAM loads, default: 0.90) — System load indice for RAM above which to consider a node in push mode sick (ie. percent RAM used)
• script_interval (type: integer, allowed: seconds, default: 300) — Interval for which to probe nodes in script mode
• script_parallelism (type: _i