diff --git a/apps/docs/docs/getting-started/after-the-installation.mdx b/apps/docs/docs/getting-started/after-the-installation.mdx index 8fad75a43..8abf1ee27 100644 --- a/apps/docs/docs/getting-started/after-the-installation.mdx +++ b/apps/docs/docs/getting-started/after-the-installation.mdx @@ -47,7 +47,7 @@ The studio keeps related choices together: 1. **Essentials** sets the default language, color scheme, analytics preference, and the usual host, IP address, domain, or reverse-proxy path used by your services. URL suggestions can use separate ports, subdomains, or one path per service. 2. **Discover** checks the actual database, Docker-compatible sockets, Kubernetes configuration, Workshop, and Assistant capabilities. Unavailable sources never block manual setup. -3. **Connect** combines explicit `homarr.*` or Homepage Docker labels with image matching. Select several integrations and apps at once, review every URL, and use the service-specific link to open its API-key settings when one is available. If a container has no published port or URL label, add its HTTP or HTTPS address before importing it. +3. **Connect** combines explicit [`homarr.*` or Homepage Docker labels](/docs/integrations/docker-labels) with image matching. Select several integrations and apps at once, review every URL, and use the service-specific link to open its API-key settings when one is available. If a container has no published port or URL label, add its HTTP or HTTPS address before importing it. 4. **Board** previews the Base layout, colors, widget radius, sidebars, selected apps, and widgets inferred from integrations or Docker labels. Choose 8 columns for a focused board, 10 for a balanced board, 12 for a wide board, or use the slider for a custom width up to 24 columns. Homarr still creates and reflows the protected Mobile layout automatically. A fast setup adds the integration-free Clock, Weather, and Bookmarks starter widgets. 5. **Extend** explains and optionally configures Homarr Assistant, the community Workshop, and the separate Homarr MCP endpoint. 6. **Review** tests the selected connections, then saves integrations, apps, widgets, settings, and the exact first board together. If any part fails, the database changes are rolled back and your form stays available to correct. diff --git a/apps/docs/docs/integrations/docker-labels/index.mdx b/apps/docs/docs/integrations/docker-labels/index.mdx new file mode 100644 index 000000000..677e7a518 --- /dev/null +++ b/apps/docs/docs/integrations/docker-labels/index.mdx @@ -0,0 +1,93 @@ +--- +title: "Docker labels" +description: "Discover apps, integrations, and widgets from container labels during Homarr onboarding." +--- + +# Docker label discovery + +During onboarding, Homarr scans running containers on every reachable +[Docker-compatible host](/docs/integrations/docker). Labels let you provide exact app metadata instead of relying on +image-name matching. You can review and deselect every result before Homarr creates anything. + +A container with valid Homarr labels takes priority over image-based discovery. Containers without valid labels can +still be suggested from their image and published ports. + +## Homarr labels + +`homarr.name` and `homarr.href` are required for label discovery. All other labels are optional. + +| Label | Purpose | +| --- | --- | +| `homarr.name` | App or integration display name | +| `homarr.href` | Address opened by the app and used as the suggested integration address | +| `homarr.group` | Container section that receives the selected app and compatible widget | +| `homarr.icon` | App icon URL | +| `homarr.description` | App description | +| `homarr.ping` | Address used for app status checks | +| `homarr.id` | Stable source identifier; defaults to the Docker container ID | +| `homarr.board` | Intended board name; see [Board targeting](#board-targeting) | +| `homarr.integration` | Homarr integration kind, for example `sonarr` | +| `homarr.widget` | Homarr widget kind to add when it supports the selected integration | +| `homarr.hide` | Excludes the container when this label is present, regardless of its value | + +Unknown integration and widget kinds are ignored. Do not put API keys, passwords, or other secrets in labels. Enter +credentials in onboarding, where Homarr stores them using its normal encrypted integration-secret flow. + +## Compose example + +```yaml +services: + sonarr: + image: lscr.io/linuxserver/sonarr:latest + labels: + homarr.name: "Sonarr" + homarr.href: "http://server.local:8989" + homarr.group: "Media" + homarr.icon: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/sonarr.svg" + homarr.description: "TV library" + homarr.ping: "http://server.local:8989" + homarr.integration: "sonarr" + homarr.widget: "calendar" +``` + +Use an address that is reachable where it is needed. A Docker service name can work for server-side integration +requests, while an app link opened in a browser usually needs a LAN hostname, IP address, or reverse-proxy address. + +## Homepage label fallback + +When `homarr.name` is absent, onboarding also understands these Homepage labels: + +- `homepage.name` +- `homepage.href` +- `homepage.group` +- `homepage.icon` +- `homepage.description` + +`homepage.name` and `homepage.href` are required for the fallback. Homarr does not combine partial Homarr metadata with +Homepage metadata: once `homarr.name` is present, use `homarr.*` labels for the remaining fields too. + +## What onboarding creates + +In **Connect**, label-discovered apps and integrations appear before image-based suggestions. You can import multiple +services in one pass and edit every suggested address. + +When setup completes, Homarr rechecks the selected container sources and then: + +- creates an app with its name, address, icon, description, and ping address; +- creates the requested integration and links its app after you provide required credentials; +- places grouped apps in a board container named by `homarr.group`; +- places ungrouped apps in the main board area; +- adds `homarr.widget` only when the widget kind is valid and compatible with the selected integration; +- keeps image-based discovery available for unlabeled containers. + +If a selected container disappears, targets another board, or requests an incompatible widget, setup finishes with a +warning instead of creating an invalid board item. + +## Board targeting + +On a fresh installation with one seeded `dashboard` board, one unique selected `homarr.board` value can name that first +board. Otherwise, the label must match the board selected in onboarding. Services labeled for another board are skipped +and reported in the completion warning. + +Onboarding configures one board at a time. Run normal board management after setup if you want to distribute services +across several boards. diff --git a/apps/docs/docs/integrations/docker/index.mdx b/apps/docs/docs/integrations/docker/index.mdx index 40ade4912..04ed74fa5 100644 --- a/apps/docs/docs/integrations/docker/index.mdx +++ b/apps/docs/docs/integrations/docker/index.mdx @@ -160,11 +160,13 @@ They are then available in the app list and can be used as normally added apps. ![Apps added from containers](img/add-to-homarr-apps.png) -### Configuration +### Container labels -Currently Homarr supports one label for configuration of the containers: +`homarr.hide` excludes a container from the Docker Containers widget, tools page, and onboarding discovery whenever the +label is present. -- **homarr.hide:** If set to any value, the container will be hidden from the Docker Containers widget and tools page. +During first-run onboarding, Homarr can also discover apps, integrations, groups, and compatible widgets from +`homarr.*` labels, with Homepage labels as a fallback. See the complete [Docker label reference](/docs/integrations/docker-labels). ### Security