This tool generates configuration files for Homer using Docker container labels.
Using Docker container or Consul catalog labels for service discovery is inspired by the same approach used by Traefik and Watchtower.
- Generates Homer config using container labels
- Watches for container changes or Consul changes
- Reloads when the base config changes
- Supports standalone Docker and Docker Swarm
- Creates groups (services) on the fly from labels
- Passes every Homer option through, including smart card options
- Generates extra Homer pages from a
homer.pagelabel - Sort groups and items by priority
- Atomic config writes, debounced events and automatic reconnection to Docker / Consul
- Multi-arch
Create a base configuration for this tool to build upon. This will contain your services sections, title, logo, etc. A value unique to this tool is priority. The higher the priority of an item, the higher on the list it will appear.
title: My Self Hosted Kingdom
subtitle: Enter!
services:
- name: Numbers
icon: fa-solid fa-list-ol
items:
- name: 4
icon: fa-solid fa-dice-four
url: https://fontawesome.com/v5.15/icons/dice-four?style=solid
priority: 4
- name: 3
icon: fa-brands fa-html5
url: https://fontawesome.com/v5.15/icons/html5?style=brands
priority: 3
- name: 1
icon: fa-regular fa-money-bill-alt
url: https://fontawesome.com/v5.15/icons/money-bill-alt?style=regular
priority: 1
# Empty section
- name: Letters
icon: fa-solid fa-sun
items: []Icons use Font Awesome 7 classes (fa-solid, fa-regular, fa-brands),
which Homer ships since v26.08. The older fas/far/fab prefixes still work as aliases.
Start Homer following its instructions to mount the /www/assets directory. This is where the config.yaml file resides.
docker run -d \
-p 8080:8080 \
-v /folder1/homer/:/www/assets \
b4bz/homer:latestStart this tool while:
- mounting the base config
- mounting homer's config
- mounting the Docker socket
- using environment variables to provide their mountpoints.
docker run -d \
-v /folder1/homer/config.yml:/config.yml \
-v /sd/base.yml:/base.yml \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
ghcr.io/pro-tweaker/homer-service-discoveryYou can visit your Homer Dashboard to see the initial generated config (remember to hard refresh).
Start adding labels to your containers to have this tool pick them up. For example, the following command will regenerate the config and add the http-echo service to the Numbers service.
docker run -d \
-p 5678:5678 \
-l homer.enable=true \
-l homer.service=Numbers \
-l homer.name='This is number 2!' \
-l homer.subtitle='http-echo server' \
-l homer.icon='fa-regular fa-hand-peace' \
-l homer.priority=2 \
-l homer.url='http://localhost:5678' \
hashicorp/http-echo \
--text="Be yourself; everyone else is already taken"The full list of labels are:
| Label | Description |
|---|---|
homer.enable |
Set to true include in Homer's config |
homer.service |
The name of Homer Service (group) to add this item to. Created if it is not in the base config |
homer.page |
Write this item to the extra page <page>.yml instead of the main config (see below) |
homer.priority |
The priority level of the item. The higher the number, the higher it appears in the Service |
homer.name |
The item's name (See Homer's documentation) |
homer.logo |
The item's logo (See Homer's documentation) |
homer.icon |
The item's icon (See Homer's documentation) |
homer.subtitle |
The item's subtitle (See Homer's documentation) |
homer.tag |
The item's tag (See Homer's documentation) |
homer.keywords |
The item's search keywords (See Homer's documentation) |
homer.url |
The item's url (See Homer's documentation) |
homer.target |
The item's target (See Homer's documentation) |
homer.tagstyle |
The item's tagstyle (See Homer's documentation) |
homer.type |
The item's type (See Homer's documentation) |
homer.class |
The item's class (See Homer's documentation) |
homer.background |
The item's background (See Homer's documentation) |
homer.<anything> |
Any other key is copied to the item as-is. Use it for smart card options (see below) |
Group options, applied when the group is created from labels (values set in the base config always win):
| Label | Description |
|---|---|
homer.service.icon |
The group's icon |
homer.service.logo |
The group's logo |
homer.service.class |
The group's class |
homer.service.tagstyle |
The group's tagstyle |
homer.service.priority |
The group's priority. Higher priority groups are listed first |
Any homer.<key> label that is not in the table above is written to the item unchanged, so every option of
Homer's smart cards and any key added
in future Homer releases works without an update of this tool:
true/falsebecome booleans and whole numbers become integers. Wrap a value in quotes (homer.apikey='0123') to force a string.- A dotted key creates a nested map:
homer.headers.Authorization=Bearer xbecomesheaders: {Authorization: Bearer x}. - Labels starting with
homer.service.belong to the group (see the table above), not the item.
docker run -d \
-l homer.enable=true \
-l homer.service=Infra \
-l homer.name=Proxmox \
-l homer.type=Proxmox \
-l homer.url=https://pve.local:8006 \
-l homer.node=pve \
-l 'homer.api_token=PVEAPIToken=root@pam!homer=xxxx' \
-l homer.warning_value=50 \
-l homer.hide_decimals=true \
...Every key in the base config is preserved in the generated config, including keys this tool does not know
about (defaults, proxy, hotkey, updateIntervalMs, group class/logo, smart card options on static
items, ...). Only the items lists of the services are modified.
Services (groups) also accept a priority key. Groups with a higher priority are listed first; groups with
the same priority keep the order of the base config.
The base config is checked for changes every HOMER_BASE_CONFIG_WATCH_INTERVAL (10 seconds by default) and
the Homer config is regenerated when it changed, so edits no longer wait for the next container event.
When homer.service names a group that is not in the base config, the group is created with the
homer.service.* options of its containers. Set HOMER_CREATE_MISSING_SERVICES=false to get the old
behaviour of skipping such items with a warning.
docker run -d \
-l homer.enable=true \
-l homer.service=Media \
-l homer.service.icon='fa-solid fa-film' \
-l homer.service.priority=10 \
-l homer.name=Jellyfin \
...Set HOMER_DEFAULT_TYPE to give every item without a homer.type label a smart card, for example
HOMER_DEFAULT_TYPE=Ping to show a reachability indicator on every discovered service.
Homer supports extra pages: a
navbar link with url: "#media" loads media.yml from the same directory as the main config. Add
homer.page=media to a container to write its item to that page instead of the main config.
- The page file is written next to
HOMER_CONFIG(e.g./www/assets/media.yml) and is created if missing. - If
<page>.ymlexists next toHOMER_BASE_CONFIG, it is used as the base of that page. Otherwise the main base config is reused without itsservices, so the page keeps the same title, theme and links. - Page names may only contain letters, digits,
-and_.
# base.yml
links:
- name: Media
icon: fa-solid fa-film
url: "#media"docker run -d \
-l homer.enable=true \
-l homer.page=media \
-l homer.service=Streaming \
-l homer.name=Jellyfin \
...| Key | Description | Default |
|---|---|---|
LOG_LEVEL |
The level of log verbosity | Info |
HOMER_BASE_CONFIG |
Where the base config is located | /base.yml |
HOMER_CONFIG |
Where the Homer config is located | /config.yml |
SERVICE_DISCOVERY |
Either Docker or Consul |
Docker |
HOMER_DOCKER_SWARM |
Docker Swarm supprt. Either true or false |
false |
CONSUL_HOST |
Host for Consul connnection | 127.0.0.1:8500 |
HOMER_CREATE_MISSING_SERVICES |
Create groups named by homer.service that are missing from the base config |
true |
HOMER_DEFAULT_TYPE |
Smart card type for items without homer.type, e.g. Ping |
(none) |
HOMER_BASE_CONFIG_WATCH_INTERVAL |
How often the base config is checked for changes. 0 disables it |
10s |
DEBOUNCE_INTERVAL |
Wait after the last Docker event before regenerating, so a burst of events causes one regeneration | 1s |
RECONNECT_INTERVAL |
Pause before reconnecting after the Docker event stream or Consul watch fails | 5s |

