The Problem
Teams that self‑host dozens of services often lack a single, secure entry point that shows status, provides quick links, and aggregates useful information (weather, time, search). Maintaining a custom dashboard requires separate web servers, manual API key handling, and ad‑hoc scripts, which adds operational overhead and security risk.
What This Does
homepage generates a static, proxied dashboard that pulls data from over 100 supported services. The core build is driven by the Dockerfile at the repository root, which bundles the Go‑based static site generator and the runtime server. Configuration lives in the docs/configs/ folder as YAML files (e.g., services.md, settings.md) and can also be discovered automatically via Docker labels (see docs/configs/docker.md). Custom theming, CSS, and HTML overrides are placed under docs/overrides/ and docs/stylesheets/.
Key files: Dockerfile – container image definition. docker-entrypoint.sh – entry script that assembles the site at container start. docs/configs/ – example YAML snippets for services, widgets, and global settings. .github/workflows/ – CI pipelines (Docker publish, lint, test).
The repository also ships a full documentation site (docs/ with 161 markdown files) that is built and published by the docs-publish.yml workflow.
How To Use It
Setup
Build the container (Dockerfile in repo root) docker build -t homepage:latest .
Run the container, mounting a custom config directory
docker run -d \ -p 3000:3000 \ -v $(pwd)/my-config:/app/config \ --name homepage \ homepage:latest
The my-config directory should contain a settings.yaml (see docs/configs/settings.md) and any service definitions required.
Configuration
Global options: settings.yaml (documented in docs/configs/settings.md). Service widgets: individual YAML files under services/ (e.g., docs/widgets/services/radarr.md). Custom CSS/JS: place files in docs/stylesheets/extra.css or docs/overrides/main.html.
All YAML files are parsed at container start by docker-entrypoint.sh, which also validates Docker label discovery if you run the container on the same Docker network as your services.
Running it
After the container is up, the dashboard is served at http://localhost:3000. The static site is generated on each container start; no separate build step is required.
For detailed installation steps, refer to docs/installation/docker.md and the GitHub Actions workflow docker-publish.yml for the exact build flags used by the project maintainers.
Real‑World Use
A home‑lab operator can drop a docker-compose.yml that mounts /var/run/docker.sock and a volume with settings.yaml. The dashboard will automatically list running containers, display Plex/Emby now‑playing info, and show weather from Open-Meteo—all without exposing API keys to the browser.
services: homepage: image: ghcr.io/gethomepage/homepage:latest ports: ["3000:3000"] volumes: /var/run/docker.sock:/var/run/docker.sock ./config:/app/config
Code Health & Issues
Low – Limited test coverage – Only one test file found; functional coverage of the many service integrations is unclear. (tests/ folder minimal). Medium – Dependency hygiene – No lockfile for Go modules is visible; CI does not run go mod verify, raising potential supply‑chain risk. (Dockerfile builds from source). Low – Documentation depth – Excellent (docs/ 164 files) and up‑to‑date, reducing onboarding friction. Medium – Runtime errors – Docker label discovery relies on presence of docker.sock; missing or mis‑mounted socket will cause silent failures, not currently caught in entry script. (docker-entrypoint.sh). Low – License – SPDX license file present (LICENSE), satisfying legal compliance.
Overall CI is robust: lint, test, and release workflows are defined under .github/workflows/.
The Bottom Line
homepage offers a production‑ready, Docker‑centric dashboard with extensive service integrations and solid documentation. It is well‑suited for self‑hosted environments where security (proxied API calls) and low overhead are priorities. The main drawbacks are sparse automated tests and a lack of explicit dependency lock files, which may require additional validation before deployment in high‑risk settings.