Healthcheck-as-Code: Building a Resilient Uptime Monitoring and Alerting System with Gatus and Gotify

Introduction: The Shift Toward Developer-Centric Monitoring

In today's fast-paced digital ecosystem, ensuring the high availability of business applications is no longer just the responsibility of a dedicated operations team. As organizations transition toward DevOps and Site Reliability Engineering (SRE) methodologies, developers are increasingly tasked with managing the lifecycle and reliability of their services. Traditional monitoring tools, while powerful, often suffer from complex user interfaces, heavy resource footprints, and rigid configuration workflows that slow down continuous deployment pipelines.

Enter the concept of Healthcheck-as-Code (HCaC). By defining uptime monitoring configurations directly in code or declarative YAML files, engineering teams can version-control their health checks alongside their application source code. This post explores a highly efficient, lightweight, and completely self-hosted stack to achieve this paradigm: Gatus for automated status monitoring and Gotify for real-time notification delivery.

Why Gatus and Gotify?

Before diving into the technical implementation, it is crucial to understand why this specific combination stands out in a crowded landscape of monitoring tools like Prometheus, Grafana, or commercial alternatives like Uptime Robot.

Gatus: Automated Status Page and Health Checking

Gatus is an open-source, developer-oriented health check dashboard that excels in simplicity and efficiency. Unlike bulky monitoring solutions, Gatus is designed around a single YAML configuration file. Key advantages include:

• Low Resource Consumption: Written in Go, Gatus runs with a minimal memory and CPU footprint, making it ideal for everything from small virtual private servers (VPS) to large Kubernetes clusters.
• Flexible Condition Evaluation: It allows developers to assert conditions based on HTTP status codes, response times, body content, and certificate expiration out of the box.
• Beautiful Built-in Dashboard: Gatus generates a clean, intuitive, and public-facing or internal status page automatically, eliminating the need to configure separate frontend visualization tools.

Gotify: Privacy-Focused Notification Delivery

While Gatus tracks the status of your endpoints, you need an instant, reliable mechanism to alert your team when a service fails. Gotify is a self-hosted, open-source notification server designed specifically for sending and receiving messages via WebSockets. By integrating Gotify, businesses can:

• Maintain Data Sovereignty: Keep all operational alerts, system names, and internal IP addresses entirely within a private network instead of routing them through third-party proprietary services.
• Eliminate Cost Hurdles: Avoid subscription fees associated with commercial alerting platforms, regardless of notification volume.
• Multi-Channel Accessibility: Access alerts instantly via a streamlined web interface, an official Android application, or custom CLI tools.

Architecture Overview: How the Stack Functions

The workflow of the Gatus-Gotify monitoring pipeline is elegant in its simplicity. Gatus acts as the orchestrator, continuously executing scheduled queries against your targeted services, APIs, databases, or external endpoints.

Core Workflow: Gatus checks endpoint → Condition fails → Gatus triggers Webhook → Gotify processes request → Push notification sent to administrator device.

When an endpoint fails to meet the pre-defined conditions (e.g., a 500 Internal Server Error is returned, or response latency exceeds 2000ms), Gatus immediately evaluates the failure threshold. If the threshold is breached, Gatus constructs a standardized payload and dispatches an HTTP POST request to the Gotify API. Gotify processes the incoming token, maps it to the designated application channel, and broadcasts a push notification to all connected clients instantly.

Step-by-Step Implementation Guide

To implement this system, we will use Docker Compose to orchestrate both services in an isolated environment. This ensures reproducibility and ease of maintenance across staging and production environments.

Step 1: Setting Up the Directory Structure

Create a dedicated directory on your server to house the configuration files:

mkdir -p scaling-monitor/{gatus,gotify-data}
cd scaling-monitor

Step 2: Designing the Docker Compose File

Create a docker-compose.yml file in the root of your directory to define both services and their persistent volumes:

