Homepage Dashboard

beginner

Modern application dashboard.

Overview

Homepage is a modern, self-hosted application dashboard designed to centralize access to your homelab services and applications. Originally developed to replace bookmark-heavy browser setups, Homepage has evolved into a comprehensive dashboard solution that automatically discovers Docker containers, integrates with over 100 different services through widgets, and provides real-time status monitoring. The application focuses on simplicity and visual appeal while maintaining powerful customization capabilities through YAML configuration files. This deployment leverages Homepage's Docker integration capabilities by mounting the Docker socket, enabling automatic service discovery and container status monitoring. The configuration uses persistent volumes to maintain your custom dashboard layouts, service definitions, and widget configurations across container restarts. Homepage's widget system can pull live statistics from services like Plex, Sonarr, Radarr, Proxmox, pfSense, and numerous other homelab applications, creating a unified monitoring interface. Homelab enthusiasts, system administrators managing multiple services, and anyone running self-hosted applications will find this dashboard invaluable for organizing and monitoring their infrastructure. The combination of automatic Docker discovery, extensive service integrations, and customizable layouts makes Homepage particularly suited for environments where multiple containerized services need centralized access and monitoring.

Key Features

Automatic Docker container discovery through socket mounting with real-time status indicators
100+ pre-built service widgets with live statistics for popular homelab applications
Customizable grid-based layout with drag-and-drop service organization
Built-in web search integration with configurable search engines and providers
Bookmark management system with categorization and custom icons
Service health monitoring with uptime checks and response time metrics
Dark and light theme support with customizable color schemes
YAML-based configuration system for services, widgets, and application settings

Common Use Cases

1Homelab dashboard centralizing access to Plex, *arr applications, and network monitoring tools
2Development environment hub providing quick access to local services, databases, and testing tools
3Small office dashboard displaying internal applications, documentation, and shared resources
4Personal productivity center combining bookmarks, weather widgets, and frequently used web applications
5System administrator console for monitoring server status, container health, and service availability
6Family media center interface providing easy access to streaming services and shared applications
7Team workspace dashboard organizing project tools, documentation, and collaborative platforms

Prerequisites

Docker Engine with Docker Compose support installed and running
Minimum 512MB RAM available for the Homepage container
Port 3000 available on the host system for web interface access
Read access to Docker socket for automatic container discovery features
Basic understanding of YAML syntax for service and widget configuration
Network connectivity to external services if using API-based widgets

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

docker-compose.yml

1services: 
2  homepage: 
3    image: ghcr.io/gethomepage/homepage:latest
4    container_name: homepage
5    restart: unless-stopped
6    volumes: 
7      - homepage_config:/app/config
8      - /var/run/docker.sock:/var/run/docker.sock:ro
9    ports: 
10      - "3000:3000"
11
12volumes: 
13  homepage_config:

.env Template

.env

1# No additional config needed

Usage Notes

1Docs: https://gethomepage.dev/
2Access at http://localhost:3000
3Config files in volume: services.yaml, widgets.yaml, settings.yaml
4100+ service widgets with live stats (Docker, Proxmox, *arr, etc.)
5Docker socket gives automatic container discovery
6Customizable with bookmarks, search, and status indicators

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  homepage:
5    image: ghcr.io/gethomepage/homepage:latest
6    container_name: homepage
7    restart: unless-stopped
8    volumes:
9      - homepage_config:/app/config
10      - /var/run/docker.sock:/var/run/docker.sock:ro
11    ports:
12      - "3000:3000"
13
14volumes:
15  homepage_config:
16EOF
17
18# 2. Create the .env file
19cat > .env << 'EOF'
20# No additional config needed
21EOF
22
23# 3. Start the services
24docker compose up -d
25
26# 4. View logs
27docker 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/homepage-dashboard/run | bash

Troubleshooting

Homepage shows 'No services configured' message: Create or modify services.yaml in the config volume with your service definitions and restart the container
Docker containers not appearing in automatic discovery: Verify Docker socket mount permissions and ensure the Homepage container can read /var/run/docker.sock
Service widgets showing 'Error' or no data: Check API endpoints, authentication credentials, and network connectivity to target services in widgets.yaml
Dashboard layout changes not persisting: Confirm homepage_config volume is properly mounted and writable by the container user
Port 3000 already in use error: Change the host port mapping in docker-compose.yml or stop the conflicting service
Bookmark icons not displaying: Verify icon URLs are accessible or use base64-encoded icons in the bookmarks configuration

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

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

Components

homepage

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download