docker.recipes

Homer Dashboard with Healthchecks

beginner

Homer dashboard with healthcheck monitoring.

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.

Key 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

Common Use Cases

  • 1Homelab dashboard combining service access with uptime monitoring for self-hosted applications
  • 2Family network portal displaying local services while monitoring backup job completion
  • 3Small business IT dashboard tracking server health and scheduled maintenance tasks
  • 4Development environment monitoring with project links and build pipeline health checks
  • 5Remote server management combining SSH access points with automated task monitoring
  • 6Home automation hub displaying smart home interfaces alongside system health monitoring
  • 7Personal 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  homer: 
3    image: b4bz/homer:latest
4    container_name: homer
5    restart: unless-stopped
6    ports: 
7      - "${HOMER_PORT:-8080}:8080"
8    environment: 
9      - UID=1000
10      - GID=1000
11    volumes: 
12      - homer_assets:/www/assets
13
14  healthchecks: 
15    image: linuxserver/healthchecks:latest
16    container_name: healthchecks
17    restart: unless-stopped
18    ports: 
19      - "${HC_PORT:-8000}:8000"
20    environment: 
21      - SITE_ROOT=http://localhost:${HC_PORT:-8000}
22      - SITE_NAME=Healthchecks
23      - SUPERUSER_EMAIL=${ADMIN_EMAIL}
24      - SUPERUSER_PASSWORD=${ADMIN_PASSWORD}
25      - SECRET_KEY=${SECRET_KEY}
26    volumes: 
27      - healthchecks_data:/config
28
29  nginx: 
30    image: nginx:alpine
31    container_name: homelab-nginx
32    restart: unless-stopped
33    ports: 
34      - "${NGINX_PORT:-80}:80"
35    volumes: 
36      - ./nginx.conf:/etc/nginx/nginx.conf:ro
37
38volumes: 
39  homer_assets: 
40  healthchecks_data:

.env Template

.env
1# Homer Dashboard
2HOMER_PORT=8080
3HC_PORT=8000
4ADMIN_EMAIL=admin@example.com
5ADMIN_PASSWORD=admin_password
6SECRET_KEY=your_secret_key
7NGINX_PORT=80

Usage Notes

  1. 1Homer at http://localhost:8080
  2. 2Healthchecks at http://localhost:8000
  3. 3Configure Homer via config.yml
  4. 4Ping Healthchecks from cron

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

homer
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
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
nginx:
  image: nginx:alpine
  container_name: homelab-nginx
  restart: unless-stopped
  ports:
    - ${NGINX_PORT:-80}:80
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf:ro

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  homer:
5    image: b4bz/homer:latest
6    container_name: homer
7    restart: unless-stopped
8    ports:
9      - "${HOMER_PORT:-8080}:8080"
10    environment:
11      - UID=1000
12      - GID=1000
13    volumes:
14      - homer_assets:/www/assets
15
16  healthchecks:
17    image: linuxserver/healthchecks:latest
18    container_name: healthchecks
19    restart: unless-stopped
20    ports:
21      - "${HC_PORT:-8000}:8000"
22    environment:
23      - SITE_ROOT=http://localhost:${HC_PORT:-8000}
24      - SITE_NAME=Healthchecks
25      - SUPERUSER_EMAIL=${ADMIN_EMAIL}
26      - SUPERUSER_PASSWORD=${ADMIN_PASSWORD}
27      - SECRET_KEY=${SECRET_KEY}
28    volumes:
29      - healthchecks_data:/config
30
31  nginx:
32    image: nginx:alpine
33    container_name: homelab-nginx
34    restart: unless-stopped
35    ports:
36      - "${NGINX_PORT:-80}:80"
37    volumes:
38      - ./nginx.conf:/etc/nginx/nginx.conf:ro
39
40volumes:
41  homer_assets:
42  healthchecks_data:
43EOF
44
45# 2. Create the .env file
46cat > .env << 'EOF'
47# Homer Dashboard
48HOMER_PORT=8080
49HC_PORT=8000
50ADMIN_EMAIL=admin@example.com
51ADMIN_PASSWORD=admin_password
52SECRET_KEY=your_secret_key
53NGINX_PORT=80
54EOF
55
56# 3. Start the services
57docker compose up -d
58
59# 4. View logs
60docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/homer-dashboard-stack/run | bash

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

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

homerhealthchecksnginx

Tags

#dashboard#homer#homelab#monitoring

Category

Home Lab & Self-Hosting

Related Recipes

Ad Space