TL;DR — Quick Summary

Deploy Homepage as a self-hosted dashboard for your services. Configure widgets, health checks, bookmarks, and integrate with Docker, Proxmox, and Portainer.

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

Service Widget Type Data Shown
Proxmox proxmox VMs, CPU, RAM, storage
Portainer portainer Container count, status
Pi-hole pihole Queries blocked, % blocked
Plex tautulli Active streams, library stats
Uptime Kuma uptimekuma Service status, uptime %

Troubleshooting

Problem Solution
Services not showing Check services.yaml syntax (YAML is indent-sensitive)
Docker discovery not working Verify 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 loading Use icon names from the Dashboard Icons project
Permission denied on Docker socket Add 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.