Homepage Dashboard

What You'll Build

Homepage is a start page for your server: one tile per app, showing whether it's running and live stats from many of them (Jellyfin streams, Pi-hole blocked queries, Immich photo counts). Set it as your browser's home page and you'll never type an IP again.

Port: 3000 · Time: 30 minutes · Difficulty: Easy

Step 1: Start Homepage

mkdir -p ~/stacks/homepage/config && cd ~/stacks/homepage
nano compose.yaml

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      # REQUIRED: every address you'll open Homepage with (comma-separated)
      HOMEPAGE_ALLOWED_HOSTS: "192.168.1.50:3000,home.home.example.com"
      PUID: 1000
      PGID: 1000
    volumes:
      - ./config:/app/config                          # your YAML settings
      - /var/run/docker.sock:/var/run/docker.sock:ro  # read-only: show container status

docker compose up -d

Open http://192.168.1.50:3000. You'll see a sample dashboard. The first start also created example files in ~/stacks/homepage/config/.

Step 2: Add Your Apps (services.yaml)

nano ~/stacks/homepage/config/services.yaml

# Each top-level item is a group (a column of tiles on the page)
- Media:
    - Jellyfin:
        icon: jellyfin.png                          # icons come from a built-in library
        href: https://jellyfin.home.example.com     # where clicking the tile goes
        description: Movies & TV
        server: my-docker                           # defined in docker.yaml (Step 3)
        container: jellyfin                         # shows running/stopped
    - Navidrome:
        icon: navidrome.png
        href: https://music.home.example.com
        description: Music streaming

- Home:
    - Immich:
        icon: immich.png
        href: https://photos.home.example.com
        description: Photos
    - Vaultwarden:
        icon: vaultwarden.png
        href: https://vault.home.example.com
        description: Passwords

- Admin:
    - Portainer:
        icon: portainer.png
        href: https://portainer.home.example.com
        server: my-docker
        container: portainer

Save — Homepage reloads automatically. YAML is picky: use spaces, never tabs, and keep the indentation exact.

Step 3: Container Status and System Widgets

nano ~/stacks/homepage/config/docker.yaml

# Lets tiles show container status via the mounted Docker socket
my-docker:
  socket: /var/run/docker.sock

nano ~/stacks/homepage/config/widgets.yaml

# The row of info along the top of the page
- resources:
    cpu: true
    memory: true
    disk: /            # add more lines for other drives, e.g. - disk: /mnt/data
- datetime:
    format:
      timeStyle: short
- search:
    provider: duckduckgo
    target: _blank

Step 4: Live App Widgets (Example: Pi-hole)

Many apps can show live numbers on their tile. Each needs an API key or password from that app:

    - Pi-hole:
        icon: pi-hole.png
        href: http://192.168.1.50:8081/admin
        widget:
          type: pihole
          url: http://192.168.1.50:8081
          version: 6
          key: your-pihole-app-password     # Pi-hole → Settings → Web interface/API → App password

Homepage's documentation lists the widget settings for each app. Keep keys out of screenshots — they're passwords.

Step 5: Make It Your Browser's Home Page

1. Add a proxy host in Nginx Proxy Manager: home.home.example.com → 192.168.1.50 port 3000.
2. Make sure that name is in HOMEPAGE_ALLOWED_HOSTS, then docker compose up -d.
3. Set it as your home page / new-tab page in your browser.

Troubleshooting

• "Host validation failed" — the address in your browser isn't listed in HOMEPAGE_ALLOWED_HOSTS. Add it exactly (including :3000 if you use the port).
• Page shows an error after editing YAML — an indentation mistake. Check the logs: docker compose logs homepage.
• Widget says "API Error" — wrong key or URL. Use the app's internal address (IP:port), not the public name.

What's Next?

Get a phone alert the moment any app goes down: