Skip to content
Klutch.sh Docs

Deploying Gatus

Introduction

Gatus is a developer-oriented health dashboard that monitors your services using HTTP, ICMP, TCP, and DNS queries. It evaluates the results using configurable conditions on response values like status codes, response times, certificate expiration, and response body content. Each health check can be paired with alerting via popular platforms like Slack, PagerDuty, Discord, and Twilio.

Built with Go, Gatus is lightweight, fast, and highly configurable through YAML configuration files. The modern dashboard provides real-time visibility into service health while supporting advanced features like incident management and uptime badges.

Key highlights of Gatus:

  • Multiple Protocol Support: Monitor services using HTTP, HTTPS, TCP, DNS, and ICMP checks
  • Flexible Conditions: Define custom conditions based on status codes, response times, body content, and more
  • Rich Alerting: Integrate with Slack, Discord, PagerDuty, Twilio, email, and many more notification services
  • SSL Monitoring: Track certificate expiration and receive alerts before certificates expire
  • Incident Management: Built-in incident tracking and management capabilities
  • Status Badges: Generate embeddable uptime badges for your README files
  • External Endpoints: Define endpoints as external to track third-party service health
  • Persistent History: Store health check history for trend analysis
  • Developer-Friendly: Configuration-as-code approach with YAML
  • Open Source: Licensed under Apache 2.0

This guide walks through deploying Gatus on Klutch.sh using Docker, configuring health checks for your services, and setting up alerting for production use.

Why Deploy Gatus on Klutch.sh

Deploying Gatus on Klutch.sh provides several advantages for monitoring your infrastructure:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Gatus without complex orchestration or manual server configuration. Push to GitHub, and your status page deploys automatically.

Persistent Storage: Attach persistent volumes for your health check history and database. Your monitoring data survives container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your status dashboard from anywhere.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your monitoring configuration trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on the number of services you’re monitoring. Start small and scale up as needed.

Environment Variable Management: Securely store sensitive configuration like alerting credentials through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Gatus instance for a branded status page.

Always-On Monitoring: Your health checks run 24/7 without managing your own hardware or dealing with uptime concerns.

Prerequisites

Before deploying Gatus on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your Gatus configuration
  • Basic familiarity with Docker and containerization concepts
  • (Optional) Alerting service credentials (Slack, Discord, PagerDuty, etc.)
  • (Optional) A custom domain for your status page

Understanding Gatus Architecture

Gatus is built with simplicity and efficiency in mind:

Go Backend: The core application is written in Go, providing low resource consumption and fast execution of health checks.

YAML Configuration: All monitoring endpoints and alerting rules are defined in YAML configuration files, enabling version control and infrastructure-as-code practices.

SQLite/PostgreSQL Storage: Health check history is stored in SQLite (default) or PostgreSQL for persistent data retention.

HTTP Dashboard: A modern web interface displays service health, uptime history, and incident status.

Concurrent Checking: Health checks run concurrently based on configured intervals, with intelligent scheduling to prevent resource exhaustion.

Preparing Your Repository

To deploy Gatus on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

gatus-deploy/
├── Dockerfile
├── config/
│   └── config.yaml
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM twinproduction/gatus:latest


# Copy configuration file
COPY config/config.yaml /config/config.yaml


# Set timezone
ENV TZ=${TZ:-UTC}


# Expose the web interface port
EXPOSE 8080


# The base image includes the default entrypoint

Creating the Configuration File

Create a config/config.yaml file with your monitoring configuration:

storage:
  type: sqlite
  path: /data/data.db


ui:
  title: "Service Status"
  header: "Service Health Dashboard"


endpoints:
  - name: Website
    group: core
    url: "https://example.com"
    interval: 60s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 1000"


  - name: API
    group: core
    url: "https://api.example.com/health"
    interval: 30s
    conditions:
      - "[STATUS] == 200"
      - "[BODY].status == 'healthy'"


  - name: Database
    group: infrastructure
    url: "tcp://db.example.com:5432"
    interval: 60s
    conditions:
      - "[CONNECTED] == true"


  - name: DNS
    group: infrastructure
    url: "dns://example.com@1.1.1.1"
    interval: 300s
    conditions:
      - "[DNS_RCODE] == NOERROR"

