Homer: a static YAML dashboard for your self-hosted services

The problem Homer solves: a bookmark page you edit in one file

Anyone running a handful of self-hosted services ends up with the same problem. The URLs live in browser bookmarks, a notes file, or someone's memory. Homer replaces that with a single page listing your services, grouped and searchable, and it keeps the source of truth in one YAML file rather than a database. The README describes it as a "dead simple static HOMepage for your servER to keep your services on hand, from a simple yaml configuration file".

The intended user is a homelab operator or a small team that wants a landing page for internal tools. The project is a static site: Vue 3, Bulma and Font Awesome are compiled into a bundle by Vite, and the only runtime input is assets/config.yml. There is no server-side component beyond the web server that hands out the files. That is the whole design, and it explains both the low maintenance cost and the ceiling on what the dashboard can show.

How the YAML config becomes a rendered dashboard

The build produces a static html/js bundle. At load time the front end reads assets/config.yml, which is not compiled into the bundle, and renders cards from it. This is why the Docker instructions bind mount a host directory to /www/assets: the config file stays outside the image, so you can edit it and reload the page without rebuilding or restarting anything.

The README lists the features this rendering supports: multi pages and item grouping, fuzzy search, theme customization, and keyboard shortcuts. The documented shortcuts are / to start searching, Escape to stop, Enter to open the first matching result while respecting the bookmark's _target property, and Alt or Option plus Enter to open the first result in a new tab. Cards can be extended through what the README calls smart cards, documented in docs/customservices.md, but that documentation is not reproduced in the README, so the exact contract for a custom service lives there.

One constraint is easy to miss. The README states plainly that Homer is meant to be served by an HTTP server and will not work if you open index.html directly over the file:// protocol. If you plan to keep the build on a shared drive and open it locally, that plan fails.

Installing Homer with Docker and a first config edit

The container is the shortest path. The README's docker run example binds a host config directory to /www/assets, publishes port 8080, and sets a restart policy. Create the host directory first, because Docker will not create a useful mount for you.

mkdir -p /path/to/config/dir
docker run -d \
  --name homer \
  -p 8080:8080 \
  --mount type=bind,source="/path/to/config/dir",target=/www/assets \
  --restart=unless-stopped \
  b4bz/homer:latest

After the container starts, open http://localhost:8080. The README notes that the container runs as uid and gid 1000 by default, so if your host directory is owned by another user, add --user <your-UID>:<your-GID> to that command. The environment variable INIT_ASSETS defaults to 1 and installs an example configuration plus assets such as favicons; it needs the config directory to be writable by the container user.

The docker-compose form is equivalent and easier to keep in version control. The compose file in the README sets the same mount, port and user, and adds INIT_ASSETS explicitly.

services:
  homer:
    image: b4bz/homer
    container_name: homer
    volumes:
      - /path/to/config/dir:/www/assets
    ports:
      - 8080:8080
    user: 1000:1000
    environment:
      - INIT_ASSETS=1
    restart: unless-stopped

If you prefer no container, the release page offers homer.zip. The README's steps download it, unzip it, copy assets/config.yml.dist to assets/config.yml, and serve the directory with any web server.

wget https://github.com/bastienwirtz/homer/releases/latest/download/homer.zip
unzip homer.zip -d homer
cd homer
cp assets/config.yml.dist assets/config.yml
pnpx http-server

The last line is only a local preview; the README also mentions python -m http.server 8010 as an alternative. Two other environment variables matter in deployment: SUBFOLDER, which you set to a path such as /homer when hosting under a subpath, and PORT, which changes the internal port from 8080. IPV6_DISABLE, set to 1, turns off IPv6 listening. Building from source is pnpm install followed by pnpm build, with the output in /dist.

What Homer cannot show you

Homer renders what you write. It does not poll your services, and nothing in the README describes a status indicator, an uptime check, or an API that reports whether a service is reachable. If a container is down, the card still looks the same. Anyone expecting a live health overview will be disappointed, and the correct response is to pair Homer with a monitoring tool rather than to look for a hidden setting.

There is also no authentication layer in the documented setup. The container serves static files through lighttpd; the README does not describe user accounts, sessions, or per-user visibility. A Homer instance placed on a public network exposes the list of services and their internal hostnames to anyone who loads the page. The usual answer is to keep it behind a VPN or an authenticating reverse proxy, but that is a deployment decision you make, not a feature the project provides.

A third limitation is the config format itself. Everything is hand-written YAML, so a typo produces a broken card or a blank page rather than a helpful error. There is no admin UI and no validation step in the documented workflow. The repository does include a .schema/ directory, which suggests schema files for the configuration exist, but the README does not explain how to use them, so editor-side validation is something you would have to investigate in the repository.

Homer against Homepage and Dashy

The closest alternatives in the self-hosted dashboard space are Homepage and Dashy. The difference is architectural rather than cosmetic. Homepage reads service definitions and can pull live status from integrations, so its widgets reflect what the services are actually doing. Dashy offers a similar card-based layout with its own configuration format and a built-in status-checking option.

Homer sits at the other end of that spectrum. It is a static site with one YAML input and no backend process, which is why the README can claim low or no maintenance. The trade is that anything dynamic has to be built by you, and the smart card mechanism described in docs/customservices.md is the documented route for that. If your requirement is a fast, predictable page that survives a rebuild of your whole stack, the static approach is an advantage. If your requirement is a single pane that tells you what is up and what is down, Homer is the wrong starting point.

Licence, maintenance and upgrade cost

Homer is licensed under Apache-2.0, and the Dockerfile carries the same identifier in its image labels. For most self-hosted use this is uncomplicated: you can run it, modify it, and redistribute it under the terms of that licence. If you fork the project and ship your own image, the licence obligations around notices and attribution apply to what you distribute; that is a question for your own counsel, not something this article can settle.

Maintenance is genuinely light because there is nothing to migrate. The config file is yours, the container is stateless apart from the mounted assets directory, and upgrading means pulling a new image tag. The repository's last push was on 2026-08-27, and releases include v26.8.1 and v26.08.2 on that same date, with v26.4.2 earlier on 2026-04-18. The project is not archived. The upgrade risk to watch is not data loss but config drift: if a release changes how a card field is interpreted, you find out when the page renders, because there is no migration step or validation pass in the documented workflow. Pinning a specific image tag and reading the release notes before bumping is the cheap precaution.

Who should run Homer, and who should not

Run Homer if you want a curated page of links to your own services, you are comfortable editing YAML, and you already have a way to serve static files. The Docker path with a bind-mounted assets directory is about as small as a self-hosted dashboard gets, and the keyboard shortcuts and fuzzy search make it usable daily.

Do not run it if you need live status, discovery, or multi-user access control. Those are not gaps in the documentation; they are outside what a static page generated from one YAML file does. The honest summary is that Homer is a bookmark page with a build step, and it is a good one at exactly that.

Editorial conclusion

Adopt Homer if you want a hand-edited YAML bookmark page with no database and no runtime API. Skip it if you need live service status, automatic service discovery, or per-user access control; the README documents none of those. Before committing, check that your config directory is writable by uid 1000 or that you pass --user, and confirm assets/config.yml.dist exists in the release you download, since the tarball instructions depend on that file.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes