# Homer Dashboard with Healthchecks

> Homer dashboard with healthcheck monitoring.

- Category: Home Lab & Self-Hosting
- Difficulty: beginner
- Components: homer, healthchecks, nginx
- Tags: dashboard, homer, homelab, monitoring
- Source: https://docker.recipes/homelab/homer-dashboard-stack

## Overview

Homer is a static, self-hosted homepage and dashboard application designed for organizing and accessing homelab services and web applications. Originally created as a simple yet elegant solution for service discovery, Homer uses YAML configuration files to create customizable dashboards with service tiles, status indicators, and organized categories. Unlike dynamic dashboards that require databases, Homer generates static HTML from configuration files, making it lightweight and fast. Healthchecks is an open-source monitoring service that tracks scheduled tasks, cron jobs, and service uptime through HTTP pings and webhooks. When combined with Homer and NGINX, this stack creates a comprehensive homelab monitoring solution where Homer provides the visual dashboard for quick service access while Healthchecks monitors the actual health and availability of those services. NGINX acts as a reverse proxy to consolidate access and can provide SSL termination for the entire stack. This combination addresses the common homelab challenge of having multiple services running on different ports while needing reliable monitoring to ensure everything stays operational. The stack is particularly valuable for homelab enthusiasts and self-hosting advocates who want both aesthetic organization and practical monitoring without the complexity of enterprise monitoring solutions. Homer's simplicity makes it perfect for personal use, while Healthchecks provides the reliability monitoring needed for critical self-hosted services like backup scripts, file synchronization, and automated maintenance tasks.

## Features

- YAML-based configuration for Homer dashboard with hot-reload capability
- Service status integration between Homer tiles and Healthchecks monitoring endpoints
- Healthchecks ping monitoring with customizable grace periods and timeout detection
- Homer's theme customization with CSS overrides and multiple built-in themes
- Webhook notifications from Healthchecks for Slack, Discord, email, and PagerDuty integrations
- NGINX reverse proxy configuration for unified access to both dashboard and monitoring interfaces
- Healthchecks cron job monitoring with detailed logs and failure pattern analysis
- Homer icon integration with Font Awesome, custom icons, and automatic favicon fetching

## Use cases

- Homelab dashboard combining service access with uptime monitoring for self-hosted applications
- Family network portal displaying local services while monitoring backup job completion
- Small business IT dashboard tracking server health and scheduled maintenance tasks
- Development environment monitoring with project links and build pipeline health checks
- Remote server management combining SSH access points with automated task monitoring
- Home automation hub displaying smart home interfaces alongside system health monitoring
- Personal cloud services dashboard with file sync and media server status tracking

## Prerequisites

- Minimum 512MB RAM for combined Homer, Healthchecks, and NGINX containers
- Docker and Docker Compose installed with at least 2GB available disk space
- Available ports 80, 8000, and 8080 or configured alternatives in environment variables
- Basic YAML editing knowledge for Homer dashboard configuration
- Email server access for Healthchecks notifications (SMTP configuration)
- Understanding of reverse proxy concepts for NGINX configuration customization

## docker-compose.yml

```yaml
services:
  homer:
    image: b4bz/homer:latest
    container_name: homer
    restart: unless-stopped
    ports:
      - "${HOMER_PORT:-8080}:8080"
    environment:
      - UID=1000
      - GID=1000
    volumes:
      - homer_assets:/www/assets

  healthchecks:
    image: linuxserver/healthchecks:latest
    container_name: healthchecks
    restart: unless-stopped
    ports:
      - "${HC_PORT:-8000}:8000"
    environment:
      - SITE_ROOT=http://localhost:${HC_PORT:-8000}
      - SITE_NAME=Healthchecks
      - SUPERUSER_EMAIL=${ADMIN_EMAIL}
      - SUPERUSER_PASSWORD=${ADMIN_PASSWORD}
      - SECRET_KEY=${SECRET_KEY}
    volumes:
      - healthchecks_data:/config

  nginx:
    image: nginx:alpine
    container_name: homelab-nginx
    restart: unless-stopped
    ports:
      - "${NGINX_PORT:-80}:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

volumes:
  homer_assets:
  healthchecks_data:
```

## .env

```bash
# Homer Dashboard
HOMER_PORT=8080
HC_PORT=8000
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin_password
SECRET_KEY=your_secret_key
NGINX_PORT=80
```

## Usage notes

- Homer at http://localhost:8080
- Healthchecks at http://localhost:8000
- Configure Homer via config.yml
- Ping Healthchecks from cron

## Troubleshooting

- Homer shows blank dashboard: Check that homer_assets volume contains config.yml file with proper YAML syntax
- Healthchecks admin login fails: Verify ADMIN_EMAIL and ADMIN_PASSWORD environment variables are set and container has been recreated
- NGINX returns 502 Bad Gateway: Ensure nginx.conf includes proper upstream definitions for homer:8080 and healthchecks:8000
- Homer service tiles show 'unreachable': Configure service URLs to use container names or docker network IPs instead of localhost
- Healthchecks ping URLs not working: Check SITE_ROOT environment variable matches actual access URL and ports are correctly mapped
- Homer configuration changes not appearing: Restart homer container as it requires restart to reload config.yml modifications

