Homepage

What it does here

Homepage is the front page of the box: a tile for each service, each showing whether its container is running.

From the manual

Canonical setup

One container with a config folder, plus the Docker socket for live status. Services are described in YAML files in that folder.

Upstream: Homepage: Docker installation.

Edited for this build

In this build

Config under /srv/stacks/homepage/configOwned by you, so tiles can be edited without sudo.
Config written before the first startHomepage fills an empty folder with its own placeholder config.
HOMEPAGE_ALLOWED_HOSTS setHomepage refuses hostnames it hasn't been told about.
The socket mounted read-onlyStatus only.
127.0.0.1:3002 outside, 3000 insideCaddy serves it as home.dev.tailnet.example.

/srv/stacks/homepage/docker-compose.yml

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    restart: unless-stopped
    ports:
      - "127.0.0.1:3002:3000"
    volumes:
      - /srv/stacks/homepage/config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - HOMEPAGE_ALLOWED_HOSTS=home.dev.tailnet.example

config/docker.yaml

my-docker:
  socket: /var/run/docker.sock

config/services.yaml

- Source Control:
    - Forgejo:
        href: https://git.dev.tailnet.example
        server: my-docker
        container: forgejo
- Dashboards:
    - Dockge:
        href: https://dockge.dev.tailnet.example
        server: my-docker
        container: dockge
    - Beszel:
        href: https://metrics.dev.tailnet.example
        server: my-docker
        container: beszel
    - Uptime Kuma:
        href: https://status.dev.tailnet.example
        server: my-docker
        container: uptime-kuma

Write both files, then docker compose up -d. Homepage reloads valid config on its own and doesn't overwrite files that exist. An empty config/bookmarks.yaml drops the default bookmarks.

Where it breaks

Seams

Where this meets the rest of the build. Each one leads with what you will actually see.

An empty config folder meets the first start

SymptomMy First Group, and bookmarks you didn't add

Homepage wrote its defaults before your files existed. Overwrite services.yaml and docker.yaml with yours and docker restart homepage.

A new hostname meets Homepage

Symptom403 on home.dev.tailnet.example

The host isn't in HOMEPAGE_ALLOWED_HOSTS. Add it and recreate the container.

Root-owned config meets your editor

Symptompermission denied editing services.yaml

If Homepage created the files, they belong to root. sudo chown -R youruser:youruser /srv/stacks/homepage/config once.

Verify

https://home.dev.tailnet.example loads with your groups, and each tile shows its container as running.

Corrections and updates

17 Oct 2026First written.