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:
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",
|
||||
};
|
||||
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user