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

+168 -39
View File
@@ -3,10 +3,13 @@ import { z } from "zod/v4";
import { createId } from "@homarr/common";
import { encryptSecret } from "@homarr/common/server";
import { eq, like, or } from "@homarr/db";
import { createLogger } from "@homarr/core/infrastructure/logs";
import { asc, eq, inArray, like, or } from "@homarr/db";
import { placeAllWidgetsAsync } from "@homarr/db/queries";
import { getServerSettingsAsync } from "@homarr/db/queries";
import {
apps,
boards,
groups,
icons,
integrationItems,
@@ -33,6 +36,8 @@ import { MissingSecretError, testConnectionAsync } from "../integration/integrat
import { mapTestConnectionError } from "../integration/map-test-connection-error";
import { getOnboardingOrFallbackAsync, nextOnboardingStepAsync } from "./onboard-queries";
const logger = createLogger({ module: "onboardDockerDiscovery" });
interface PortInfo {
IP?: string;
PublicPort?: number;
@@ -43,6 +48,30 @@ interface SuggestedUrlResult {
publishedPort: number | null;
}
type DockerDiscoverySource = "label" | "docker";
interface DiscoveredIntegration {
containerId: string;
containerName: string;
kind: IntegrationKind;
suggestedUrl: string;
publishedPort: number | null;
iconUrl: string | null;
source: DockerDiscoverySource;
group?: string;
}
interface DiscoveredApp {
containerId: string;
containerName: string;
suggestedUrl: string;
publishedPort: number | null;
iconUrl: string | null;
source: DockerDiscoverySource;
group?: string;
host?: string;
}
const buildSuggestedUrl = (ports: PortInfo[] | undefined, host: string): SuggestedUrlResult => {
const port = ports?.[0];
if (port?.PublicPort) {
@@ -145,51 +174,91 @@ export const onboardRouter = createTRPCRouter({
}),
discoverDockerServices: onboardingProcedure.requiresStep("integrations").query(async ({ ctx }) => {
const emptyResult = {
integrations: [] as {
containerId: string;
containerName: string;
kind: IntegrationKind;
suggestedUrl: string;
publishedPort: number | null;
iconUrl: string | null;
}[],
apps: [] as {
containerId: string;
containerName: string;
suggestedUrl: string;
publishedPort: number | null;
iconUrl: string | null;
}[],
integrations: [] as DiscoveredIntegration[],
apps: [] as DiscoveredApp[],
};
try {
const { DockerSingleton, dockerLabels } = await import("@homarr/docker");
const { DockerSingleton, dockerLabels, listDiscoveredContainersAsync } = await import("@homarr/docker");
const serverSettings = await getServerSettingsAsync(ctx.db);
const labeledServices = await listDiscoveredContainersAsync({
readHomepageLabels: serverSettings.docker.readHomepageLabels,
});
const labeledContainerIds = new Set(labeledServices.map((service) => service.containerId));
const seenKinds = new Set<IntegrationKind>();
const discoveredIntegrations = emptyResult.integrations;
const discoveredApps = emptyResult.apps;
for (const service of labeledServices) {
if (service.integrationKind && !seenKinds.has(service.integrationKind)) {
seenKinds.add(service.integrationKind);
discoveredIntegrations.push({
containerId: service.containerId,
containerName: service.name,
kind: service.integrationKind,
suggestedUrl: service.href,
publishedPort: null,
iconUrl: service.icon ?? null,
source: "label",
group: service.group,
});
continue;
}
discoveredApps.push({
containerId: service.containerId,
containerName: service.name,
suggestedUrl: service.href,
publishedPort: null,
iconUrl: service.icon ?? null,
source: "label",
group: service.group,
host: service.host,
});
}
const dockerInstances = DockerSingleton.getInstances();
if (dockerInstances.length === 0) {
return { status: "empty" as const, ...emptyResult };
const hasResults = discoveredIntegrations.length > 0 || discoveredApps.length > 0;
return {
status: hasResults ? ("success" as const) : ("empty" as const),
integrations: discoveredIntegrations,
apps: discoveredApps,
};
}
const results = await Promise.allSettled(
dockerInstances.map(async ({ instance, host }) => {
const containerList = await instance.listContainers({ all: false });
return containerList.filter((c) => !(dockerLabels.hide in c.Labels)).map((c) => ({ ...c, host }));
return containerList
.filter((container) => !(dockerLabels.hide in container.Labels))
.filter((container) => !labeledContainerIds.has(container.Id))
.map((container) => ({ ...container, host }));
}),
);
const containers = results.flatMap((r) => (r.status === "fulfilled" ? r.value : []));
const containers = results.flatMap((result, index) => {
if (result.status === "fulfilled") {
return result.value;
}
if (containers.length === 0) {
logger.warn("Failed to list containers for onboarding discovery", {
host: dockerInstances[index]?.host,
cause: result.reason,
});
return [];
});
if (containers.length === 0 && discoveredIntegrations.length === 0 && discoveredApps.length === 0) {
return { status: "empty" as const, ...emptyResult };
}
const likeQueries = containers.map((c) => like(icons.name, `%${extractContainerImageName(c.Image)}%`));
const likeQueries = containers.map((container) =>
like(icons.name, `%${extractContainerImageName(container.Image)}%`),
);
const dbIcons = likeQueries.length > 0 ? await ctx.db.query.icons.findMany({ where: or(...likeQueries) }) : [];
const seenKinds = new Set<IntegrationKind>();
const discoveredIntegrations = emptyResult.integrations;
const discoveredApps = emptyResult.apps;
const cdnIconUrl = (slug: string) =>
`https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/${slug}.svg`;
@@ -223,6 +292,7 @@ export const onboardRouter = createTRPCRouter({
suggestedUrl,
publishedPort,
iconUrl,
source: "docker",
});
} else if (!kind && dbIcon) {
discoveredApps.push({
@@ -231,19 +301,61 @@ export const onboardRouter = createTRPCRouter({
suggestedUrl,
publishedPort,
iconUrl,
source: "docker",
host: container.host,
});
}
}
const hasResults = discoveredIntegrations.length > 0 || discoveredApps.length > 0;
return {
status: "success" as const,
status: hasResults ? ("success" as const) : ("empty" as const),
integrations: discoveredIntegrations,
apps: discoveredApps,
};
} catch {
} catch (error) {
logger.warn("Docker discovery failed during onboarding", { cause: error });
return { status: "unavailable" as const, ...emptyResult };
}
}),
syncDockerLabelApps: onboardingProcedure
.requiresStep("integrations")
.input(
z.array(
z.object({
containerId: z.string(),
host: z.string(),
}),
),
)
.mutation(async ({ ctx, input }) => {
if (input.length === 0) {
return { created: 0, updated: 0, skipped: 0, notFound: 0 };
}
const { listDiscoveredContainersAsync, syncDiscoveredServicesAsync } = await import("@homarr/docker");
const serverSettings = await getServerSettingsAsync(ctx.db);
const labeledServices = await listDiscoveredContainersAsync({
readHomepageLabels: serverSettings.docker.readHomepageLabels,
});
const selectedKeys = new Set(input.map((entry) => `${entry.host}/${entry.containerId}`));
const selectedServices = labeledServices.filter((service) =>
selectedKeys.has(`${service.host}/${service.containerId}`),
);
const syncResult = await syncDiscoveredServicesAsync(selectedServices, {
targetBoardName: serverSettings.docker.targetBoardName,
enableStatusByDefault: serverSettings.board.enableStatusByDefault,
forceDisableStatus: serverSettings.board.forceDisableStatus,
defaultItemWidth: serverSettings.docker.defaultItemWidth,
defaultItemHeight: serverSettings.docker.defaultItemHeight,
});
return {
...syncResult,
notFound: input.length - selectedServices.length,
};
}),
createAppsFromDiscovery: onboardingProcedure
.requiresStep("integrations")
.input(
@@ -257,9 +369,15 @@ export const onboardRouter = createTRPCRouter({
)
.mutation(async ({ ctx, input }) => {
if (input.length === 0) return;
const existingApps = await ctx.db.query.apps.findMany({ columns: { href: true } });
const existingHrefs = new Set(existingApps.map((app) => app.href).filter((href): href is string => Boolean(href)));
const appsToCreate = input.filter((app) => !app.href || !existingHrefs.has(app.href));
if (appsToCreate.length === 0) return;
const defaultIcon = "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/homarr.svg";
await ctx.db.insert(apps).values(
input.map((app) => ({
appsToCreate.map((app) => ({
id: createId(),
name: app.name,
iconUrl: app.iconUrl ?? defaultIcon,
@@ -270,16 +388,26 @@ export const onboardRouter = createTRPCRouter({
}),
setupIntegrations: onboardingProcedure.requiresStep("integrations").mutation(async ({ ctx }) => {
const db = ctx.db;
const serverSettings = await getServerSettingsAsync(db);
const allIntegrations = await db.query.integrations.findMany();
const allApps = await db.query.apps.findMany();
const labelSyncedAppIds = new Set(
(await db.query.dockerAppSources.findMany({ columns: { appId: true } })).map((source) => source.appId),
);
const appsForWidgetPlacement = allApps.filter((app) => !labelSyncedAppIds.has(app.id));
const board = await db.query.boards.findFirst({
const boardList = await db.query.boards.findMany({
orderBy: asc(boards.name),
with: {
sections: true,
layouts: true,
},
});
const targetBoardName = serverSettings.docker.targetBoardName;
const board = targetBoardName
? (boardList.find((entry) => entry.name === targetBoardName) ?? boardList.at(0))
: boardList.at(0);
if (!board) {
await nextOnboardingStepAsync(db, undefined);
@@ -297,15 +425,16 @@ export const onboardRouter = createTRPCRouter({
const layout = board.layouts[0];
if (section && layout) {
const existingItems = await db.query.items.findMany({
where: eq(items.boardId, board.id),
const emptySectionLayouts = await db.query.itemLayouts.findMany({
where: eq(itemLayouts.sectionId, section.id),
columns: { itemId: true },
});
for (const item of existingItems) {
await db.delete(integrationItems).where(eq(integrationItems.itemId, item.id));
await db.delete(itemLayouts).where(eq(itemLayouts.itemId, item.id));
}
if (existingItems.length > 0) {
await db.delete(items).where(eq(items.boardId, board.id));
const emptySectionItemIds = emptySectionLayouts.map((entry) => entry.itemId);
if (emptySectionItemIds.length > 0) {
await db.delete(integrationItems).where(inArray(integrationItems.itemId, emptySectionItemIds));
await db.delete(itemLayouts).where(inArray(itemLayouts.itemId, emptySectionItemIds));
await db.delete(items).where(inArray(items.id, emptySectionItemIds));
}
await placeAllWidgetsAsync(
@@ -317,7 +446,7 @@ export const onboardRouter = createTRPCRouter({
columnCount: layout.columnCount,
},
allIntegrations,
allApps,
appsForWidgetPlacement,
);
}