<aside> 📋

This post details setting up HomePage as part of a docker compose stack to create a service dashboard with system and service monitors, automatic service discovery (using Docker labels) and keyboard service search for QuickLaunch.

</aside>

Revision: 20250317-0 (init: 20240908)

docker compose setup for HomePage with Dashdot and Watchtower widgets from Komodo or Dockge, including detailing the dashboard setup for a multi-tab layout with four sections of content: system metrics, static content, dynamic applications (docker service discovery), and service monitors.

Preamble

Services Map

Documentation is a crucial feature of a successful self-hosting methodology.

While migrating to Traefik and creating reverse proxies by adding dynamic configuration files or Docker labels, I documented the services’ map (on Notion, with multiple Table views).

A “Per Host” Table view (sorted by “Exposed Port”) for the services on one server is as follows:

Among the columns existing in the original Notion DataBase from which those views are created are:

• Name: the service name — duplicates can exist if the service either uses multiple port (list all ports exposed) and/or is deployed on multiple Hosts
• Host: the server name — a “single select” list of available servers
• Exposed Port: any port exposed by the service, be it mapped to a reverse proxy or not
• Slug base: the base URL to use for each domain (if multiple), for example, the home slug with the example.com domain; the full url is home.example.com
• Domain mapping: for example.com, how the service is exposed via a reverse proxy (if it is): Traefik label, name of the Traefik dynamic yaml file, … if more than one domain, create as many “domain mapping” columns as needed
  • Per Domain, a “Added to “HomePage” checkmark as well as “Credentials stored in Password Manager” checkmark
• Deployment Method: how the service is deployed, with entries from a mutli-selection list with content such as “Unraid”, “Dockge”, “Komodo”, “Docker Compose”, … i.e. make it easier to find the a given service in case of issues with it.
• Tool URL: where to find documentation in case of an issue, often GitHub repositories.
• Notes: Any notes relevant to the service; for example: “VNC-based, add /vnc.html to url”
• Relationship: Notion DB allows linking components to other rows from the same table; for example, the “HomePage” service uses the “Docker Socket Proxy” service.

Automatic Discovery

Automation is another relevant component when attempting to maintain this knowledge map.

It is challenging to keep multiple sources of truth synchronized. As such, it is practical to have some components automatically announce themselves.

In the same way that adding an entry to Traefik can be done using Docker labels, the dashboard solution we retained, Homepage, can also automatically register Docker service using labels.

Homepage

A modern, fully static, fast, secure fully proxied, highly customizable application dashboard with integrations for over 100 services and translations into multiple languages. Easily configured via YAML files or through docker label discovery.

r/homelab and r/selfhosted are great places to discover people showcasing their “homepage dashboard.”

For this setup, we are using multiple features of the tool:

