Homepage

Homepage is a dashboard described entirely in YAML: one file for services, one for bookmarks, one for widgets, one for settings. One container, no database.

Last run on a host 8 Nov 2026

Pinned at v2.7.0 (released 23 Oct 2026) · the newest upstream release

In the upstream images: 0 CRITICAL · 9 HIGH with a published fix — per image

To try it: Docker, nothing else. See Try it locally.

To deploy it behind the proxy: Traefik running and a domain.

Try it locally

On your own machine, with no proxy, domain or certificate. From apps/homepage/:

cp .env.local.example .env.local

mkdir -p volumes/local/config

docker compose -f docker-compose.local.yml --env-file .env.local up -d

Then open http://localhost:3000. Stop it again with the same command and down.

Installation

From apps/homepage/:

1. Copy the environment file and set APP_TRAEFIK_HOST and TZ:

   cp .env.example .env

   Then set APP_BASIC_AUTH_USERS. The route ships with a basic-auth gate, because the stack does not enable Homepage’s own authentication and its configuration holds the API keys of every widget; the placeholder is not a valid hash. Every $ in the hash is doubled for Compose — the command does it, paste the whole line:

   htpasswd -nbB ops 'the-password' | sed -e 's/\$/\$\$/g'

2. Create the configuration from the examples:

   cd config
   for f in *.example.yaml; do cp "$f" "${f/.example/}"; done
   cd ..

3. Start it:

   docker compose up -d

4. Open https://<APP_TRAEFIK_HOST>.

Further configuration is editing the files in config/. Homepage reloads on change, so no restart is needed.

Verify

docker compose ps                       # one service, healthy
curl -sSI https://<APP_TRAEFIK_HOST>/                         # 401 — the gate asks
curl -fsSI -u ops https://<APP_TRAEFIK_HOST>/  # asks for the password; 200 with it

Then add a service to config/services.yaml and watch it appear without a restart. That confirms the mount and the reload together.

Going further

Discovering services from Docker

Homepage can read labels on other containers and show live container state, which needs access to the Docker daemon. A direct socket mount gives it read-write control of Docker, so any code-execution bug in Homepage becomes control of the host.

Route it through a filtering socket proxy exposing only what it needs — containers, networks and info — and point Homepage’s Docker configuration at the proxy instead. Dockhand shows the pattern.

Backup

Nothing to back up, provided the configuration is committed. There is no database and no state the container creates on its own.

The one thing to check before relying on that: Homepage writes its defaults into config/ on first start, so confirm the running configuration matches what is in the repository. An uncommitted local edit is the only thing here a restore would lose.

Updates

1. Read the release notes. The step from 1.x to 2.x changed the configuration format and added Homepage’s own authentication.

2. Commit the current configuration.

3. Raise APP_TAG in .env, then:

   docker compose pull && docker compose up -d

4. Load the dashboard. A configuration key removed upstream shows up as a missing section rather than as a failed start.

Troubleshooting

A section is missing after an update. A configuration key changed upstream. Compare your file against the current example in config/.

Changes have no effect. The file is not where the container reads it, or the YAML does not parse. Check docker compose logs homepage-app.

Container state does not appear. Homepage has no route to the Docker daemon. See above.

Repository files

• apps/homepage/README.md — setup, security model, the Docker options
• apps/homepage/UPSTREAM.md — source and upgrade checklist

Official sources

• Homepage documentation