Automatic Service Discovery

When you're building your home lab using this setup, each time you add a service, you need to not only add a container to your Docker Compose file but also add a service definition to Homepage's services.yaml file. Hompage simplifies this with automatic service discovery for containers by using labels. If you use automatic service discovery, you don't need to define the service in services.yaml. Instead, you add the proper labels in the service definition in your Docker Compose file, as shown in Listing 11. Then, you only need to touch one file for each added service.

01 freshrss:
02   image: docker.io/freshrss/freshrss:1.26.1-alpine
03   container_name: freshrss
04   ports:
05     - 8081:80
06   volumes:
07     - /home/koan/containers/freshrss/data:/var/www/FreshRSS/data
08     - /home/koan/containers/freshrss/extensions:/var/www/FreshRSS/extensions
09   environment:
10     CRON_MIN: "1,31"
11     TZ: Europe/Brussels
12   restart: unless-stopped
13   labels:
14     - homepage.group=Services
15     - homepage.name=FreshRSS
16     - homepage.href=http://debian.home:8081
17     - homepage.description=Feed aggregator
18     - homepage.icon=freshrss

All labels start with homepage, followed by a dot and a configuration option. The server and container options I used earlier are no longer needed, because Homepage automatically infers them through the API from the configured Docker instance. When you recreate this container, Homepage automatically discovers the service and adds it to its Services group.

Widgets can also be added to docker-compose.yml this way. Using the same dot notation, Listing 12 shows the number of unread posts and the number of subscriptions for FreshRSS. You need to enable the API in FreshRSS and enter the API password in the homepage.widget.password label.

01 labels:
02   - homepage.group=Services
03   - homepage.name=FreshRSS
04   - homepage.href=http://debian.home:8081
05   - homepage.description=Feed aggregator
06   - homepage.icon=freshrss
07   - homepage.widget.type=freshrss
08   - homepage.widget.url=http://freshrss
09   - homepage.widget.username=USER
10   - homepage.widget.password=PASSWORD

Bookmarks

Lastly, Homepage also allows you to add simple bookmarks to its dashboard. You can group them just like services, but they are mere links without extra features. Define your bookmarks in the bookmarks.yaml file, which by default looks like Listing 13.

01 - Developer:
02   - GitHub:
03     - abbr: GH
04       href: https://github.com
05 - Social:
06   - Reddit:
07     - abbr: RE
08       href: https://reddit.com
09 - Entertainment:
10   - YouTube:
11     - abbr: YT
12       href: https://youtube.com

The abbr property represents a two-letter abbreviation shown before the bookmark, but you can replace this with an icon as with services. Furthermore, adding a description property shows this description instead of the bookmark's URL. You can also give the bookmark categories icons by defining them in settings.yaml just like you did for service groups.

Conclusion

Homepage allows you to collect links to all your self-hosted services and important accounts on external services onto a single page (see Figure 4). Automatic service discovery is an especially powerful feature: Once you've configured your dashboard's basic structure, you don't need to touch Homepage's configuration files again. Instead, you can just add labels to each of your new containers to automatically add them to your dashboard.

Figure 4: My home lab's complete dashboard with Homepage.

This article doesn't cover all of Homepage's features. For instance, the settings.yaml file allows for a lot of layout customization, including a background image. For even more flexibility, you can add your own custom CSS and JavaScript code. Moreover, if you add a service to your dashboard for which Homepage doesn't have a widget, you can define a custom widget by mapping JSON objects from the service's API to service fields in Homepage. Overall, Homepage is a powerful addition to any home lab.

The Author

Koen Vervloesem has been writing about Linux and open source, computer security, privacy, programming, artificial intelligence, and the Internet of Things for more than 25 years. He holds Master's degrees in Computer Science Engineering and Philosophy and is teaching Linux, Python, and IoT classes. You can find more on his website at http://koen.vervloesem.eu.