feat(onboarding): add Docker label discovery during init

Port label-based container discovery from config-portability and wire it
into the onboarding integrations step. Labeled containers take priority
over image matching, sync into category sections, and preserve board
layout when placing integration widgets.
This commit is contained in:
Thomas Camlong committed 2026-07-01 22:30:44 +02:00
1 parent dd2eb3aa66
commit 05e7d8c529
26 files changed
+1630 -58

No files matched your search

@@ -0,0 +1,54 @@
---
title: 'Docker labels'
description: 'Configure Homarr apps automatically using Docker container labels during onboarding.'
hide_title: true
---
# Docker label discovery
Homarr can read `homarr.*` labels on your containers to pre-populate apps during onboarding. Homepage-style `homepage.*` labels are supported as a fallback when no `homarr.name` label is set.
## Required labels
| Label | Description |
| --- | --- |
| `homarr.name` | Display name for the app |
| `homarr.group` | Category section name on the board |
| `homarr.href` | URL opened when clicking the app |
## Optional labels
| Label | Description |
| --- | --- |
| `homarr.icon` | Icon URL |
| `homarr.description` | App description |
| `homarr.ping` | Ping URL for status checks |
| `homarr.id` | Stable external ID (defaults to container ID) |
| `homarr.board` | Target board name |
| `homarr.integration` | Integration kind (e.g. `sonarr`) for onboarding integration setup |
| `homarr.widget` | Widget kind hint (parsed, not auto-placed yet) |
| `homarr.hide` | Hide container from discovery |
## Homepage fallback
When `homarr.name` is absent, Homarr reads `homepage.name`, `homepage.group`, and `homepage.href` if homepage label reading is enabled (default: on).
## Example
```yaml
services:
sonarr:
image: lscr.io/linuxserver/sonarr:latest
labels:
homarr.name: "Sonarr"
homarr.group: "Media"
homarr.href: "http://sonarr:8989"
homarr.icon: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/sonarr.svg"
homarr.integration: "sonarr"
```
## Onboarding behavior
During the integrations step, Homarr scans labeled containers first. Labeled services appear with their configured name, group, and URL. Unlabeled running containers still use image-based discovery as a fallback.
When you finish onboarding, selected label-based apps are synced into category sections on your board. Integration widgets are placed separately in the default section.
@@ -0,0 +1,8 @@
import { IntegrationDefinition } from "@site/src/types";
export const dockerLabelsIntegration: IntegrationDefinition = {
name: "Docker labels",
description: "Configure Homarr apps automatically using Docker container labels.",
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/docker.svg",
path: "../../integrations/docker-labels",
};
+4 -2
View File
@@ -93,9 +93,11 @@ They are then available in the app list and can be used as normally added apps.
### Configuration
Currently Homarr supports one label for configuration of the containers:
Homarr supports Docker labels for automatic app discovery during onboarding. See [Docker labels](./docker-labels/index.mdx) for the full reference.
- **homarr.hide:** If set to any value, the container will be hidden from the Docker Containers widget and tools page.
Currently Homarr supports one label for hiding containers:
- **homarr.hide:** If set to any value, the container will be hidden from the Docker Containers widget, tools page, and label discovery.
### Security
Mounting docker sockets can be risky, as they permit full control over your docker service.