Homepage dashboard with login

The quadlet files

Every quadlet file below passes podman's quadlet generator and systemd-analyze verify on podman 5.0 and the current release. Personal values are placeholders: replace example.com, /srv/... paths and the time zone with your own.

[Unit]
Description=Homepage start page with live widgets
StartLimitIntervalSec=0
After=network-online.target

[Container]
Image=ghcr.io/gethomepage/homepage:latest
ContainerName=homepage
AutoUpdate=registry
Environment=TZ=Etc/UTC
# Homepage answers 400 to any Host header not listed here, including its health check.
Environment=HOMEPAGE_ALLOWED_HOSTS=home.example.com,10.0.0.10:3010
Environment=LOG_TARGETS=stdout
# API keys and the login come from drop-ins in homepage.container.d/, as podman secrets.
# Host port 3010: 3000 is often taken (AdGuard Home's setup page uses it).
PublishPort=3010:3000
Volume=homepage.volume:/app/config:Z
# Disk usage of a NAS for the resources widget. rslave: shares that mount after
# Homepage started still show up.
Volume=/mnt:/nas:ro,rslave
# No docker or podman socket: status comes from siteMonitor and each app's own API.
HealthCmd=wget -q -O /dev/null http://127.0.0.1:3000/api/healthcheck
HealthInterval=1m
HealthTimeout=10s
HealthRetries=3
HealthStartPeriod=1m
HealthOnFailure=kill

[Service]
Restart=always
RestartSec=30

[Install]
WantedBy=default.target

[Unit]
Description=Homepage config: settings, services, widgets and bookmarks YAML

[Volume]
VolumeName=homepage

# Every podman secret homepage-<name> becomes the variable HOMEPAGE_VAR_<NAME>,
# which services.yaml reads as {{HOMEPAGE_VAR_<NAME>}}.
[Container]
Secret=homepage-jellyfin-key,type=env,target=HOMEPAGE_VAR_JELLYFIN_KEY
Secret=homepage-radarr-key,type=env,target=HOMEPAGE_VAR_RADARR_KEY
Secret=homepage-sonarr-key,type=env,target=HOMEPAGE_VAR_SONARR_KEY
Secret=homepage-ntfy-token,type=env,target=HOMEPAGE_VAR_NTFY_TOKEN

# Homepage's built-in login: one password, no user name.
[Container]
Environment=HOMEPAGE_AUTH_ENABLED=true
# The one URL you open Homepage at; the login redirects back to it.
Environment=HOMEPAGE_EXTERNAL_URL=https://home.example.com
Secret=homepage-auth-secret,type=env,target=HOMEPAGE_AUTH_SECRET
Secret=homepage-auth-password,type=env,target=HOMEPAGE_AUTH_PASSWORD

# href: what your browser opens. widget url and siteMonitor: what the container calls.
# Keys only as {{HOMEPAGE_VAR_*}}, never as values.
- Media:
    - Jellyfin:
        icon: jellyfin.svg
        href: https://jellyfin.example.com
        description: Media server
        siteMonitor: http://host.containers.internal:8096/health
        widget:
          type: jellyfin
          url: http://host.containers.internal:8096
          key: "{{HOMEPAGE_VAR_JELLYFIN_KEY}}"
          # Version 2 sends the key in a header. Version 1 puts it in the URL, and
          # Homepage logs that URL when a widget call fails.
          version: 2
          enableBlocks: true
          enableNowPlaying: true
    - Radarr:
        icon: radarr.svg
        href: https://radarr.example.com
        description: Movies
        siteMonitor: http://host.containers.internal:7878/ping
        widget:
          type: radarr
          url: http://host.containers.internal:7878
          key: "{{HOMEPAGE_VAR_RADARR_KEY}}"
          enableQueue: true
    - Sonarr:
        icon: sonarr.svg
        href: https://sonarr.example.com
        description: TV series
        siteMonitor: http://host.containers.internal:8989/ping
        widget:
          type: sonarr
          url: http://host.containers.internal:8989
          key: "{{HOMEPAGE_VAR_SONARR_KEY}}"
          enableQueue: true
- Monitoring:
    - Gatus:
        icon: gatus.svg
        href: https://status.example.com
        description: Uptime checks
        widget:
          type: gatus
          url: http://host.containers.internal:8084
    - ntfy:
        icon: ntfy.svg
        href: https://ntfy.example.com
        description: Latest alert
        siteMonitor: http://host.containers.internal:2586/v1/health
        widget:
          type: ntfy
          url: http://host.containers.internal:2586
          topic: homelab-alerts
          key: "{{HOMEPAGE_VAR_NTFY_TOKEN}}"

home.example.com {
	reverse_proxy 10.0.0.10:3010
}

Why is it built this way?

What it is. Homepage is a start page for your server: one tile per service, with live numbers such as the download queue, what is playing in Jellyfin and the latest ntfy alert. It is configured entirely in YAML.

Secrets as placeholders. Homepage replaces {{HOMEPAGE_VAR_RADARR_KEY}} in services.yaml with the environment variable of that name. The drop-in 10-secrets.conf fills those variables from podman secrets, so the YAML holds no keys and can be shared or committed. Quadlet merges every file in homepage.container.d/ into the container, so the secrets stay out of the main file.

The built-in login. 20-auth.conf turns on Homepage's own password login. The signing secret is random; the password is yours. Put the page behind Caddy at one fixed URL and set HOMEPAGE_EXTERNAL_URL to exactly that URL.

Read-only accounts. Give widgets the least access that works: a read-only ntfy user that may only read the alert topic (see the ntfy example), and a read-only local account for network controllers. Never use an admin login for a dashboard widget.

Caddy in front of Homepage

The name in the site block must also be in HOMEPAGE_ALLOWED_HOSTS; that is the most common reason for a 400 error behind a proxy. The Caddyfile generator writes the block.

Check that it works

systemctl --user status homepage.service
# 200 with an allowed Host header, 400 without
curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: 10.0.0.10:3010' http://127.0.0.1:3010/api/healthcheck
# which secrets the container gets (names only, never values)
podman inspect homepage --format '{{range .Config.CreateCommand}}{{.}} {{end}}' | grep -o -- '--secret [a-z-]*'
journalctl --user -u homepage.service -n 30

Gatus adds history and alerts to the up or down dots. For rootless services in general, see rootless podman.

How do I start it?

Run these as your normal user, not as root. Quadlet reads ~/.config/containers/systemd/ for user services.

mkdir -p ~/.config/containers/systemd/homepage.container.d
# one secret per API key: copy each key from the app (Settings, General) and paste it
for s in jellyfin-key radarr-key sonarr-key ntfy-token; do
  read -rs -p "$s: " v && echo && printf '%s' "$v" | podman secret create "homepage-$s" -
done; unset v
# the login: a random signing secret and your password
openssl rand -hex 32 | tr -d '\n' | podman secret create homepage-auth-secret -
read -rs -p 'Homepage password: ' v && echo && printf '%s' "$v" | podman secret create homepage-auth-password - && unset v
systemctl --user daemon-reload
systemctl --user start homepage.service
cp services.yaml "$(podman volume inspect homepage --format '{{.Mountpoint}}')/"
# open https://home.example.com and log in

Check the result with systemctl --user status and the logs with journalctl --user -u followed by the service name. To turn a docker-compose file of your own into files like these, use the compose to quadlet converter.

Common mistakes

Frequently asked questions