How to install and configure Gatus for health check monitoring Using Docker Compose

Gatus is a health dashboard that gives you the ability to monitor your services using HTTP, ICMP, TCP, and even DNS queries as well as evaluate the result of said queries by using a list of conditions on values like the status code, the response time, the certificate expiration, the body and many others. The icing on top is that each of these health checks can be paired with alerting via Slack, PagerDuty, Discord, Twilio and more.

In this guide, we will configure Gatus as a health dashboard tool using docker compose.

Prerequisites

Latest version of Docker installed on the system
Latest version of docker-compose installed

Ensure Docker and docker-compose is installed

Docker allows us to manage applications in the system as containers without worrying about OS dependencies. Ensure that docker is installed in the system. If you are on Ubuntu, checkout How to Install and Use Docker in Ubuntu 22.04. For other OS systems, check docker website on how to go about it.

Docker Compose is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file to configure your application’s services. Then, with a single command, you create and start all the services from your configuration.

Docker Compose is a python application thus it can be installed as a python package using pip. Ensure that you have Latest python and pip on your system before proceeding. On an Ubuntu system, I use this command:

1
sudo apt install -y python3 python3-dev python3-pip

Then use pip to install docker-compose:

1
sudo pip3 install docker-compose

Confirm that it is installed by checking the version

1
2
3
4
5
6
$ docker-compose version

docker-compose version 1.29.2, build unknown
docker-py version: 5.0.3
CPython version: 3.10.4
OpenSSL version: OpenSSL 3.0.2 15 Mar 2022

Creating Gatus configuration file

We need a config that will let Gatus know what we are monitoring. Gatus uses yaml

Create the directory where we will store our configurations:

1
2
mkdir gatus
cd gatus/

Save the following as config.yaml. Be sure to update slack url with your slack webhook.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
alerting:
  slack:
    webhook-url: ""
    default-alert:
      enabled: true
      description: "Health check failed"
      send-on-resolved: true
      failure-threshold: 5
      success-threshold: 5

endpoints:
  - name: Citizix Web
    url: "https://citizix.com/health"
    interval: 30s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 1000"
    alerts:
    - type: slack
      failure-threshold: 3
      success-threshold: 2
  - name: Citizix Grafana
    url: "https://grafana.citizix.com/"
    interval: 30s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 1000"
    alerts:
    - type: slack
      failure-threshold: 3
      success-threshold: 2

storage:
  type: sqlite
  path: data.db

The alerting section configures alerting when monitoring thresholds are met.

Gatus supports multiple alerting providers, such as Slack and PagerDuty, and supports different alerts for each individual endpoints with configurable descriptions and thresholds. Note that if an alerting provider is not properly configured, all alerts configured with the provider’s type will be ignored. In this example we are using slack. We are defining a Slack Webhook URL and failure thresholds.

The endpoints defines a list of endpoints and parameters for the endpoints.

The storage section defines data persistence layer. The default database is sqlite but there is a postgres option. I am defining that the database should be in the current path named data.db.

Running Gatus with docker

We can run the latest version of Gatus using this command:

1
docker run -p 8080:8080 twinproduction/gatus:latest

If you have a configuration file config.yaml like defined above, you can use it by running this command:

1
2
3
docker run --name gatus -p 8080:8080 \
    --mount type=bind,source="$(pwd)"/config.yaml,target=/config/config.yaml \
    twinproduction/gatus:latest

That will run Gatus as a docker container and expose gatus port (8080) in the OS. To access head over to http://server_ip:8080.

Creating a docker-compose file

Docker Compose allows us to define the configurations as yaml. This makes it easy to manage the containers and to understand the various parameters.

Create docker-compose.yaml with this content:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
version: '3.9'

services:
  app:
    image: twinproduction/gatus:latest
    restart: always
    ports:
      - 8080:8080
    volumes:
      - type: bind
        source: ./config.yaml
        target: /config/config.yaml
      - type: bind
        source: ./db
        target: /db

The above file will will run the latest gatus image twinproduction/gatus:latest and ensure that it is always restarted even if the container crashes. We are binding the port to our local system then finally binding the configuration file and the database path to the local ./db directory.

You can then run the container using this command:

1
docker-compose up -d

The container will be started and will listen on the local port :8080

(Optional) Adding Nginx virtual host to proxy traffic

It is easier to remember names than server IPs. You can opt to proxy traffic from to Gatus using nginx.

If you are using ubuntu, install nginx using this command:

1
sudo apt install nginx

Then create gatus configuration file:

1
sudo vim /etc/nginx/conf.g/gatus.conf

Add this content to the file to allow all traffic from gatus.example.com to the gatus port:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
server {
    listen 80;
    server_tokens off;
    server_name gatus.example.com;

    if ($host !~* ^(gatus.example.com)$) {
        return 444;
    }

    location / {
        proxy_redirect     off;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Host $server_name;
        proxy_pass http://127.0.0.1:8080;
    }
}

Then ensure that Nginx is started and enabled on boot:

1
2
sudo systemctl start nginx
sudo systemctl enable nginx

Now you can visit your site using the specified domain.

To enable ssl on your domain, check How to Secure Nginx with Letsencrypt on Ubuntu 20.04/22.04.

Conclusion

In this guide, we were able to set up docker and docker compose and use it to run Gatus which can be used to do health check monitor on sites.