Create a Homelab Uptime Dashboard with Docker, Grafana, and Simple Service Health Checks

Expected Outcome

A working uptime dashboard that displays the health status of your services in real-time.

Assumptions

• Basic understanding of Docker
• Docker installed on your machine
• Basic knowledge of Grafana

Bill of Materials

• Docker
• Docker Compose
• Grafana
• Prometheus
• Node Exporter (for service health checks)

Build Steps

1. Set Up Docker Environment

   Ensure that Docker and Docker Compose are installed and running on your machine.

   Safe to run: read-only

   docker --version
   docker-compose --version

2. Create a Docker Compose File

   Create a docker-compose.yml file to define the services needed for Grafana and Prometheus.

   Safe to run: read-only

   touch docker-compose.yml

3. Define Prometheus Service

   Add the Prometheus service configuration to the docker-compose.yml file.

   Safe to run: read-only

   echo 'version: "3"' >> docker-compose.yml
   echo 'services:' >> docker-compose.yml
   echo '  prometheus:' >> docker-compose.yml
   echo '    image: prom/prometheus' >> docker-compose.yml
   echo '    volumes:' >> docker-compose.yml
   echo '      - ./prometheus.yml:/etc/prometheus/prometheus.yml' >> docker-compose.yml
   echo '    ports:' >> docker-compose.yml
   echo '      - "9090:9090"' >> docker-compose.yml

4. Create Prometheus Configuration

   Create a Prometheus configuration file to specify the targets to monitor.

   Example pattern only. Adjust for your environment before running.

   touch prometheus.yml

5. Define Monitoring Targets in Prometheus

   Add the targets (services) you want to monitor in the prometheus.yml file.

   Example pattern only. Adjust for your environment before running.

   echo 'global:' >> prometheus.yml
   echo '  scrape_interval: 15s' >> prometheus.yml
   echo 'scrape_configs:' >> prometheus.yml
   echo '  - job_name: "node"' >> prometheus.yml
   echo '    static_configs:' >> prometheus.yml
   echo '      - targets: ["localhost:9100"]' >> prometheus.yml

6. Define Grafana Service

   Add the Grafana service configuration to the docker-compose.yml file.

   Safe to run: read-only

   echo '  grafana:' >> docker-compose.yml
   echo '    image: grafana/grafana' >> docker-compose.yml
   echo '    ports:' >> docker-compose.yml
   echo '      - "3000:3000"' >> docker-compose.yml

7. Start the Services

   Use Docker Compose to start the Prometheus and Grafana services.

   Changes system state: review before running

   docker-compose up -d

8. Access Grafana Dashboard

   Open your web browser and navigate to http://localhost:3000 to access the Grafana dashboard.

9. Add Prometheus as Data Source in Grafana

   In Grafana, add Prometheus as a data source to visualize the metrics.

10. Create a Dashboard

    Create a new dashboard in Grafana and add panels to display the uptime of your services.

Validation

• Check that the Grafana dashboard displays data from Prometheus.
• Verify that the service health checks are correctly reflected in the dashboard.

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 Grafana features to customize your dashboard.
• Add more services to monitor and visualize their health.
• Set up alerts in Grafana for service downtime.