Advanced Configuration with Alerting

For production deployments with alerting:

storage:
  type: sqlite
  path: /data/data.db


ui:
  title: "Production Status"
  header: "System Health Dashboard"
  logo: "https://example.com/logo.png"


alerting:
  slack:
    webhook-url: "${SLACK_WEBHOOK_URL}"
    default-alert:
      enabled: true
      failure-threshold: 3
      success-threshold: 2
      send-on-resolved: true


  discord:
    webhook-url: "${DISCORD_WEBHOOK_URL}"
    default-alert:
      enabled: true
      failure-threshold: 3
      success-threshold: 2


  pagerduty:
    integration-key: "${PAGERDUTY_INTEGRATION_KEY}"
    default-alert:
      enabled: true
      failure-threshold: 3
      send-on-resolved: true


endpoints:
  - name: Production Website
    group: production
    url: "https://example.com"
    interval: 30s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 2000"
      - "[CERTIFICATE_EXPIRATION] > 720h"
    alerts:
      - type: slack
      - type: pagerduty


  - name: API Gateway
    group: production
    url: "https://api.example.com/v1/health"
    interval: 15s
    conditions:
      - "[STATUS] == 200"
      - "[BODY].status == 'ok'"
      - "[RESPONSE_TIME] < 500"
    alerts:
      - type: slack
        failure-threshold: 2
      - type: pagerduty
        failure-threshold: 5


  - name: Staging Environment
    group: staging
    url: "https://staging.example.com"
    interval: 60s
    conditions:
      - "[STATUS] == 200"
    alerts:
      - type: discord

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Gatus supports environment variable substitution in configuration:

VariableRequiredDefaultDescription
TZNoUTCContainer timezone
GATUS_CONFIG_PATHNo/config/config.yamlPath to configuration file
SLACK_WEBHOOK_URLConditional-Slack webhook for alerts
DISCORD_WEBHOOK_URLConditional-Discord webhook for alerts
PAGERDUTY_INTEGRATION_KEYConditional-PagerDuty integration key
PUSHOVER_TOKENConditional-Pushover application token
TWILIO_ACCOUNT_SIDConditional-Twilio account SID

Deploying Gatus on Klutch.sh

Once your repository is prepared, follow these steps to deploy Gatus:

    Prepare Your Configuration

    Review and customize your config.yaml with the endpoints you want to monitor. Ensure all URLs are accessible from Klutch.sh’s infrastructure.

    Set Up Alerting Credentials

    If using alerting, obtain the necessary credentials:

    • Slack: Create an incoming webhook in your workspace
    • Discord: Create a webhook in your channel settings
    • PagerDuty: Create an integration and get the key

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile config/ .dockerignore README.md
    git commit -m "Initial Gatus deployment configuration"
    git remote add origin https://github.com/yourusername/gatus-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “gatus” or “status-page”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Gatus Dockerfile.

    Configure HTTP Traffic

    Gatus serves its web interface over HTTP. In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 8080 (Gatus’s default port)

    Set Environment Variables

    In the environment variables section, add your alerting credentials:

    VariableValue
    TZYour timezone (e.g., America/New_York)
    SLACK_WEBHOOK_URLYour Slack webhook URL (if using)
    DISCORD_WEBHOOK_URLYour Discord webhook URL (if using)
    PAGERDUTY_INTEGRATION_KEYYour PagerDuty key (if using)

    Attach Persistent Volumes

    Persistent storage preserves your health check history. Add the following volumes:

    Mount PathRecommended SizePurpose
    /data1 GBSQLite database and health check history

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Detect your Dockerfile automatically
    • Build the container image
    • Attach the persistent volumes
    • Start the Gatus container
    • Provision an HTTPS certificate

    Access Gatus

    Once deployment completes, access your Gatus dashboard at https://your-app-name.klutch.sh. Your configured endpoints will begin health checks immediately.

Configuring Health Checks

HTTP Endpoints

Monitor web services and APIs:

endpoints:
  - name: Website
    url: "https://example.com"
    interval: 60s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 2000"
      - "[BODY] contains 'Welcome'"

