Gatus

Overview

Gatus polls endpoints on an interval, evaluates a list of conditions against each response, shows the results on a built-in status page and fires alerts when an endpoint fails several checks in a row. Everything lives in one YAML file (default path /config/config.yaml, override with GATUS_CONFIG_PATH, which may also be a directory of *.yaml files that are merged). Results are kept in memory by default; sqlite or postgres storage keeps history across restarts.

Instructions

Step 1: Write the configuration

# config.yaml
storage:
  type: sqlite                 # memory (default), sqlite or postgres
  path: /data/gatus.db         # file for sqlite, connection URL for postgres
web:
  port: 8080
metrics: true                  # Prometheus metrics at /metrics

alerting:
  slack:
    webhook-url: "${SLACK_WEBHOOK_URL}"      # $VAR and ${VAR} are expanded; write $$ for a literal $
    default-alert:
      failure-threshold: 3     # consecutive failures before alerting (default 3)
      success-threshold: 2     # consecutive successes before resolving (default 2)
      send-on-resolved: true
  pagerduty:
    integration-key: "${PAGERDUTY_KEY}"      # Events API v2 key
    default-alert:
      failure-threshold: 5
      send-on-resolved: true
  email:
    from: "gatus@acme-status.io"
    host: "smtp.acme-status.io"
    port: 587
    username: "${SMTP_USER}"
    password: "${SMTP_PASS}"
    to: "oncall@acme-status.io"              # required

endpoints:
  - name: API Gateway
    group: backend
    url: "https://api.acme-status.io/health"
    interval: 30s                            # default 60s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 2000"             # milliseconds
      - "[BODY].status == healthy"           # JSONPath into the body
    alerts:
      - type: slack                          # type is required even with default-alert
      - type: pagerduty

  - name: Website
    group: frontend
    url: "https://acme-status.io"
    interval: 60s
    conditions:
      - "[STATUS] == 200"
      - "[BODY] == pat(*Welcome*)"           # substring match uses pat(); there is no "contains"
      - "[CERTIFICATE_EXPIRATION] > 720h"    # fail when the TLS cert expires within 30 days

  - name: PostgreSQL
    group: infrastructure
    url: "tcp://db.acme-status.io:5432"
    interval: 30s
    conditions:
      - "[CONNECTED] == true"

  - name: DNS Resolution
    group: infrastructure
    url: "8.8.8.8"                           # DNS server address, no scheme
    dns:
      query-name: "acme-status.io"
      query-type: "A"
    conditions:
      - "[DNS_RCODE] == NOERROR"

  - name: GraphQL API
    group: backend
    url: "https://api.acme-status.io/graphql"
    method: POST
    graphql: true                            # wraps the body as {"query": "..."}
    body: |
      { __typename }
    conditions:
      - "[STATUS] == 200"
      - "[BODY].data.__typename == Query"

Other URL forms: icmp://host (ping), starttls://smtp.acme-status.io:587, and an ssh: block for SSH checks. Per-endpoint client settings include insecure, timeout (default 10s) and ignore-redirect.

Step 2: Know the condition syntax

Placeholders: [STATUS], [BODY], [RESPONSE_TIME], [CONNECTED], [CERTIFICATE_EXPIRATION], [DNS_RCODE], [IP]. Each condition must read <value> <comparator> <value> (==, !=, <, <=, >, >=); anything else, such as [BODY] contains x, stops startup with invalid condition format. Functions: len([BODY].items) > 0, has([BODY].errors) == false, pat(...) and any(...) (with == and != only), e.g. [STATUS] == any(200, 429). Prefer [STATUS] < 300 over pat(2*), which costs more.

Step 3: Run it

docker run -d --name gatus -p 8080:8080 \
  -e SLACK_WEBHOOK_URL -e PAGERDUTY_KEY -e SMTP_USER -e SMTP_PASS \
  --mount type=bind,source="$(pwd)/config.yaml",target=/config/config.yaml,readonly \
  -v gatus-data:/data \
  ghcr.io/twin/gatus:stable

twinproduction/gatus:stable on Docker Hub is the same image. Docker Compose:

services:
  gatus:
    image: ghcr.io/twin/gatus:stable
    ports: ["8080:8080"]
    volumes:
      - ./config.yaml:/config/config.yaml:ro
      - gatus-data:/data
    environment:
      - SLACK_WEBHOOK_URL
      - PAGERDUTY_KEY
      - SMTP_USER
      - SMTP_PASS
    restart: unless-stopped
volumes:
  gatus-data:

Other install routes: Helm (helm repo add twin https://twin.github.io/helm-charts && helm install gatus twin/gatus) or go install github.com/TwiN/gatus/v5@latest for a binary.

Verify: open http://localhost:8080, or curl http://localhost:8080/health (returns {"status":"UP"}) and curl http://localhost:8080/api/v1/endpoints/statuses for every endpoint's latest results. Set GATUS_LOG_LEVEL=DEBUG when troubleshooting.

Examples

Example 1: Monitor a Node.js API and React frontend

User request: "I have a Node.js API and a React frontend in Docker. Set up Gatus to watch both and tell Slack when either is down."

Create config.yaml with two endpoints in groups backend and frontend (as above), the slack provider with default-alert, and run the Compose service. Expected result: the status page at http://localhost:8080 shows two groups; after three failed checks in a row (about 90 seconds at interval: 30s) Slack receives an alert, and a resolved message after two successes.

Example 2: Gatus will not start after editing conditions

User request: "Gatus exits right away with 'error parsing config'. Here is the log."

panic: error parsing config: invalid endpoint _website: invalid condition format: does not match '<VALUE> <COMPARATOR> <VALUE>': invalid condition: [BODY] contains Welcome

Fix: replace the condition with [BODY] == pat(*Welcome*), then docker restart gatus and check docker logs gatus for Monitored group=...; success=true lines.

Guidelines

• Check status AND response time AND content: a 200 with the wrong body is still an outage.
• Keep secrets in environment variables; escape a literal $ in values as $$.
• Use storage.type: sqlite (and a mounted volume) for history across restarts; with the default memory, uptime resets whenever the container restarts.
• Failure threshold 2 to 3 avoids alerts from single network blips; each endpoint still needs alerts: - type: ....
• Alerting providers go well beyond Slack, PagerDuty and email (Discord, Teams Workflow, Telegram, Ntfy, Twilio and others); each has its own keys, so check the README section for the provider.
• Gatus protects its own page only when security (basic auth or OIDC) is configured; do not expose it publicly if URLs or errors reveal internals, and use ui.hide-url for URLs that contain tokens.
• Gatus checks from where it runs: a monitor on the same host or network as your service cannot see an outage of that host or network.