Homepage: the start page for your home server (and the “Host validation failed” error)

Once you have more than four or five services at home, you start forgetting which port each one is on. Homepage fixes that: a start page with all your links grouped, the status of each service and the machine’s resources (CPU, RAM, disk, temperature).

I run it on port 80 of the Raspberry Pi, so I type the IP into the browser and everything is there.

Installing with Docker

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    restart: unless-stopped
    environment:
      HOMEPAGE_ALLOWED_HOSTS: "192.168.1.50,my-pi,my-pi.local,localhost"
      PUID: "1000"
      PGID: "991"   # docker group, so it can read docker.sock
    ports: ["80:3000"]
    volumes:
      - ./homepage:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /:/host:ro

Three mounts, three jobs:

• ./homepage → the configuration, as YAML files you edit and that reload automatically.
• docker.sock read-only → to see whether each container is running.
• / as /host read-only → to show free disk space on the Pi.

The links: services.yaml

Each group is a list, and each service has its icon, link and description:

- Services:
    - Gitea:
        icon: gitea.png
        href: http://192.168.1.50:3000
        description: Git repositories
        server: pi
        container: gitea
    - Uptime Kuma:
        icon: uptime-kuma.png
        href: http://192.168.1.50:3001
        description: Monitoring and alerts
        server: pi
        container: uptime-kuma
- Infrastructure:
    - NAS:
        icon: synology.png
        href: http://192.168.1.60:5000
        description: NAS admin panel
        ping: 192.168.1.60

• container: links to Docker and shows whether it’s running and how much CPU and RAM it uses.
• ping: is for machines that aren’t containers, like the NAS or the router.
• siteMonitor: http://... checks a URL and shows how long it takes to respond. I use it for services not in Docker.
• Icons like gitea.png come from a huge collection Homepage already knows. mdi-name also works for Material Design icons.

Layout: settings.yaml

title: Home
theme: dark
color: slate
language: en
target: _blank
layout:
  Services:
    style: row
    columns: 4

style: row with columns lays each group out in rows. target: _blank opens links in a new tab.

Error 1: “Host validation failed”

Recent versions of Homepage only respond to addresses you allow. If you use one that isn’t on the list, you get an error page and the logs show:

error: Host validation failed for: 127.0.0.1

Fix: add every name or IP you use (local IP, machine name, Tailscale name…) to HOMEPAGE_ALLOWED_HOSTS, comma-separated, and recreate the container.

Error 2: container status doesn’t show

If services appear without the Docker indicator, it’s almost always a socket permissions issue. The container user (PUID/PGID) has to belong to the docker group. Check that group’s number on your machine:

getent group docker

and put it in PGID. Also, create docker.yaml in the config:

pi:
  socket: /var/run/docker.sock

The name pi is what you then use in each service’s server: pi.

A warning about docker.sock

Even read-only, the Docker socket gives access to a lot of information about your system. Only use it with containers you trust, and never expose Homepage to the Internet. Mine is only reachable from home or over VPN.

So why did I build another dashboard?

Homepage is great as a launcher: links and basic status. For things that are just mine (to-dos, backups, deadlines) I built a second dashboard in Python. The two complement each other, and Homepage links to the other one.