Homepage: A Static, Proxied Dashboard for Self-Hosted Services

What Homepage Actually Solves

Homepage addresses a specific annoyance: self-hosters who run many services and want one landing page that shows status, links, and key data without logging into each app. The README describes it as a modern, fully static, fast, secure fully proxied, highly customizable application dashboard. The target user is someone who already runs Docker containers and wants a startpage that is not just a list of bookmarks but a live overview. It solves the problem of scattered URLs and the need to check several UIs for basic state, like whether a download is complete or a media server is up. The static generation means the page loads instantly, but it also means the data is a snapshot from build or startup time, not a live feed.

Static Generation and the Proxy Mechanism

The core architectural choice is that Homepage is statically generated at build time. This is a Next.js application, and the production build produces static files. That gives fast load times, but it imposes a constraint: any dynamic data must be fetched client-side or via a proxy. The README states that all API requests to backend services are proxied, keeping your API keys hidden. The proxy runs server-side, so the browser never sees the keys. This is a real security benefit, but it also means Homepage must run as a server process, not just a static file host. The proxy is the mechanism that reconciles the static front end with live service data. The trade-off is that the dashboard cannot be served from a plain CDN; you need the Node server running.

Docker Label Discovery: The Killer Feature

The most distinctive feature is automatic service discovery via Docker labels. You add labels to your existing containers, and Homepage picks them up and adds them to the dashboard. This is documented on the Docker Service Discovery page. It removes the need to hand-edit YAML for every service. The mechanism requires mounting the Docker socket into the Homepage container, which the compose example does with /var/run/docker.sock:/var/run/docker.sock:ro. That is a read-only mount, which is a sensible precaution, but mounting the Docker socket at all is a significant security consideration. Anyone who compromises Homepage could potentially interact with the Docker daemon, even read-only. The README notes that the socket mount is optional, for docker integrations. For users who cannot or should not mount the socket, you can still define services manually in YAML.

Running It: Commands and Config Keys

The README gives two primary deployment paths. With Docker Compose, you use the image ghcr.io/gethomepage/homepage:latest, set the environment variable HOMEPAGE_ALLOWED_HOSTS (which the README marks as required), and mount a config directory to /app/config. The compose file also shows optional PUID and PGID variables for user and group IDs. For a source install, you clone the repo, run pnpm install and pnpm build, copy src/skeleton to config/ for initial example files, then run HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev:1234 pnpm start. The config is all YAML files in the config directory. There is no mention of a setup wizard or GUI. The documentation site is the primary reference, and the README points there for configuration details. The security notice stresses that if Homepage is reachable from an untrusted network, it must sit behind a reverse proxy that enforces authentication, TLS, and Host header validation, with an optional built-in OIDC or password login.

Widgets and Integrations: Breadth vs. Depth

Homepage claims over 100 service integrations and widgets for popular self-hosted apps like Radarr, Sonarr, Plex, Jellyfin, and qBittorrent. It also has information widgets for weather, time, date, and search. The README lists these as examples, not an exhaustive set. The breadth is impressive on paper, but the depth varies. Each widget has its own API requirements. The documentation likely specifies which endpoints and API keys each widget needs. A practical limitation is that if a service changes its API, a widget may break until the project updates. The release history shows active maintenance, with three releases in a single day (v2.1.0, v2.1.1, v2.1.2), which suggests a fast iteration cycle. But that also means you should pin a specific version in production, rather than using latest, to avoid unexpected changes.

Customization and Its Limits

Homepage is highly customizable, with support for custom themes, custom CSS and JS, custom layouts, and localization. That is a strength for users who want a personal look. The README mentions over 40 languages, which is broad. But customization is done through YAML files and custom code, not through a visual editor. The README warns that most questions are simple YAML configuration issues. That points to a learning curve. If you are not comfortable editing YAML and reading documentation, Homepage will feel opaque. The static generation also means that changes to config require a restart or rebuild to take effect, depending on how the server picks up files. The README does not specify a hot-reload mechanism for config in production, so you should plan for a restart after edits.

The Wrong Tool for Live Dashboards

Homepage is not a real-time monitoring tool. The static generation means the page is a snapshot. If you need live-updating graphs or second-by-second status, this is the wrong tool. Tools like Glances are mentioned as an information provider, but the dashboard itself does not push updates. The README does not describe WebSockets or server-sent events. The proxy handles API requests, but the page likely refreshes on load or on a timer, not via a continuous stream. For a homelab dashboard, that is often fine, but for an operations dashboard, it is a genuine limitation. Also, the security model depends on your reverse proxy. The README is explicit about that, which is good, but it means Homepage alone does not provide robust protection; you must configure the proxy correctly.

Alternatives and How They Differ

A common alternative is Organizr, which is a PHP-based dashboard that also aggregates services but does not use static generation. Organizr runs as a web app with a database and a login system built in. The key difference is that Organizr is dynamic: it serves pages on request and can integrate with authentication systems like LDAP. Homepage is static and relies on a reverse proxy for auth, though it has an optional built-in login. Another alternative is Heimdall, which is a static-ish dashboard but does not have Docker label discovery as a core feature; you add tiles manually. The difference in approach is that Homepage leans on Docker labels for automatic population, while Heimdall requires manual tile creation. If you prefer a PHP app with a UI for management, Organizr is the choice. If you want a lightweight, static page with minimal dependencies, Homepage is more aligned.

Maintenance, License, and Upgrade Cost

Homepage is licensed under GPL-3.0, which means if you modify and distribute it, you must share your changes under the same license. For personal use, that is not a burden, but for a company that wants to embed it in a proprietary product, it is a consideration. The project is actively maintained, with releases as recent as August 2026 and a default branch named dev, which suggests ongoing development. The upgrade cost is moderate: you pull a new image or rebuild from source. The README does not describe a migration path or breaking changes between versions, so you should check the release notes before upgrading. The documentation is built with Zensical and can be run locally with uv sync and uv run zensical serve, which is a nice touch for contributors. The project has over 200 contributors, which indicates a healthy community, but you should verify that the specific widgets you need are maintained.

Editorial conclusion

Adopt Homepage if you run a self-hosted stack in Docker, want automatic service discovery via labels, and can accept a config directory that is read at startup rather than live. Avoid it if you need real-time dashboard updates without a refresh, if you cannot mount the Docker socket, or if you expect a GUI for configuration, because everything is YAML. Before deploying, verify that your reverse proxy enforces authentication and Host header validation, set HOMEPAGE_ALLOWED_HOSTS correctly, and confirm that your service APIs expose the endpoints Homepage expects, since widget coverage varies by service.

Official sources

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