Organize self-hosted services with Homepage
Dashboard Delight

© Photo by Nik on Unsplash
Simplify the chaos of self-hosted services with Homepage, a customizable dashboard with widgets that put service statistics at your fingertips.
If you're running more than a handful of self-hosted services, having a single dashboard to access all their web interfaces would be nice. Homepage [1] provides a highly customizable application dashboard that integrates with over one hundred services. The Homepage dashboard not only facilitates easy access to services running in Docker [2] or Podman [3] containers, but it also lets you link to the admin pages of devices such as your modem, router, hypervisor, and network attached storage (NAS).
While this might seem like a typical bookmark manager, Homepage offers much more. Widgets can display various service metrics, such as your hypervisor's CPU and RAM usage, the amount of unread articles in your RSS feed aggregator, and the number of available updates from your container image update notifier. This makes it truly a homepage, giving you a bird's-eye view of all your services.
Installation
For this article, I assume you are running your services within Docker or Podman containers and will be adding Homepage to these containers. I'll use Docker Compose [4] for my setup here, though the same applies to Podman Quadlets [5]. Other Homepage installation options [6] are available as well.
Start by creating a directory for the Homepage container to store its data and configuration:
$ mkdir -p containers/homepage
In your docker-compose.yml
file, define a service for Homepage as shown in Listing 1.
Listing 1
Homepage Service in docker-compose.yml
01 services: 02 homepage: 03 image: ghcr.io/gethomepage/homepage:v1.1.1 04 container_name: homepage 05 ports: 06 - 3000:3000 07 volumes: 08 - /home/koan/containers/homepage:/app/config 09 environment: 10 HOMEPAGE_ALLOWED_HOSTS: debian.home:3000 11 restart: unless-stopped
In Listing 1, I have specified version 1.1.1 of the container image to make sure that the configuration in this article still works when an update introduces incompatible changes. Check the releases on the Homepage GitHub repository [7] for breaking changes before defining the latest release in the Docker Compose file.
Adjust the directory /home/koan/containers/homepage
to the one you created earlier for the container. Ensure the HOMEPAGE_ALLOWED_HOSTS
environment variable reflects the domain and port you'll use to access the web interface. If you publish the container's port directly to the host machine, as shown in this example, this environment variable should represent the hostname of the container host and the container's published port. However, if you deploy Homepage behind a reverse proxy for HTTPS access, adjust this variable accordingly.
Next, launch the container:
$ docker-compose up -d
Once the image has downloaded and the container starts, open Homepage in your web browser using the URL you defined (in this example, http://debian.home:3000). You should see something like Figure 1.

Exploring Homepage
Figure 1 shows the basic structure of any Homepage dashboard. A header occupying the top of the page displays some information widgets, providing host system statistics and a search bar to launch searches via the default search engine, DuckDuckGo [8].
Below the header, three groups are visible, each with one service. Each service has a name and a description, and clicking on a service opens a new browser tab with the corresponding link. By hovering over a group name, you can collapse the entire group by clicking on the inverted caret and expand the group by clicking on the caret again.
Located below the service groups, you'll find bookmark groups that function similarly, allowing you to collapse and expand the groups. Clicking on a bookmark opens the corresponding link. Finally, at the bottom, you'll see some icons for changing theme colors, reloading the page, and toggling between dark and light colors. In this article, I'll show you how to customize all these parts of your personal homepage.
Information Widgets
While not Homepage's primary function, its information widgets [9] are a pleasant addition. By default, two information widgets appear: Resources and Search. You'll find their definitions in the widgets.yaml
file (Listing 2) in Homepage's directory, created upon the container's initial launch along with all other configuration files.
Listing 2
Default widgets.yaml file
01 - resources: 02 cpu: true 03 memory: true 04 disk: / 05 06 - search: 07 provider: duckduckgo 08 target: _blank
If you want to exclude a specific resource, simply set it to false
instead of true
. You can also add the system's uptime by adding uptime: true
and add a name to the widget by adding label: Name
. Another option, expanded: true
, shows more resource statistics, such as the CPU load, total RAM, and total storage size.
Homepage also offers two weather widgets: one using Open-Meteo [10], which requires no registration, and another using OpenWeatherMap [11], which requires you to subscribe and get an API key. Listing 3 presents a complete widgets.yaml
file, where you see the expanded Resources widget and the Open-Meteo widget set to a location. The cache
value sets the duration in minutes for caching API responses, preventing excessive requests to Open-Meteo services. Figure 2 shows the information widgets defined in Listing 3.
Listing 3
Defining Widgets
01 - resources: 02 label: System 03 expanded: true 04 cpu: true 05 memory: true 06 uptime: true 07 disk: / 08 09 - search: 10 provider: duckduckgo 11 target: _blank 12 13 - openmeteo: 14 label: Attenrode 15 latitude: 50.8773405 16 longitude: 4.9213237 17 timezone: Europe/Brussels 18 units: metric 19 cache: 5 20 format: 21 maximumFractionDigits: 1

Other information widgets offered by Homepage include options for displaying stock prices, the date and time, and more. Consult the documentation for all possibilities. You can also customize the header style. For instance, adding headerStyle: boxed
within the settings.yaml
file adds a box around the information widgets instead of underlining them. The Settings [12] page in Homepage's documentation provides details about these and other settings.
Buy this article as PDF
(incl. VAT)