Create an Uptime Kuma and Grafana Homelab Monitor with Status Pages and Escalation Rules

Expected Outcome

A working monitoring system using Uptime Kuma and Grafana that provides status pages and escalation alerts for your homelab services.

Assumptions

• Basic knowledge of Docker and Docker Compose
• A server or local machine to host the services
• Access to a terminal/command line interface
• Docker and Docker Compose installed

Bill of Materials

• Docker
• Docker Compose
• Uptime Kuma Docker image
• Grafana Docker image
• A text editor for configuration files

Build Steps

1. Set up Uptime Kuma

   Deploy Uptime Kuma using Docker Compose.

   Changes system state: review before running

   mkdir uptime-kuma
   cd uptime-kuma
   echo 'version: "3"
   services:
     uptime-kuma:
       image: louislam/uptime-kuma:latest
       ports:
         - '3001:3001'
       volumes:
         - ./data:/app/data
       restart: always' > docker-compose.yml
   docker-compose up -d

2. Access Uptime Kuma

   Open your web browser and navigate to Uptime Kuma to complete the setup. Manual action: Open a web browser and go to http://localhost:3001.

3. Add services to Uptime Kuma

   Create monitors for the services you want to track. Manual action: Log in to Uptime Kuma and click on 'Add New Monitor'.

   Example pattern only. Adjust for your environment before running.

   Fill in the details for the service you want to monitor and save.

4. Set up Grafana

   Deploy Grafana using Docker Compose.

   Changes system state: review before running

   mkdir grafana
   cd grafana
   echo 'version: "3"
   services:
     grafana:
       image: grafana/grafana:latest
       ports:
         - '3000:3000'
       restart: always' > docker-compose.yml
   docker-compose up -d

5. Access Grafana

   Open your web browser and navigate to Grafana to complete the setup. Manual action: Open a web browser and go to http://localhost:3000.

6. Configure Grafana data source

   Connect Grafana to Uptime Kuma's database for visualization. Manual action: Log in to Grafana and go to 'Configuration' > 'Data Sources'; Add a new data source and select the appropriate type (e.g., InfluxDB, Prometheus).

   Example pattern only. Adjust for your environment before running.

   Fill in the required connection details and save.

7. Create dashboards in Grafana

   Build dashboards to visualize the data collected by Uptime Kuma. Manual action: Go to 'Dashboards' > 'New Dashboard' in Grafana.

   Example pattern only. Adjust for your environment before running.

   Add panels and configure them to display the metrics from Uptime Kuma.

8. Set up status pages

   Create public status pages for your monitored services. Manual action: In Uptime Kuma, navigate to 'Status Pages'; Click 'Add New Status Page' and configure the details.

9. Configure escalation rules

   Set up alerts and escalation rules for service downtime. Manual action: In Uptime Kuma, go to 'Settings' > 'Notifications'.

   Example pattern only. Adjust for your environment before running.

   Configure notification channels and set escalation rules based on your needs.

Validation

• Ensure Uptime Kuma is collecting data correctly by checking the dashboard.
• Verify that Grafana is displaying the correct metrics.
• Test the status pages to ensure they are publicly accessible.
• Simulate downtime to check if escalation rules are triggered.

Troubleshooting

• If a step fails, capture the exact command, exit code, and log line before retrying or changing the design.
• Use `docker compose ps` and `docker compose logs <service>` to separate image, environment, port, and volume problems.

Cleanup or Rollback

• Keep a copy of working configuration, compose files, scripts, and service credentials before removing containers, packages, or data directories.
• Stop test containers with `docker compose down` only after confirming which volumes contain persistent data.
• Rollback by redeploying the previous compose file or image tag and restoring the saved environment file.

Next Improvements

• Explore additional Grafana plugins for enhanced visualization.
• Consider setting up additional monitoring tools for comprehensive coverage.
• Regularly review and update your monitoring configuration.