• docker label discovery
• tabs to separate components per server and/or per purpose
• widgets to display monitors and service details
• quicklaunch to start a service from the keyboard (no mouse click)
• a layout to separate multiple sections: metrics, static, dynamic, and widgets
• numerous instances to separate network definitions (or use various Traefik domains, for example, a domain1 for the local network and a domain2 for a reverse proxy for only some applications specific to Tailscale (where not all services are available on that domain2). When using tailscale, if using a local host as a subnet router, domain1 suffices.

Here is what our local setup provides (yours will likely differ):

(Link to larger screenshot + link to background image on r/wallpaper)

Using docker labels

We will rely on homepage’s ability to perform Automatic Service Discovery using Docker labels. Those labels are homepage.group, homepage.name, homepage.icon, homepage.href, homepage.description, and instance-specific options.

The following are copy→adapt→paste options for a use-case with a single instance, multiple homepage instances, and an Unraid XML template filler. In each case:

• replace example.com and example.net with the INSTANCE domain
• replace ALIAS with the application name
• replace TAB with the tab name as defined in the layout: section of your settings.yaml file
• replace SIGN with the expected icon name.
• replace SLUG with the base URL of the service you are connecting; it will be used with the domain name; for example, if the slug is home and the domain example.com, the href entry will be home.example.com
• .instance allows separation between different homepages’ instance
  • Replace INSTANCE1 and INSTANCE2 with the value you will use for your instanceName: (in the settings.yaml file)
  • do not add an entry if a service does not exist for a given instance
• We have added the TAB in the .description field to sort when using homepage’s quicklaunch option easily. It is also possible to use the host in that location. However you decide to use those, they are methods to differentiate multiple instances using a similar .name-base on different hosts, for example.

Single Instance

		labels:
		  - homepage.name=ALIAS
		  - homepage.group=TAB_apps
		  - homepage.icon=SIGN.png
		  - homepage.href=https://SLUG.example.com/
		  - homepage.description=ALIAS (TAB)

Multiple homepage instances

    labels:
      - homepage.name=ALIAS
      - homepage.group=TAB_apps
      - homepage.icon=SIGN.png
      - homepage.instance.INSTANCE1.href=https://SLUG.example.com/
      - homepage.instance.INSTANCE2.href=https://SLUG.example.net/
      - homepage.description=ALIAS (TAB)

Unraid with multiple instances

Although the Unraid WebUI allows you to manually “Add” labels for each required label, you can also modify the Docker service’s XML file.

Those are in the /boot/config/plugins/dockerMan/templates-user folder and are named my-<SERVICE>.xml. Once the matching service entry is found, it can be edited by copying and adapting the following lines before the final </Container> line:

  <Config Name="homepage.name=ALIAS" Target="homepage.name" Default="" Mode="" Description="" Type="Label" Display="always" Required="false" Mask="false">ALIAS</Config>
  <Config Name="homepage.group=TAB_apps" Target="homepage.group" Default="" Mode="" Description="" Type="Label" Display="always" Required="false" Mask="false">TAB_apps</Config>
  <Config Name="homepage.icon=SIGN" Target="homepage.icon" Default="" Mode="" Description="" Type="Label" Display="always" Required="false" Mask="false">SIGN</Config>
  <Config Name="homepage.instance.INSTANCE1.href=https://SLUG.example.com/" Target="homepage.instance.INSTANCE1.href" Default="" Mode="" Description="" Type="Label" Display="always" Required="false" Mask="false"><https://SLUG.example.com/></Config>
  <Config Name="homepage.instance.INSTANCE2.href=https://SLUG.example.net/" Target="homepage.instance.INSTANCE2.href" Default="" Mode="" Description="" Type="Label" Display="always" Required="false" Mask="false"><https://SLUG.example.net/></Config>
  <Config Name="homepage.description=ALIAS (TAB)" Target="homepage.description" Default="" Mode="" Description="" Type="Label" Display="always" Required="false" Mask="false">ALIAS (TAB)</Config>

<aside> 💡

After modifying the XML file, from Unraid’s “Docker” tab, Edit the Service and undo any changes to enable the Save button. Save-ing will restart the updated service.

</aside>

Preliminary installations

We will deploy services using docker-compose. Although tools such as Dockge or Komodo are not a requirement, they provide a convenient method to deploy “stacks.” Please see the “Dockge” post for additional details on previous stack deployments.

Dockge (Rev: 20250322-0)

Our example configuration files, in particular, will show how to integrate Dashdot and Watchtower (with metric collection) as widgets and automatically discover Docker services. Both were installed following the instructions in that post.

We are sharing an example.com version of the compose.yaml files we are using for that configuration (follow the direct links to the files, or the content relative to this post is posted at https://github.com/mmartial/geekierblog-artifacts/tree/main/20240908-homepage):

• Dashdot’s compose.yaml. Please adapt:
  • DASHDOT_CUSTOM_HOST with the hostname of the system you are using DashDot with
  • DASHDOT_OVERRIDE_OS with the host OS
  • In the labels: section:
    • update with the .group value you intend to use (also update the .description)
    • update the .href to reflect the URL that matches your setup
    • Note that this example is only for a single instance, adapt if needed.
  • We are using a GPU version of the container. To use a CPU-only version:
  • No other labels beyond the watchtower one are present. If needed, add other such as Traefik labels.
• Watchtower’s compose.yaml. Where:

Although we are not describing how to set reverse proxy configurations for those, in the further configuration steps, we will rely on the following two URLs for those services:

• Dashdot at https://dashdot.example.com
• Watchtower at https://watchtower.example.com

Please see the Traefik or Nginx Proxy Manager posts on some options to use for the reverse proxy.

Traefik Proxy (Rev: 20250210-0)

Reverse Proxy: Nginx Proxy Manager (Rev: 20240730-0)

Glances

Untitled

Untitled