Once you’re running more than a handful of services, you need a single place to see everything. What’s running? What’s the status? Where’s the link again?
Homepage is a modern, fast, self-hosted dashboard that gives you a clean overview of your entire homelab. It pulls live stats from your services, shows system info, and organizes all your bookmarks in one place.
Why Homepage Over Other Dashboards?
There are several self-hosted dashboards — Dashy, Homarr, Heimdall, Organizr. Homepage stands out for:
- Service widgets — live data from 100+ services (Sonarr, Radarr, Plex, Portainer, Pi-hole, etc.)
- Extremely fast — static generation, no database
- YAML config — version-controllable, no clicking through UIs
- Beautiful by default — looks great without tweaking
- Lightweight — minimal resource usage
Docker Setup
mkdir -p ~/homepage && cd ~/homepage
mkdir config
# docker-compose.yml
version: "3.8"
services:
homepage:
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
restart: unless-stopped
ports:
- "3000:3000"
volumes:
- ./config:/app/config
- /var/run/docker.sock:/var/run/docker.sock:ro # Optional: Docker integration
environment:
PUID: 1000
PGID: 1000
docker compose up -d
Visit http://your-server:3000 — you’ll see a blank dashboard ready to configure.
Configuration Files
Homepage uses YAML files in the config directory. There are four main files:
services.yaml — Your Service Links
This is where you add all your self-hosted services:
# config/services.yaml
- Media:
- Plex:
icon: plex.png
href: http://192.168.1.100:32400
description: Media streaming
widget:
type: plex
url: http://192.168.1.100:32400
key: your-plex-token
- Jellyfin:
icon: jellyfin.png
href: http://192.168.1.100:8096
description: Free media streaming
- Infrastructure:
- Portainer:
icon: portainer.png
href: http://192.168.1.100:9000
description: Docker management
widget:
type: portainer
url: http://192.168.1.100:9000
env: 2
key: your-portainer-api-key
- Pi-hole:
icon: pi-hole.png
href: http://192.168.1.100:80/admin
description: DNS ad blocking
widget:
type: pihole
url: http://192.168.1.100
key: your-pihole-api-key
- Productivity:
- Nextcloud:
icon: nextcloud.png
href: https://cloud.yourdomain.com
description: File sync and share
- Paperless-ngx:
icon: paperless-ngx.png
href: http://192.168.1.100:8000
description: Document management
- Vaultwarden:
icon: vaultwarden.png
href: https://vault.yourdomain.com
description: Password manager
widgets.yaml — System Information
Show system stats at the top of your dashboard:
# config/widgets.yaml
- resources:
cpu: true
memory: true
disk: /
cputemp: true
uptime: true
- search:
provider: google
target: _blank
- datetime:
text_size: xl
format:
dateStyle: long
timeStyle: short
hour12: true
bookmarks.yaml — Quick Links
For services you don’t need widgets for:
# config/bookmarks.yaml
- Developer:
- GitHub:
- abbr: GH
href: https://github.com
- Stack Overflow:
- abbr: SO
href: https://stackoverflow.com
- Social:
- Reddit:
- abbr: RE
href: https://reddit.com/r/selfhosted
- Hacker News:
- abbr: HN
href: https://news.ycombinator.com
settings.yaml — Theme and Layout
# config/settings.yaml
title: My Homelab
theme: dark
color: slate
layout:
Media:
style: row
columns: 3
Infrastructure:
style: row
columns: 3
Productivity:
style: row
columns: 4
headerStyle: clean
quicklaunch:
searchDescriptions: true
hideInternetSearch: false
hideVisitURL: false
Service Widgets That Matter
Homepage supports widgets for 100+ services. Here are the most useful ones:
Docker Integration
Mount the Docker socket and Homepage auto-discovers containers:
# config/docker.yaml
local:
socket: /var/run/docker.sock
Then add labels to your containers:
# In any docker-compose.yml
services:
myapp:
labels:
- homepage.group=Media
- homepage.name=My App
- homepage.icon=myapp.png
- homepage.href=http://192.168.1.100:8080
- homepage.description=My cool app
Containers appear on the dashboard automatically.
Uptime Kuma Widget
If you run Uptime Kuma for monitoring:
- Uptime Kuma:
icon: uptime-kuma.png
href: http://192.168.1.100:3001
widget:
type: uptimekuma
url: http://192.168.1.100:3001
slug: default
Sonarr / Radarr Widgets
See upcoming shows and movies:
- Sonarr:
icon: sonarr.png
href: http://192.168.1.100:8989
widget:
type: sonarr
url: http://192.168.1.100:8989
key: your-api-key
- Radarr:
icon: radarr.png
href: http://192.168.1.100:7878
widget:
type: radarr
url: http://192.168.1.100:7878
key: your-api-key
Customizing the Look
Custom CSS
Create config/custom.css for tweaks:
/* Translucent cards */
.service {
backdrop-filter: blur(10px);
background: rgba(0, 0, 0, 0.3) !important;
}
/* Bigger icons */
.service-icon {
width: 48px !important;
height: 48px !important;
}
Background Image
Add a background in settings.yaml:
background:
image: https://images.unsplash.com/photo-1506905925346-21bda4d32df4
blur: sm
opacity: 50
Tips for a Clean Dashboard
- Group by function, not by server. “Media”, “Productivity”, “Infrastructure” — not “Server 1”, “Server 2”
- Only add what you use daily. Less is more. Put rarely-used services in bookmarks
- Use widgets selectively. Not everything needs live stats — just the services where status matters
- Keep config in git. Your YAML files are your dashboard — version control them
Accessing Remotely
Put Homepage behind your reverse proxy like any other service:
server {
server_name home.yourdomain.com;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
Consider adding authentication (Authelia, Authentik, or basic auth) since your dashboard reveals your entire infrastructure.
Wrapping Up
Homepage takes about 15 minutes to set up and saves you from constantly typing IP addresses and port numbers. More importantly, it gives you a single view of your entire homelab — what’s running, what’s healthy, and where everything lives.
Start simple with a few services, then add widgets and bookmarks as your lab grows. The YAML configuration means you can version control your dashboard and rebuild it instantly on any server.