Homepage

Last reviewed Aug 26, 2026 · 791 words

The first thing most people see after starting Homepage is a page reading Host validation failed. Since version 1.0 the container refuses any request whose Host header is not listed in HOMEPAGE_ALLOWED_HOSTS, and the compose snippet in older tutorials does not set it. Add HOMEPAGE_ALLOWED_HOSTS=home.example.com,192.168.1.10:3000 and the dashboard appears. Fix that, mount the config directory, and you have the fastest, most portable start page in the dashboard category: 128 MB of RAM, no database, and a configuration that lives in 4 YAML files you can commit to git.

The compose file that actually works in 2026

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    ports:
      - "3000:3000"
    environment:
      - PUID=1000
      - PGID=1000
      - HOMEPAGE_ALLOWED_HOSTS=home.example.com,192.168.1.10:3000
    volumes:
      - ./config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

PUID and PGID should match the owner of ./config or the container cannot write the starter files it generates on first run. The Docker socket mount is optional and only needed for the container status dots and the label-based discovery below; it is read-only, but read-only on the socket still exposes every container's environment variables to the process, so on anything multi-tenant use a socket proxy container and point Homepage at it over TCP in docker.yaml instead.

Four files, and which one you will actually edit

settings.yaml sets the title, theme, layout, and background. services.yaml is the main event: groups of services, each with a name, icon, URL, description, and optionally a widget. widgets.yaml is the top bar (search box, clock, host resources, weather). bookmarks.yaml is a plain link list. A docker.yaml names socket connections and a kubernetes.yaml does the same for clusters. You will spend 90 percent of your time in services.yaml, and it looks like this:

- Media:
    - Jellyfin:
        icon: jellyfin.png
        href: https://tv.example.com
        description: movies and shows
        widget:
          type: jellyfin
          url: http://jellyfin:8096
          key: "{{HOMEPAGE_VAR_JELLYFIN_KEY}}"

Icons resolve by name against the Dashboard Icons collection, so jellyfin.png needs no path and no download. Changes are picked up live without a restart, which makes the YAML-editing cost lower than the "can intimidate" complaint suggests: edit, save, refresh. There is no web editor and there will not be one; that is a design decision, and it is why the config survives a rebuild of the host when a database-backed dashboard would not.

Widgets want API keys, and git wants none of them

Homepage ships widgets for several hundred services: the arr stack, Proxmox, Portainer, Pi-hole, Uptime Kuma, Immich, Nextcloud, Grafana, and more. Nearly every one needs a key or a password. The right pattern is the one in the snippet above: reference {{HOMEPAGE_VAR_NAME}} in YAML and set HOMEPAGE_VAR_NAME in the container environment (or in a .env file alongside your compose, which you gitignore). {{HOMEPAGE_FILE_NAME}} reads the value from a mounted file for people who use Docker secrets. Commit the YAML, never the .env, and the whole dashboard is reproducible from the repo. The Uptime Kuma widget alone is worth the effort: it puts the up/down count of every monitor on the page you already open first.

Labels instead of YAML for the containers that come and go

For services running on the same host, skip services.yaml and add labels to each container's compose file:

labels:
  - homepage.group=Media
  - homepage.name=Jellyfin
  - homepage.icon=jellyfin.png
  - homepage.href=https://tv.example.com
  - homepage.widget.type=jellyfin
  - homepage.widget.url=http://jellyfin:8096

The service then appears when the container starts and vanishes when it is removed, which is the right behaviour for a lab where things get torn down. I use labels for anything ephemeral and services.yaml for the permanent fixtures and for hosts that are not containers. Homarr is the obvious alternative if you want drag-and-drop editing and a database; Dashy sits between the two with a YAML config plus a UI editor. Homepage wins on speed, footprint, and widget count, and its 32,240 GitHub stars in 4 years say the config-as-code crowd is not small.

What I'd do

Deploy with the compose above, set HOMEPAGE_ALLOWED_HOSTS before anything else, put the config directory in a git repo with .env ignored, and add widgets one at a time as you find yourself checking a service daily. Use labels for containers, YAML for everything else. Back the config up like any other repo. It is the dashboard I have not felt the urge to replace, which for a start page is the highest compliment available.