Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Public-facing consul-backed status page

A simple status page for your Consul services. Displays whether they are up or not with a simple status page. You can choose which services are displayed by specifying their names.

DISCLAIMER: This project is not associated with Hashicorp or the Consul project in any way. It just uses the API of your consul instance. Hashicorp do not endorse (or even know about, probably) this project. Hashicorp and Consul are trademarks of Hashicorp®.

System Requirements

  • Consul instance (authentication isn't yet supported)
  • PHP 7+ enabled web server
  • Composer


Clone this git repo:

git clone

cd into the repository:

cd consulstatus;

Install the Composer dependencies:

composer install

Then, point your web server at the src directory. For example, to start a PHP development web server:

# Run this from the root of the repository
php -S [::1]:4567 -t src

Finally, create the settings file. Relative to the root of the repository, it should be located data/settings.toml. It should look like this:

title = "ExampleCloud Status Page"

# The base URL of the Consul API
base_url = ""
# The list of services to show the status of

name = "A Group"

	name = "dashboard"
	description = "some description text. The description field is optional."

	name = "another_service"

name = "Another Group"

	name = "apple"
	description = "The apple service"

	name = "orange"
	description = "The orange service"

Then, you should be able to load index.php in your web browser and it should work!

Optionally, add a background section to seet a background image:


mode="cover" # Default, causes the background to be enlarged to cover the entire page
# OR, for a fixed background that doesn't move:

consulalerter is a small Bash script whose purpose is writing service check status updates to an MQTT server - more methods may be added in the future.

Warning: The directory used for persisting state gets a number of writes (though attempts have been made to optimise this), so try to avoid it being on an SSD / flash memory.

It writes to the mqtt topic consul/checks/status_changes by default whenever the number of failed checks for a services changes in the following format:

    "service_name": "SERVICE_NAME_HERE",
    "checks": {
        "total": "2",
        "failed": "0"
  • service_name: The name of the service whose status has changed
  • The total number of checks the service has
  • checks.failed: The number of aforementioned checks that failed


Copy the logrotate & rsyslog config files into place:

cd path/to/consulstatus_repo_root;
sudo cp consulalerter-logrotate /etc/logrotate.d/consulalerter
sudo cp consulalerter-rsyslog.conf /etc/rsyslog.d/consulalerter.conf

Copy the systemd service file into place:

sudo cp consulalerter.service /etc/systemd/system

Make sure to edit the service file to match your filepaths:

sudo nano /etc/systemd/system/consulalerter.service

Create the consulalerter user:

sudo useradd --no-create-home --system --home /srv/consulalerter consulalerter

Create the data directory:

sudo mkdir -p /srv/consulalerter;
sudo chown consulalerter:consulalerter /srv/consulalerter;

Now, write a config file:

#!/usr/bin/env bash



Note that consulalerter requires a username & password to login to the MQTT server, and won't function without one.

Save it to the right place:

# Write the config file....
sudo nano /srv/consulalerter/
# ....and set the correct permissions on it
sudo chmod +x /srv/consulalerter/

Finally, start consulalerter.service and enable it on boot:

sudo systemctl enable --now consulalerter.service


Contributions are very welcome - both issues and pull requests! Please mention in your pull request that you release your work under the MPL-2.0 (see below).

If you're feeling that way inclined, the sponsor button at the top of the page (if you're on GitHub) will take you to my Liberapay profile if you'd like to donate to say an extra thank you :-)


Consulstatus is released under the Mozilla Public License 2.0. The full license text is included in the LICENSE file in this repository. Tldr legal have a great summary of the license if you're interested.


Simple public-facing consul-backed status page








No releases published

Sponsor this project


No packages published