Homepage: The Dashboard Your Homelab Deserves

Your homelab has a dozen services running. Maybe two dozen. Plex for media, Pi-hole for ad blocking, Proxmox for VMs, Portainer for containers, and a growing collection of *arr applications that would make any librarian jealous. Each has its own port, its own bookmark, its own login page you can never remember.

You could keep a text file of URLs like some kind of digital vagrant. Or you could install a dashboard that actually makes sense.

Homepage is the most popular self-hosted dashboard on GitHub for a reason. With over 29,000 stars, it’s not just winning the category—it’s lapping the field. But popularity doesn’t automatically mean quality. Let’s dig into why Homepage has become the go-to choice for homelab enthusiasts and whether it deserves a spot in your stack.

What Is Homepage?

Homepage is a modern, fully static application dashboard built on Next.js. It displays your self-hosted services in a clean, customizable interface with live status information—container stats, bandwidth usage, movie counts, download progress, whatever each service exposes.

The key difference from older dashboards: Homepage generates a static site at build time. No PHP process churning in the background. No database to maintain. Just fast HTML that loads instantly and uses service APIs to pull live data when needed.

Why This Matters

Traditional dashboards like Heimdall run on PHP, querying services in real-time and rendering pages dynamically. Homepage takes a different approach:

1. Build-time generation - The dashboard structure is pre-built
2. Client-side API calls - Your browser fetches live data directly
3. Proxied requests - API keys never leave your server

The result? A dashboard that feels instantaneous while keeping your credentials secure.

Key Features

160+ Service Integrations

Homepage supports more services than any other dashboard—over 160 integrations with live widgets that display real-time data:

Media & Entertainment:

• Plex, Jellyfin, Emby – Now playing, library stats
• Radarr, Sonarr, Lidarr – Queue status, missing items
• Prowlarr, Bazarr – Indexer status, subtitle counts

Download Clients:

• qBittorrent, Transmission – Active downloads, speeds
• SABnzbd, NZBGet – Queue progress
• JDownloader – Download status

Infrastructure:

• Proxmox – VM/container status, resource usage
• Portainer – Container management
• TrueNAS, Unraid – Storage pools, usage

Network:

• Pi-hole, AdGuard Home – DNS queries, blocked domains
• UniFi Controller – Network devices, client counts
• Traefik, Nginx Proxy Manager – Proxy status

Monitoring:

• Uptime Kuma – Service uptime charts
• Grafana – Dashboard metrics
• Glances – System stats

Home Automation:

• Home Assistant – Entity states
• Frigate – Camera feeds, detection counts

Each widget pulls live data without you needing to open the actual service. Your movie library count, current download speed, and container status all visible at a glance.

Docker Integration Done Right

This is where Homepage separates itself from the pack. Instead of manually configuring every service, you can let Docker do the work:

# docker-compose.yml
services:
  plex:
    image: plexinc/pms-docker:latest
    labels:
      - homepage.group=Media
      - homepage.name=Plex
      - homepage.icon=plex.png
      - homepage.href=http://plex.local:32400
      - homepage.description=Media streaming server
      - homepage.widget.type=plex
      - homepage.widget.url=http://plex.local:32400
      - homepage.widget.key=your-plex-token

Add those labels to any container and Homepage automatically discovers and configures it. No YAML editing required. No manual service definitions. The dashboard builds itself from your existing infrastructure.

YAML Configuration (Actually Good)

For services that need more detail or aren’t running in Docker, Homepage uses clean YAML files:

# config/services.yaml
- Media Services:
    - Plex:
        icon: plex.png
        href: http://plex.local:32400
        description: Media streaming server
        widget:
          type: plex
          url: http://plex.local:32400
          key: {{HOMEPAGE_VAR_PLEX_TOKEN}}
    
    - Radarr:
        icon: radarr.png
        href: http://radarr.local:7878
        description: Movie collection manager
        widget:
          type: radarr
          url: http://radarr.local:7878
          key: {{HOMEPAGE_VAR_RADARR_KEY}}

The config structure is intuitive: groups contain services, services have widgets. You can organize by function (Media, Network, Infrastructure) or by location (Living Room, Server Rack, Cloud).

Static Site Generation

Here’s the technical advantage that matters in practice:

Aspect	Homepage	Heimdall	Dashy
Rendering	Static (build-time)	Dynamic (PHP)	Dynamic (Node.js)
Load time	Instant	Slower	Moderate
Server overhead	Minimal	PHP process	Node process
API security	Proxied	Exposed	Mixed

Homepage generates your dashboard once at startup, then serves that static HTML. When you load the page, it’s already built—your browser just fetches live data from the services you’ve configured.

Multi-Host Docker Support

Running Docker on multiple machines? Homepage can monitor them all:

# config/docker.yaml
local-docker:
  host: socket-proxy
  port: 2375

remote-server:
  host: 192.168.1.100
  port: 2375
  tls:
    keyFile: /config/tls/key.pem
    caFile: /config/tls/ca.pem
    certFile: /config/tls/cert.pem

Each Docker host becomes a source for automatic service discovery. Add labels anywhere, see them everywhere.

Homepage vs Heimdall vs Dashy

The three dashboards people actually consider. Here’s how they stack up:

Feature	Homepage	Heimdall	Dashy
GitHub Stars	29,000+	9,000+	24,000+
Live Widgets	160+	~100	60+
Configuration	YAML	GUI	YAML + GUI
Docker Integration	Native auto-discovery	Limited	Basic
Performance	Static generation	PHP-based	Node.js
API Proxy	Yes	No	Mixed
Auth	Via reverse proxy	Via reverse proxy	Built-in optional
Active Development	Very active	Less active	Active

