Why Homepage?

You’re running 20+ self-hosted services. Remembering which port is which is painful. Homepage solves this:

  • Service dashboard — All your apps in one organized view.
  • Live status checks — See which services are up or down at a glance.
  • Resource widgets — CPU, RAM, disk, and network stats.
  • Docker auto-discovery — Add labels to containers, Homepage finds them.
  • 100+ integrations — Plex, Sonarr, Pi-hole, Proxmox, Portainer, and more.

Prerequisites

  • Docker with docker-compose.
  • At least 128 MB RAM.

Step 1: Deploy with Docker Compose

# docker-compose.yml
version: "3"
services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - "3000:3000"
    volumes:
      - ./config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: always
mkdir -p config
docker compose up -d

Step 2: Configure Services (config/services.yaml)

- Infrastructure:
    - Proxmox:
        href: https://proxmox.home.lab:8006
        icon: proxmox.png
        description: Hypervisor
        widget:
          type: proxmox
          url: https://proxmox.home.lab:8006
          username: api@pam!homepage
          password: your-api-token

    - Portainer:
        href: https://portainer.home.lab:9443
        icon: portainer.png
        description: Container management

- Media:
    - Plex:
        href: https://plex.home.lab
        icon: plex.png
        description: Media server

Step 3: Add Widgets (config/widgets.yaml)

- resources:
    cpu: true
    memory: true
    disk: /

- search:
    provider: google
    target: _blank

- datetime:
    text_size: xl
    format:
      dateStyle: long
      timeStyle: short

Step 4: Docker Auto-Discovery

Add labels to any container’s docker-compose.yml:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    labels:
      - homepage.group=Monitoring
      - homepage.name=Uptime Kuma
      - homepage.icon=uptime-kuma.png
      - homepage.href=http://server:3001
      - homepage.description=Uptime monitoring

Homepage automatically discovers labeled containers.

Widget Integration Examples

ServiceWidget TypeData Shown
ProxmoxproxmoxVMs, CPU, RAM, storage
PortainerportainerContainer count, status
Pi-holepiholeQueries blocked, % blocked
PlextautulliActive streams, library stats
Uptime KumauptimekumaService status, uptime %

Troubleshooting

ProblemSolution
Services not showingCheck services.yaml syntax (YAML is indent-sensitive)
Docker discovery not workingVerify Docker socket is mounted as read-only; check container labels
Widget shows “Error”Verify the service URL and API credentials in the widget config
Icons not loadingUse icon names from the Dashboard Icons project
Permission denied on Docker socketAdd the homepage container user to the docker group

Summary

  • Single pane of glass for all self-hosted services.
  • Docker auto-discovery via container labels.
  • 100+ widget integrations for live service data.
  • YAML-based config — no database, easy to version control.