Gatus — Automated Status Page with Health Checks & Alerts

What Gatus Does

• Health Checks: HTTP, TCP, DNS, ICMP, SSH, STARTTLS, and TLS monitoring
• Conditions: Flexible condition expressions (status code, response time, body content, certificate expiry)
• Status Page: Beautiful, auto-generated public status page
• Alerts: Slack, Discord, PagerDuty, OpsGenie, Telegram, email, webhook, and more
• Uptime Badges: Embeddable SVG badges for README files
• Incidents: Manual and automatic incident annotations on the status page
• Groups: Organize endpoints into logical groups (Production, Staging, External)
• Metrics: Prometheus and InfluxDB metrics export
• Configuration as Code: Everything defined in YAML — version control your monitoring

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  config.yaml │────▶│  Gatus       │────▶│  Endpoints   │
│  (Endpoints  │     │  Engine (Go) │     │  (HTTP/TCP/  │
│   Conditions │     └──────┬───────┘     │   DNS/etc)   │
│   Alerts)    │            │             └──────────────┘
└──────────────┘     ┌──────┴───────┐
                     │  Status Page │
                     │  + Alerts    │
                     │  + Badges    │
                     └──────────────┘

Configuration

Basic Example

endpoints:
  - name: Website
    group: Production
    url: "https://yourdomain.com"
    interval: 60s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 2000"

  - name: API
    group: Production
    url: "https://api.yourdomain.com/health"
    interval: 30s
    conditions:
      - "[STATUS] == 200"
      - "[BODY].status == UP"
      - "[RESPONSE_TIME] < 500"

  - name: Database
    group: Infrastructure
    url: "tcp://db.internal:5432"
    interval: 30s
    conditions:
      - "[CONNECTED] == true"

  - name: DNS
    group: Infrastructure
    url: "dns://8.8.8.8"
    interval: 120s
    dns:
      query-name: "yourdomain.com"
      query-type: "A"
    conditions:
      - "[DNS_RCODE] == NOERROR"

  - name: SSL Certificate
    group: Security
    url: "https://yourdomain.com"
    interval: 3600s
    conditions:
      - "[CERTIFICATE_EXPIRATION] > 720h"  # Alert if < 30 days

With Alerts

alerting:
  slack:
    webhook-url: "https://hooks.slack.com/services/xxx/yyy/zzz"
    default-alert:
      enabled: true
      failure-threshold: 3
      success-threshold: 2
      send-on-resolved: true

  discord:
    webhook-url: "https://discord.com/api/webhooks/xxx/yyy"

  pagerduty:
    integration-key: "your-pagerduty-key"

endpoints:
  - name: Critical API
    url: "https://api.yourdomain.com/health"
    interval: 30s
    conditions:
      - "[STATUS] == 200"
    alerts:
      - type: slack
        failure-threshold: 2
        description: "API is down!"
      - type: pagerduty
        failure-threshold: 5
        description: "API critical failure"

Response Body Checks

endpoints:
  - name: API Health
    url: "https://api.example.com/health"
    conditions:
      - "[STATUS] == 200"
      - "[BODY].status == ok"
      - "[BODY].database == connected"
      - "[BODY].cache == connected"
      - "[BODY].version == any(v2.0.0, v2.1.0)"

Self-Hosting

Docker Compose

services:
  gatus:
    image: twinproduction/gatus:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.yaml:/config/config.yaml
      - gatus-data:/data
    restart: unless-stopped

volumes:
  gatus-data:

Kubernetes

apiVersion: v1
kind: ConfigMap
metadata:
  name: gatus-config
data:
  config.yaml: |
    endpoints:
      - name: Frontend
        url: "https://myapp.com"
        interval: 60s
        conditions:
          - "[STATUS] == 200"

Key Features

Uptime Badges

Embed in your README:

![Uptime](https://status.yourdomain.com/api/v1/endpoints/production_website/uptimes/7d/badge.svg)
![Response Time](https://status.yourdomain.com/api/v1/endpoints/production_api/response-times/24h/badge.svg)

Maintenance Windows

endpoints:
  - name: API
    url: "https://api.example.com"
    maintenance:
      start: "23:00"
      duration: 1h
      every: [Monday, Thursday]
    conditions:
      - "[STATUS] == 200"

External Endpoints

external-endpoints:
  - name: GitHub Actions
    group: CI/CD
    token: "your-secret-token"
    # Push results via API:
    # curl -X POST https://status.yourdomain.com/api/v1/endpoints/github-actions/external 
    #   -H "Authorization: Bearer your-secret-token" 
    #   -d '{"status": "UP", "duration": 5000}'

Gatus vs Alternatives

FAQ

Q: Gatus or Uptime Kuma — which should I choose? A: Uptime Kuma has a nice web UI, great for managing monitoring through a GUI. Gatus is YAML-driven, ideal for DevOps teams who want monitoring under Git version control. If you prefer Infrastructure as Code, pick Gatus. If you prefer clicking through a UI, pick Uptime Kuma.

Q: Can it monitor internal services? A: Yes. Gatus supports TCP port checks and ICMP ping, allowing you to monitor internal databases, caches, message queues, and other services that don't expose HTTP.

Q: Where is data stored? A: By default, historical data is stored in SQLite. PostgreSQL is also supported as a backend. Retention is configurable.

Sources & Credits

• GitHub: TwiN/gatus — 10.6K+ ⭐ | Apache-2.0
• Docs: gatus.io