When to Choose Homepage

• You have a Docker-heavy homelab and want auto-discovery
• You want the most service integrations available
• You prefer YAML configuration (version control friendly)
• You care about load time and performance
• You’re already using a reverse proxy for authentication

When to Consider Alternatives

• Heimdall if you want a GUI configuration experience—no YAML required
• Dashy if you need built-in authentication without setting up a separate auth system

But for most homelab setups? Homepage wins on integrations, performance, and Docker native support.

Installation

Docker Compose (Recommended)

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      HOMEPAGE_ALLOWED_HOSTS: homepage.yourdomain.com
      PUID: 1000
      PGID: 1000
    ports:
      - 3000:3000
    volumes:
      - ./config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro  # For Docker integration
    restart: unless-stopped

Create the config directory before starting:

mkdir config
docker compose up -d

Homepage will start on port 3000. The first run creates default configuration files in ./config/.

Docker Socket Security

That docker.sock mount is convenient but a security consideration. Homepage can use a socket proxy instead:

services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy:latest
    environment:
      - CONTAINERS=1
      - IMAGES=1
      - INFO=1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - 2375:2375

  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    environment:
      - HOMEPAGE_DOCKER_HOST=socket-proxy
      - HOMEPAGE_DOCKER_PORT=2375
    depends_on:
      - socket-proxy
    # ... rest of config

This limits Homepage’s Docker access to read-only operations, reducing potential attack surface.

Configuration Deep Dive

Homepage uses separate YAML files for different concerns:

settings.yaml

Global appearance and layout:

title: My Homelab
description: Personal services dashboard
background: /images/background.jpg
theme: dark
color: slate
cardBlur: md

layout:
  Media:
    style: row
    columns: 4
  Infrastructure:
    style: column

services.yaml

Service definitions with widgets:

- Media Services:
    - Plex:
        icon: plex.png
        href: http://plex.local:32400
        widget:
          type: plex
          url: http://plex.local:32400
          key: {{HOMEPAGE_VAR_PLEX_TOKEN}}

- Network:
    - Pi-hole:
        icon: pi-hole.png
        href: http://pihole.local/admin
        widget:
          type: pihole
          url: http://pihole.local
          key: {{HOMEPAGE_VAR_PIHOLE_KEY}}

widgets.yaml

Header widgets for system info:

- openmeteo:
    label: Weather
    latitude: 40.7128
    longitude: -74.0060
    cache: 5

- glances:
    url: http://glances.local:61208
    label: Server Stats
    fields:
      - cpu
      - memory
      - disk

- search:
    provider: google
    focus: true

Environment Variables for Secrets

API keys shouldn’t live in your config files. Use environment variables:

# docker-compose.yml
services:
  homepage:
    environment:
      HOMEPAGE_VAR_PLEX_TOKEN: your-plex-token-here
      HOMEPAGE_VAR_PIHOLE_KEY: your-pihole-key-here

Then reference them in configs with {{HOMEPAGE_VAR_PLEX_TOKEN}}.

Security Considerations

Homepage doesn’t include built-in authentication. This is intentional—the authors expect you to put it behind a reverse proxy like any other internal service.

Best practices:

1. Use Authentik, Authelia, or similar – Handle authentication at the proxy level
2. Set HOMEPAGE_ALLOWED_HOSTS – Prevent host header attacks
3. Use environment variables for secrets – Keep API keys out of config files
4. Consider socket proxy for Docker – Limit container access to read-only
5. Always use HTTPS – TLS termination at your reverse proxy

Homepage proxies all API requests through the server, keeping your service credentials hidden from the browser. This is a meaningful security advantage over dashboards that embed keys in client-side JavaScript.

Why Homepage Wins

The numbers tell part of the story: 29,000+ GitHub stars, 200+ contributors, 1 open issue at the time of writing. But the real advantages are practical:

1. Most integrations – 160+ widgets means your services probably just work
2. Docker native – Auto-discovery via labels is genuinely convenient
3. Static generation – Instant loads, minimal server overhead
4. YAML configuration – Version control friendly, infrastructure-as-code ready
5. Active development – New features and fixes ship regularly
6. Good documentation – gethomepage.dev is comprehensive and searchable

The dashboard category has matured. Homepage represents the current best practice: static-first architecture, extensive integrations, and configuration that fits into modern infrastructure workflows.

Quick Start

1. Create your config directory:

   mkdir -p homepage/config

2. Run with Docker:

   docker run -d \
     --name homepage \
     -p 3000:3000 \
     -v ./config:/app/config \
     -v /var/run/docker.sock:/var/run/docker.sock:ro \
     ghcr.io/gethomepage/homepage:latest

3. Access at http://localhost:3000

4. Add services via Docker labels or by editing config/services.yaml

5. Configure widgets in config/widgets.yaml

6. Customize appearance in config/settings.yaml

The default setup includes helpful examples. Start there, remove what you don’t need, add what you do.

---

Homepage does one thing well: it displays your services with relevant live data. No bloat. No complexity you didn’t ask for. Just a clean dashboard that gets out of your way.

If your homelab has grown past the point where browser bookmarks make sense, give it thirty minutes. The Docker integration means the first version of your dashboard might already be running—you just haven’t labeled your containers yet.