TCP Endpoints

Monitor database and service ports:

endpoints:
  - name: PostgreSQL
    url: "tcp://db.example.com:5432"
    interval: 30s
    conditions:
      - "[CONNECTED] == true"

DNS Endpoints

Monitor DNS resolution:

endpoints:
  - name: DNS Resolution
    url: "dns://example.com@8.8.8.8"
    interval: 300s
    conditions:
      - "[DNS_RCODE] == NOERROR"

SSL Certificate Monitoring

Monitor certificate expiration:

endpoints:
  - name: Website SSL
    url: "https://example.com"
    interval: 3600s
    conditions:
      - "[CERTIFICATE_EXPIRATION] > 720h"  # 30 days

Configuring Alerts

Slack Alerting

alerting:
  slack:
    webhook-url: "${SLACK_WEBHOOK_URL}"
    default-alert:
      enabled: true
      failure-threshold: 3
      success-threshold: 2
      send-on-resolved: true

Discord Alerting

alerting:
  discord:
    webhook-url: "${DISCORD_WEBHOOK_URL}"
    default-alert:
      enabled: true
      failure-threshold: 3

PagerDuty Alerting

alerting:
  pagerduty:
    integration-key: "${PAGERDUTY_INTEGRATION_KEY}"
    default-alert:
      enabled: true
      failure-threshold: 5
      send-on-resolved: true

Email Alerting

alerting:
  email:
    from: "gatus@example.com"
    host: "smtp.example.com"
    port: 587
    username: "${SMTP_USERNAME}"
    password: "${SMTP_PASSWORD}"
    to: "oncall@example.com"
    default-alert:
      enabled: true
      failure-threshold: 3

Advanced Features

Endpoint Groups

Organize endpoints into logical groups:

endpoints:
  - name: API
    group: backend
    url: "https://api.example.com"
    ...


  - name: Website
    group: frontend
    url: "https://example.com"
    ...

Uptime Badges

Generate badges for your README:

![Uptime](https://your-gatus.klutch.sh/api/v1/endpoints/core_website/uptimes/7d/badge.svg)

External Endpoints

Mark third-party services as external:

endpoints:
  - name: GitHub
    group: external
    url: "https://api.github.com"
    interval: 60s
    external: true
    conditions:
      - "[STATUS] == 200"

Production Best Practices

Security Recommendations

  • Secure Webhooks: Keep alerting webhook URLs confidential
  • HTTPS Only: Always use HTTPS for monitored endpoints
  • Access Control: Consider adding authentication to your status page
  • Credential Rotation: Regularly rotate alerting credentials

Monitoring Strategy

  • Critical Services: Check frequently (15-30 seconds)
  • Standard Services: Check regularly (1-5 minutes)
  • Infrastructure: Check periodically (5-15 minutes)
  • SSL Certificates: Check hourly

Alert Tuning

  • Failure Threshold: Prevent alert fatigue with appropriate thresholds
  • Success Threshold: Require multiple successes before resolving
  • Escalation: Use different alert types for different severity levels

Troubleshooting Common Issues

Endpoints Always Failing

Solutions:

  • Verify endpoint URLs are correct
  • Check that endpoints are accessible from Klutch.sh
  • Review condition syntax
  • Check for firewall or network issues

Alerts Not Sending

Solutions:

  • Verify alerting credentials
  • Check webhook URLs are correct
  • Ensure environment variables are set
  • Review Gatus logs for errors

Dashboard Not Loading

Solutions:

  • Verify container is running
  • Check port configuration
  • Review logs for startup errors

Additional Resources

Conclusion

Deploying Gatus on Klutch.sh gives you a powerful, developer-oriented status page with automatic builds, persistent storage, and secure HTTPS access. The combination of Gatus’s flexible configuration and Klutch.sh’s deployment simplicity means you can have comprehensive monitoring running in minutes.

With support for multiple protocols, rich alerting integrations, and a clean dashboard interface, Gatus provides everything you need to monitor your infrastructure. Whether you’re tracking a few services or monitoring an entire platform, Gatus on Klutch.sh delivers reliable health monitoring without the operational overhead.