version: '3.8'

services:
  gatus:
    image: twinproduction/gatus:latest
    container_name: gatus
    volumes:
      - ./gatus:/config
    ports:
      - "8080:8080"
    restart: always
    depends_on:
      - gotify

  gotify:
    image: gotify/server:latest
    container_name: gotify
    ports:
      - "80/*":80
    volumes:
      - ./gotify-data:/app/data
    restart: always

Step 3: Initializing Gotify and Generating an Application Token

Launch the containers using the following command:

docker-compose up -d

Navigate to your browser and access the Gotify web UI (typically at http://your-server-ip:80). Log in using the default administrative credentials (admin/admin) and change the password immediately via the user settings panel.

To allow Gatus to send alerts, navigate to the Apps tab in the Gotify UI and click Create Application. Name it "Gatus Monitor" and copy the generated App Token (e.g., A1b2C3d4E5f6G7h). This token ensures authenticated access to your alerting stream.

Step 4: Writing the Gatus Healthcheck-as-Code Configuration

Now, create the config.yaml file inside the ./gatus directory. This file dictates exactly what services to check, how often to check them, what constitutes a failure, and where to send the alerts.

alerting:
  gotify:
    url: "http://gotify:80/message?token=YOUR_GOTIFY_APP_TOKEN_HERE"
    default-alert:
      enabled: true
      failure-threshold: 3
      success-threshold: 2
      description: "Service alert status changed"

endpoints:
  - name: Core Business API
    url: "[https://api.yourcompany.com/v1/health](https://api.yourcompany.com/v1/health)"
    interval: 30s
    conditions:
      - "[STATUS] == 200"
      - "[RESPONSE_TIME] < 500"
    alerts:
      - type: gotify

  - name: Corporate Website Home
    url: "[https://yourcompany.com](https://yourcompany.com)"
    interval: 60s
    conditions:
      - "[STATUS] == 200"
      - "[BODY] == contains Welcome"
    alerts:
      - type: gotify

Replace YOUR_GOTIFY_APP_TOKEN_HERE with the token you obtained from Gotify in the previous step. In this file, we have configured two endpoints. The first monitors an API endpoint, validating that it responds within 500 milliseconds with a 200 OK status. The second verifies that the corporate homepage loads correctly and contains the string "Welcome". If either service fails 3 consecutive times, an alert is dispatched.

Step 5: Applying Configurations

Restart the Gatus container to apply the new configuration file:

docker-compose restart gatus

You can now navigate to http://your-server-ip:8080 to view your live, automated uptime dashboard.

Best Practices for Enterprise-Grade Monitoring

While setting up the stack is straightforward, optimizing it for production environments requires adhering to strict operational standards:

1. Isolate the Monitoring Infrastructure: Always host your monitoring stack (Gatus and Gotify) on hardware completely separate from your primary application infrastructure. If your core cluster goes offline, a co-located monitoring system will fail along with it, leaving you blind to the outage.
2. Implement Secure Reverse Proxies: Secure both Gatus and Gotify interfaces with SSL/TLS certificates using reverse proxies like Nginx, Traefik, or Caddy. Exposing raw HTTP endpoints to the open internet invites security vulnerabilities.
3. Fine-Tune Failure Thresholds: Avoid setting the failure-threshold to 1. Transient network hiccups or minor latency spikes can cause temporary failures. Setting a threshold of 3 prevents alert fatigue by ensuring notifications are only triggered for genuine, sustained outages.

Conclusion

Implementing a Healthcheck-as-Code pipeline using Gatus and Gotify offers an unparalleled balance of simplicity, efficiency, and data control. By treating health checks as versioned configuration assets, engineering teams can guarantee that monitoring coverage evolves seamlessly alongside application development. Embracing this self-hosted stack empowers your organization to detect infrastructure failures instantly, minimize MTTR (Mean Time to Resolution), and maintain the high availability your business demands.