Dashboard Delight

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.

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.

Figure 1: The default Homepage dashboard.

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.

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.

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

Figure 2: The Resources, Search, and Open-Meteo widgets on my dashboard.

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.