TwiN/gatus

Features

• Highly flexible health check conditions: While checking the response status may be enough for some use cases, Gatus goes much further and allows you to add conditions on the response time, the respons
• Ability to use Gatus for user acceptance tests: Thanks to the point above, you can leverage this application to create automated user acceptance tests.
• Very easy to configure: Not only is the configuration designed to be as readable as possible, it's also extremely easy to add a new service or a new endpoint to monitor.
• Alerting: While having a pretty visual dashboard is useful to keep track of the state of your application(s), you probably don't want to stare at it all day. Thus, notifications via Slack, Mattermost,
• Low resource consumption: As with most Go applications, the resource footprint that this application requires is negligibly small.

Deployment

Many examples can be found in the .examples folder, but this section will focus on the most popular ways of deploying Gatus.

Installing as binary

You can download Gatus as a binary using the following command:

go install github.com/TwiN/gatus/v5@latest

Usage

If you want to create your own configuration, see Docker for information on how to mount a configuration file.

docker run -p 8080:8080 --name gatus ghcr.io/twin/gatus:stable

Configuration

By default, the configuration file is expected to be at config/config.yaml.

You can specify a custom path by setting the GATUSCONFIGPATH environment variable.

If GATUSCONFIGPATH points to a directory, all .yaml and .yml files inside said directory and its subdirectories are merged like so: - All maps/objects are deep merged (i.e. you could define alerting.slack in one file and alerting.pagerduty in another file) - All slices/arrays are appended (i.e. you can define endpoints in multiple files and each endpoint will be added to the final list of endpoints) - Parameters with a primitive value (e.g. metrics, alerting.slack.webhook-url, etc.) may only be defined once to forcefully avoid any ambiguity - To clarify, this also means that you could not defi

Configuration

If you want more verbose logging, you may set the GATUSLOGLEVEL environment variable to DEBUG. Conversely, if you want less verbose logging, you can set the aforementioned environment variable to WARN, ERROR or FATAL. The default value for GATUSLOGLEVEL is INFO.

• metrics — Whether to expose metrics at /metrics. — false
• storage — Storage configuration. — {}
• alerting — Alerting configuration. — {}
• announcements — Announcements configuration. — []
• endpoints — Endpoints configuration. — Required []
• external-endpoints — External Endpoints configuration. — []
• security — Security configuration. — {}
• concurrency — Maximum number of endpoints/suites to monitor concurrently. Set to 0 for unlimited. See Concurrency. — 3
• disable-monitoring-lock — Whether to disable the monitoring lock. Deprecated: Use concurrency: 0 instead. — false
• skip-invalid-config-update — Whether to ignore invalid configuration update. See Reloading configuration on the fly. — false
• web — Web configuration. — {}
• ui — UI configuration. — {}
• maintenance — Maintenance configuration. — {}

Client configuration

In order to support a wide range of environments, each monitored endpoint has a unique configuration for the client used to send the request.

Note that this configuration is only available under endpoints[], alerting.mattermost and alerting.custom.

Here's an example with the client configuration under endpoints[]:

This example shows how you can specify a custom DNS resolver:

• client.insecure — Whether to skip verifying the server's certificate chain and host name. — false
• client.ignore-redirect — Whether to ignore redirects (true) or follow them (false, default). — false
• client.timeout — Duration before timing out. — 10s
• client.dns-resolver — Override the DNS resolver using the format {proto}://{host}:{port}. — ""
• client.oauth2 — OAuth2 client configuration. — {}
• client.oauth2.token-url — The token endpoint URL — required ""
• client.oauth2.client-id — The client id which should be used for the Client credentials flow — required ""
• client.oauth2.client-secret — The client secret which should be used for the Client credentials flow — required ""
• client.oauth2.scopes[] — A list of scopes which should be used for the Client credentials flow. — required [""]
• client.proxy-url — The URL of the proxy to use for the client — ""
• client.identity-aware-proxy — Google Identity-Aware-Proxy client configuration. — {}
• client.identity-aware-proxy.audience — The Identity-Aware-Proxy audience. (client-id of the IAP oauth2 credential) — required ""
• client.tls.certificate-file — Path to a client certificate (in PEM format) for mTLS configurations. — ""
• client.tls.private-key-file — Path to a client private key (in PEM format) for mTLS configurations. — ""

client:
  insecure: false
  ignore-redirect: false
  timeout: 10s
  store-cookies: false

Reloading configuration on the fly

For the sake of convenience, Gatus automatically reloads the configuration on the fly if the loaded configuration file is updated while Gatus is running.

By default, the application will exit if the updating configuration is invalid, but you can configure Gatus to continue running if the configuration file is updated with an invalid configuration by setting skip-invalid-config-update to true.

Keep in mind that it is in your best interest to ensure the validity of the configuration file after each update you apply to the configuration file while Gatus is running by looking at the log and making sure that you do not see the following message:

Failure to do so may result in Gatus being unable to start if the application is restarted for whatever reason.

The configuration file was updated, but it is not valid. The old configuration will continue being used.