↓ Skip to main content
Florian Hoss
Setting up Gatus with Docker Compose: Monitoring and Health Checks

Setting up Gatus with Docker Compose: Monitoring and Health Checks

·589 words·3 mins
Gatus Monitoring Docker Docker-Compose Health-Check Uptime
Table of Contents

Gatus is a powerful, open-source tool for service monitoring and health checks. In this guide, I’ll show you how to set up and configure Gatus with Docker Compose to monitor your services.

What is Gatus?
#

Gatus is a modern monitoring tool distinguished by the following features:

  • Simple configuration via YAML files
  • Web interface for monitoring service status
  • Flexible endpoint tests (HTTP, TCP, ICMP, DNS)
  • Notifications through various channels (Slack, Discord, Email, etc.)
  • Minimal Resource Usage - perfect for Docker deployments

Docker Compose Setup
#

Here’s a Docker Compose configuration for Gatus:

services:
  gatus:
    image: twinproduction/gatus:v5.27.0@sha256:5091320d752756d7ac0a094d26ac38eb8216d7ed5857642b305522d1c6641f72
    container_name: gatus
    restart: always
    volumes:
      - /opt/docker/gatus/config:/config
      - /opt/docker/gatus/data:/data/
    expose:
      - 8080
    networks:
      - proxy

networks:
  proxy:
    external: true

Gatus Configuration
#

Create Directory Structure
#

First, let’s create the required directories:

sudo mkdir -p /opt/docker/gatus/{config,data}
sudo chown -R $USER:$USER /opt/docker/gatus

Basic Configuration (config.yaml)
#

Create the main configuration file /opt/docker/gatus/config/config.yaml:

# General settings
web:
  port: 8080
  
# Database configuration (SQLite)
storage:
  type: sqlite
  path: /data/data.db

# UI configuration
ui:
  title: "Service Status Dashboard"
  header: "Service Monitoring"
  
# Endpoints to monitor
endpoints:
  - name: "Main Website"
    url: "https://yourdomain.com"
    interval: 30s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 1000"
      - "[BODY] == pat(*Welcome*)"
    
  - name: "API Service"
    url: "https://api.yourdomain.com/health"
    interval: 60s
    conditions:
      - "[STATUS] == 200"
      - "[BODY].status == UP"
    
  - name: "Database Connection"
    url: "tcp://db.yourdomain.com:5432"
    interval: 30s
    conditions:
      - "[CONNECTED] == true"
      - "[RESPONSE_TIME] < 500"
    
  - name: "DNS Check"
    url: "1.1.1.1"
    dns:
      query-name: "yourdomain.com"
      query-type: "A"
    interval: 60s
    conditions:
      - "[DNS_RCODE] == NOERROR"

Advanced Configuration Options
#

Setting up Notifications
#

Add Slack notifications:

alerting:
  slack:
    webhook-url: "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
    default-alert:
      description: "Service Alert"
      send-on-resolved: true
      failure-threshold: 3
      success-threshold: 2

Enable Authentication
#

For protected dashboards:

web:
  port: 8080
  
security:
  basic:
    username: "admin"
    password-sha512: "YOUR_SHA512_HASHED_PASSWORD"

Generate password hash:

echo -n 'yourpassword' | sha512sum

Starting the Service
#

1. Start Container
#

docker compose up -d

2. Check Logs
#

docker compose logs -f

3. Test Service
#

Open your browser and navigate to http://localhost:8080 to access the Gatus dashboard.

Monitoring Best Practices
#

Reasonable Check Intervals
#

  • Critical services: 30s - 1min
  • Less critical services: 2-5min
  • DNS/Infrastructure: 1-2min

Condition Examples
#

# HTTP Status and Response Time
conditions:
  - "[STATUS] == 200"
  - "[RESPONSE_TIME] < 1000"

# JSON Response validation
conditions:
  - "[STATUS] == 200"
  - "[BODY].status == healthy"
  - "[BODY].database.connected == true"

# Header validation
conditions:
  - "[STATUS] == 200"
  - "[HEADERS].Content-Type == application/json"

# Certificate monitoring
conditions:
  - "[STATUS] == 200"
  - "[CERTIFICATE_EXPIRATION] > 72h"

Maintenance and Updates
#

Update Container
#

# Pull new version
docker compose pull

# Restart service
docker compose up -d

Backup Data
#

# Backup database
cp /opt/docker/gatus/data/data.db /backup/gatus-$(date +%Y%m%d).db

# Backup configuration
tar -czf /backup/gatus-config-$(date +%Y%m%d).tar.gz /opt/docker/gatus/config/

Troubleshooting
#

Common Issues
#

Problem: Service reachable but checks are failing

# Test network connectivity
docker exec gatus ping yourdomain.com

# Check DNS resolution
docker exec gatus nslookup yourdomain.com

Problem: High response times

  • Check network latency
  • Reduce check frequency for less critical services
  • Use local DNS servers

Debugging
#

# Enable detailed logs
docker compose logs -f | grep -i error

# Check container status
docker compose ps gatus

Conclusion
#

With this configuration, you have a robust monitoring system that:

  • Monitors all important services
  • Notifies on failures
  • Available via web interface
  • Uses minimal resources
  • Easy to maintain

Gatus is perfect for small to medium infrastructures and offers a good alternative to more complex monitoring solutions like Prometheus/Grafana when you need a simple but effective status dashboard.

Further Resources
#

Florian Hoss
Author
Florian Hoss
Matrix