Self-Hosting with Homepage: Fast, Secure Application Dashboard

Homepage is an open-source, highly customizable dashboard and startpage designed for self-hosted infrastructure and personal homelabs. Homepage is a statically generated application dashboard that proxies backend API requests to keep credentials hidden and supports YAML configuration as well as Docker label discovery.

By combining instant static rendering with an active ecosystem of over 100 service widgets, Homepage serves as a central hub for monitoring system health, managing bookmarks, and inspecting live service metrics. The official documentation is maintained at gethomepage.dev.

Deploying Homepage with Docker Compose

The standard deployment method for Homepage is containerized execution via Docker Compose. The configuration requires mounting a persistent directory for your configuration files and optionally mounting the Docker socket for container monitoring.

To set up Homepage, create a docker-compose.yml file as documented in the official Docker installation guide:

Make sure the local path mapped to /app/config exists before launching the container. Set the HOMEPAGE_ALLOWED_HOSTS variable to your access domain or host IP to ensure security headers permit inbound connections.

Launch the service using Docker Compose:

Once running, access the dashboard at http://localhost:3000 or your host IP address.

Organizing Groups and Declaring Services

Dashboard services and layout groups are defined inside the services.yaml configuration file, supporting arbitrary numbers of groups and service items. This file resides in the mounted /app/config volume directory.

The service configuration documentation demonstrates how to organize services into logical groups:

Groups can be nested to create multi-tier hierarchies, allowing complex homelab environments to stay cleanly partitioned across functional areas such as networking, storage, and media automation.

Service Widgets and API Proxying

A key architectural advantage of Homepage is its security posture when interfacing with downstream APIs. All outbound API requests to downstream services are proxied through the server layer so that sensitive API keys remain concealed from the client browser.

Service widgets fetch real-time operational metrics directly into service cards. For example, attaching an Emby widget into services.yaml requires specifying the widget type, target URL, and API key as shown in the official services configuration guide:

When rendered, Homepage connects to the Emby API on the server side and forwards sanitized status data to the browser interface. Widgets also support custom headers, field visibility controls, and block tint highlighting for immediate visual alerts when thresholds are crossed.

Docker Discovery and Permission Management

Homepage offers native Docker integration capable of discovering and registering dashboard entries automatically using container labels. Instead of declaring every container manually in YAML, adding homepage.group, homepage.name, and homepage.href labels to container definitions allows Homepage to discover and display them dynamically upon startup.

For container execution security, While the container runs as root by default, Homepage supports running as a non-root user through standard PUID and PGID environment variables. When specifying non-root user IDs, ensure that local config directories on the host share matching file ownership so the application container maintains read and write access.

The project is actively maintained under the GNU General Public License v3.0, with regular maintenance updates such as the v2.1.2 release where The v2.1.2 release resolved a YAML parsing regression introduced in the previous version. Additional features, changelogs, and translation updates are detailed across the official README and documentation portals.