feat(onboarding): enhance integration setup with Docker discovery, URL templating, and API key helpers
Add automatic Docker container discovery during onboarding to pre-select and pre-fill integrations. Introduce base URL templating with subdomain/port modes, API key settings path links, and a curated onboarding list that hides niche integrations (GitHub, npm, Docker Hub, etc.). Prevent duplicate widget seeding and remove the timetable widget from defaults.
This commit is contained in:
18 files changed
+1056
-56
No files matched your search
@@ -5,9 +5,11 @@ import { z } from "zod/v4";
|
||||
import { createId } from "@homarr/common";
|
||||
import { encryptSecret } from "@homarr/common/server";
|
||||
import type { Database } from "@homarr/db";
|
||||
import { eq } from "@homarr/db";
|
||||
import { eq, like, or } from "@homarr/db";
|
||||
import {
|
||||
apps,
|
||||
groups,
|
||||
icons,
|
||||
integrationItems,
|
||||
integrations,
|
||||
integrationSecrets,
|
||||
@@ -20,12 +22,15 @@ import {
|
||||
defaultWidgetConfigs,
|
||||
emptySuperJSON,
|
||||
everyoneGroup,
|
||||
extractContainerImageName,
|
||||
getIconUrl,
|
||||
getWidgetKindsForIntegration,
|
||||
integrationKinds,
|
||||
integrationSecretKinds,
|
||||
matchIntegrationKindFromContainer,
|
||||
onboardingSteps,
|
||||
} from "@homarr/definitions";
|
||||
import type { WidgetKind } from "@homarr/definitions";
|
||||
import type { IntegrationKind, WidgetKind } from "@homarr/definitions";
|
||||
import { zodEnumFromArray } from "@homarr/validation/enums";
|
||||
|
||||
import { createTRPCRouter, onboardingProcedure, publicProcedure } from "../../trpc";
|
||||
@@ -33,6 +38,25 @@ import { MissingSecretError, testConnectionAsync } from "../integration/integrat
|
||||
import { mapTestConnectionError } from "../integration/map-test-connection-error";
|
||||
import { getOnboardingOrFallbackAsync, nextOnboardingStepAsync } from "./onboard-queries";
|
||||
|
||||
interface PortInfo {
|
||||
IP?: string;
|
||||
PublicPort?: number;
|
||||
}
|
||||
|
||||
interface SuggestedUrlResult {
|
||||
url: string;
|
||||
publishedPort: number | null;
|
||||
}
|
||||
|
||||
const buildSuggestedUrl = (ports: PortInfo[] | undefined, host: string): SuggestedUrlResult => {
|
||||
const port = ports?.[0];
|
||||
if (port?.PublicPort) {
|
||||
const ip = port.IP && port.IP !== "0.0.0.0" && port.IP !== "::" ? port.IP : host;
|
||||
return { url: `http://${ip}:${port.PublicPort}`, publishedPort: port.PublicPort };
|
||||
}
|
||||
return { url: "", publishedPort: null };
|
||||
};
|
||||
|
||||
const widgetConfigMap = new Map(defaultWidgetConfigs.map((config) => [config.kind, config]));
|
||||
|
||||
const getWidgetConfig = (kind: WidgetKind) => widgetConfigMap.get(kind);
|
||||
@@ -125,10 +149,7 @@ export const onboardRouter = createTRPCRouter({
|
||||
.input(
|
||||
z.object({
|
||||
name: z.string().nonempty().max(127),
|
||||
url: z
|
||||
.string()
|
||||
.url()
|
||||
.regex(/^https?:\/\//),
|
||||
url: z.string().nonempty(),
|
||||
kind: zodEnumFromArray(integrationKinds),
|
||||
secrets: z.array(
|
||||
z.object({
|
||||
@@ -159,12 +180,23 @@ export const onboardRouter = createTRPCRouter({
|
||||
}
|
||||
|
||||
const integrationId = createId();
|
||||
const appId = createId();
|
||||
|
||||
await ctx.db.insert(apps).values({
|
||||
id: appId,
|
||||
name: input.name,
|
||||
iconUrl: getIconUrl(input.kind),
|
||||
href: input.url,
|
||||
pingUrl: input.url,
|
||||
description: null,
|
||||
});
|
||||
|
||||
await ctx.db.insert(integrations).values({
|
||||
id: integrationId,
|
||||
name: input.name,
|
||||
url: input.url,
|
||||
kind: input.kind,
|
||||
appId: null,
|
||||
appId,
|
||||
});
|
||||
|
||||
if (input.secrets.length >= 1) {
|
||||
@@ -177,6 +209,103 @@ 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; iconUrl: string | null }[],
|
||||
};
|
||||
|
||||
try {
|
||||
const { DockerSingleton, dockerLabels } = await import("@homarr/docker");
|
||||
const { bestMatch } = await import("@homarr/common");
|
||||
|
||||
const dockerInstances = DockerSingleton.getInstances();
|
||||
if (dockerInstances.length === 0) {
|
||||
return { status: "empty" as const, ...emptyResult };
|
||||
}
|
||||
|
||||
const results = await Promise.allSettled(
|
||||
dockerInstances.map(async ({ instance, host }) => {
|
||||
const containerList = await instance.listContainers({ all: true });
|
||||
return containerList
|
||||
.filter((c) => !(dockerLabels.hide in c.Labels))
|
||||
.map((c) => ({ ...c, host }));
|
||||
}),
|
||||
);
|
||||
|
||||
const containers = results.flatMap((r) => (r.status === "fulfilled" ? r.value : []));
|
||||
|
||||
if (containers.length === 0) {
|
||||
return { status: "empty" as const, ...emptyResult };
|
||||
}
|
||||
|
||||
const likeQueries = containers.map((c) => like(icons.name, `%${extractContainerImageName(c.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;
|
||||
|
||||
for (const container of containers) {
|
||||
const imageName = extractContainerImageName(container.Image);
|
||||
const containerName = container.Names[0]?.split("/")[1] ?? "Unknown";
|
||||
const iconUrl = bestMatch(imageName, dbIcons, (icon) => icon.name)?.url ?? null;
|
||||
|
||||
const { url: suggestedUrl, publishedPort } = buildSuggestedUrl(container.Ports, container.host);
|
||||
|
||||
const kind = matchIntegrationKindFromContainer({ image: container.Image, name: containerName });
|
||||
|
||||
if (kind && !seenKinds.has(kind)) {
|
||||
seenKinds.add(kind);
|
||||
discoveredIntegrations.push({
|
||||
containerId: container.Id,
|
||||
containerName,
|
||||
kind,
|
||||
suggestedUrl,
|
||||
publishedPort,
|
||||
iconUrl,
|
||||
});
|
||||
} else if (!kind && iconUrl) {
|
||||
discoveredApps.push({
|
||||
containerId: container.Id,
|
||||
containerName,
|
||||
suggestedUrl,
|
||||
iconUrl,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return { status: "success" as const, integrations: discoveredIntegrations, apps: discoveredApps };
|
||||
} catch {
|
||||
return { status: "unavailable" as const, ...emptyResult };
|
||||
}
|
||||
}),
|
||||
createAppsFromDiscovery: onboardingProcedure
|
||||
.requiresStep("integrations")
|
||||
.input(
|
||||
z.array(
|
||||
z.object({
|
||||
name: z.string().nonempty().max(127),
|
||||
href: z.string().nullable(),
|
||||
iconUrl: z.string().nullable(),
|
||||
}),
|
||||
),
|
||||
)
|
||||
.mutation(async ({ ctx, input }) => {
|
||||
if (input.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) => ({
|
||||
id: createId(),
|
||||
name: app.name,
|
||||
iconUrl: app.iconUrl ?? defaultIcon,
|
||||
href: app.href,
|
||||
description: null,
|
||||
})),
|
||||
);
|
||||
}),
|
||||
setupIntegrations: onboardingProcedure.requiresStep("integrations").mutation(async ({ ctx }) => {
|
||||
const db = ctx.db;
|
||||
|
||||
@@ -206,6 +335,17 @@ 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),
|
||||
});
|
||||
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 widgetCtx: PlaceWidgetContext = {
|
||||
db,
|
||||
boardId: board.id,
|
||||
|
||||
@@ -0,0 +1,91 @@
|
||||
import { objectKeys } from "@homarr/common";
|
||||
|
||||
import { integrationDefs } from "./integration";
|
||||
import type { IntegrationKind } from "./integration";
|
||||
|
||||
export const extractContainerImageName = (image: string): string =>
|
||||
image.split("/").at(-1)?.split(":").at(0) ?? "";
|
||||
|
||||
const extractIconSlug = (iconUrl: string): string => {
|
||||
const filename = iconUrl.split("/").pop() ?? "";
|
||||
return filename.replace(/\.(svg|png)$/, "").toLowerCase();
|
||||
};
|
||||
|
||||
export const integrationIconSlugs: Record<IntegrationKind, string> = Object.fromEntries(
|
||||
objectKeys(integrationDefs).map((kind) => [kind, extractIconSlug(integrationDefs[kind].iconUrl)]),
|
||||
) as Record<IntegrationKind, string>;
|
||||
|
||||
const integrationAliases: Partial<Record<IntegrationKind, readonly string[]>> = {
|
||||
piHole: ["pihole", "pi-hole"],
|
||||
adGuardHome: ["adguardhome", "adguard-home", "adguard"],
|
||||
homeAssistant: ["homeassistant", "home-assistant", "hass"],
|
||||
openmediavault: ["omv"],
|
||||
qBittorrent: ["qbittorrent"],
|
||||
sabNzbd: ["sabnzbd"],
|
||||
nzbGet: ["nzbget"],
|
||||
unifiController: ["unifi", "unifi-controller"],
|
||||
jellyseerr: ["jellyseerr"],
|
||||
overseerr: ["overseerr"],
|
||||
dashDot: ["dashdot", "dash-dot", "dash."],
|
||||
speedtestTracker: ["speedtest-tracker"],
|
||||
searchCh: ["search-ch"],
|
||||
gitHubContainerRegistry: ["ghcr"],
|
||||
linuxServerIO: ["linuxserver"],
|
||||
coolify: ["coolify"],
|
||||
truenas: ["truenas"],
|
||||
};
|
||||
|
||||
export const matchIntegrationKind = (search: string): IntegrationKind | null => {
|
||||
const normalized = search.toLowerCase().trim();
|
||||
if (!normalized) return null;
|
||||
|
||||
for (const kind of objectKeys(integrationDefs)) {
|
||||
if (kind.toLowerCase() === normalized) return kind;
|
||||
if (integrationDefs[kind].name.toLowerCase() === normalized) return kind;
|
||||
}
|
||||
|
||||
for (const kind of objectKeys(integrationDefs)) {
|
||||
if (integrationIconSlugs[kind] === normalized) return kind;
|
||||
}
|
||||
|
||||
for (const [kind, aliases] of Object.entries(integrationAliases) as [IntegrationKind, readonly string[]][]) {
|
||||
if (aliases.some((alias) => alias === normalized)) return kind;
|
||||
}
|
||||
|
||||
for (const kind of objectKeys(integrationDefs)) {
|
||||
if (normalized.includes(kind.toLowerCase())) return kind;
|
||||
if (normalized.includes(integrationIconSlugs[kind])) return kind;
|
||||
}
|
||||
|
||||
return null;
|
||||
};
|
||||
|
||||
const notDockerDiscoverable = new Set<IntegrationKind>([
|
||||
"dockerHub",
|
||||
"github",
|
||||
"gitlab",
|
||||
"npm",
|
||||
"codeberg",
|
||||
"linuxServerIO",
|
||||
"gitHubContainerRegistry",
|
||||
"quay",
|
||||
"ical",
|
||||
"searchCh",
|
||||
"mock",
|
||||
]);
|
||||
|
||||
interface ContainerMatchInput {
|
||||
image: string;
|
||||
name: string;
|
||||
}
|
||||
|
||||
export const matchIntegrationKindFromContainer = (container: ContainerMatchInput): IntegrationKind | null => {
|
||||
const imageName = extractContainerImageName(container.image);
|
||||
const fromImage = matchIntegrationKind(imageName);
|
||||
if (fromImage && !notDockerDiscoverable.has(fromImage)) return fromImage;
|
||||
|
||||
const fromName = matchIntegrationKind(container.name);
|
||||
if (fromName && !notDockerDiscoverable.has(fromName)) return fromName;
|
||||
|
||||
return null;
|
||||
};
|
||||
@@ -15,3 +15,5 @@ export * from "./onboarding";
|
||||
export * from "./widget-integration-map";
|
||||
export * from "./emptysuperjson";
|
||||
export * from "./hotkeys";
|
||||
export * from "./docker-integration-match";
|
||||
export * from "./integration-url-template";
|
||||
@@ -0,0 +1,30 @@
|
||||
import { integrationIconSlugs } from "./docker-integration-match";
|
||||
import type { IntegrationKind } from "./integration";
|
||||
import { getIntegrationDefaultPort } from "./integration";
|
||||
|
||||
export type UrlTemplateMode = "hostPort" | "subdomain";
|
||||
|
||||
const getSlugForKind = (kind: IntegrationKind): string =>
|
||||
integrationIconSlugs[kind] ?? kind.toLowerCase();
|
||||
|
||||
export const buildIntegrationUrl = (
|
||||
kind: IntegrationKind,
|
||||
baseHost: string,
|
||||
mode: UrlTemplateMode,
|
||||
dockerPort?: number,
|
||||
): string => {
|
||||
const host = baseHost.trim().replace(/\/+$/, "");
|
||||
if (!host) return "";
|
||||
|
||||
const slug = getSlugForKind(kind);
|
||||
|
||||
const modeBuilders: Record<UrlTemplateMode, () => string> = {
|
||||
subdomain: () => `http://${slug}.${host}`,
|
||||
hostPort: () => {
|
||||
const port = dockerPort ?? getIntegrationDefaultPort(kind);
|
||||
return port ? `http://${host}:${port}` : `http://${host}`;
|
||||
},
|
||||
};
|
||||
|
||||
return modeBuilders[mode]();
|
||||
};
|
||||
@@ -27,7 +27,9 @@ interface integrationDefinition {
|
||||
secretKinds: AtLeastOneOf<IntegrationSecretKind[]>; // at least one secret kind set is required
|
||||
category: AtLeastOneOf<IntegrationCategory>;
|
||||
documentationUrl: string | null;
|
||||
defaultUrl?: string; // optional default URL for the integration
|
||||
defaultUrl?: string;
|
||||
defaultPort?: number;
|
||||
apiKeySettingsPath?: string;
|
||||
}
|
||||
|
||||
export const integrationDefs = {
|
||||
@@ -37,6 +39,8 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/sabnzbd.svg",
|
||||
category: ["downloadClient", "usenet"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/sabnzbd"),
|
||||
defaultPort: 8080,
|
||||
apiKeySettingsPath: "/config/general/",
|
||||
},
|
||||
nzbGet: {
|
||||
name: "NZBGet",
|
||||
@@ -44,6 +48,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/nzbget.svg",
|
||||
category: ["downloadClient", "usenet"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/nzbget"),
|
||||
defaultPort: 6789,
|
||||
},
|
||||
deluge: {
|
||||
name: "Deluge",
|
||||
@@ -51,6 +56,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/deluge.svg",
|
||||
category: ["downloadClient", "torrent"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/deluge"),
|
||||
defaultPort: 8112,
|
||||
},
|
||||
transmission: {
|
||||
name: "Transmission",
|
||||
@@ -58,6 +64,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/transmission.svg",
|
||||
category: ["downloadClient", "torrent"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/transmission"),
|
||||
defaultPort: 9091,
|
||||
},
|
||||
qBittorrent: {
|
||||
name: "qBittorrent",
|
||||
@@ -65,6 +72,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/qbittorrent.svg",
|
||||
category: ["downloadClient", "torrent"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/q-bittorent"),
|
||||
defaultPort: 8080,
|
||||
},
|
||||
aria2: {
|
||||
name: "Aria2",
|
||||
@@ -72,6 +80,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/PapirusDevelopmentTeam/papirus_icons@latest/src/system_downloads_3.svg",
|
||||
category: ["downloadClient", "torrent", "miscellaneous"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/aria2"),
|
||||
defaultPort: 6800,
|
||||
},
|
||||
slskd: {
|
||||
name: "Slskd",
|
||||
@@ -79,6 +88,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/slskd.svg",
|
||||
category: ["downloadClient", "miscellaneous"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/slskd"),
|
||||
defaultPort: 5030,
|
||||
},
|
||||
sonarr: {
|
||||
name: "Sonarr",
|
||||
@@ -86,6 +96,8 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/sonarr.svg",
|
||||
category: ["calendar"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/sonarr"),
|
||||
defaultPort: 8989,
|
||||
apiKeySettingsPath: "/settings/general",
|
||||
},
|
||||
radarr: {
|
||||
name: "Radarr",
|
||||
@@ -93,6 +105,8 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/radarr.svg",
|
||||
category: ["calendar"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/radarr"),
|
||||
defaultPort: 7878,
|
||||
apiKeySettingsPath: "/settings/general",
|
||||
},
|
||||
lidarr: {
|
||||
name: "Lidarr",
|
||||
@@ -100,6 +114,8 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/lidarr.svg",
|
||||
category: ["calendar"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/lidarr"),
|
||||
defaultPort: 8686,
|
||||
apiKeySettingsPath: "/settings/general",
|
||||
},
|
||||
readarr: {
|
||||
name: "Readarr",
|
||||
@@ -107,6 +123,8 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/readarr.svg",
|
||||
category: ["calendar"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/readarr"),
|
||||
defaultPort: 8787,
|
||||
apiKeySettingsPath: "/settings/general",
|
||||
},
|
||||
prowlarr: {
|
||||
name: "Prowlarr",
|
||||
@@ -114,6 +132,8 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/prowlarr.svg",
|
||||
category: ["indexerManager"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/prowlarr"),
|
||||
defaultPort: 9696,
|
||||
apiKeySettingsPath: "/settings/general",
|
||||
},
|
||||
jellyfin: {
|
||||
name: "Jellyfin",
|
||||
@@ -121,6 +141,8 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/jellyfin.svg",
|
||||
category: ["mediaService", "mediaRelease"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/jellyfin"),
|
||||
defaultPort: 8096,
|
||||
apiKeySettingsPath: "/web/index.html#!/dashboard/keys",
|
||||
},
|
||||
emby: {
|
||||
name: "Emby",
|
||||
@@ -128,6 +150,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/emby.svg",
|
||||
category: ["mediaService", "mediaRelease"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/emby"),
|
||||
defaultPort: 8096,
|
||||
},
|
||||
plex: {
|
||||
name: "Plex",
|
||||
@@ -135,6 +158,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/plex.svg",
|
||||
category: ["mediaService", "mediaRelease"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/plex"),
|
||||
defaultPort: 32400,
|
||||
},
|
||||
jellyseerr: {
|
||||
name: "Jellyseerr",
|
||||
@@ -142,6 +166,8 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/jellyseerr.svg",
|
||||
category: ["mediaSearch", "mediaRequest", "search"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/jellyseerr"),
|
||||
defaultPort: 5055,
|
||||
apiKeySettingsPath: "/settings",
|
||||
},
|
||||
seerr: {
|
||||
name: "Seerr",
|
||||
@@ -149,6 +175,8 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/seerr.svg",
|
||||
category: ["mediaSearch", "mediaRequest", "search"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/seerr"),
|
||||
defaultPort: 5055,
|
||||
apiKeySettingsPath: "/settings",
|
||||
},
|
||||
overseerr: {
|
||||
name: "Overseerr",
|
||||
@@ -156,6 +184,8 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/overseerr.svg",
|
||||
category: ["mediaSearch", "mediaRequest", "search"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/overseerr"),
|
||||
defaultPort: 5055,
|
||||
apiKeySettingsPath: "/settings",
|
||||
},
|
||||
piHole: {
|
||||
name: "Pi-hole",
|
||||
@@ -163,6 +193,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/pi-hole.svg",
|
||||
category: ["dnsHole"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/pi-hole"),
|
||||
defaultPort: 80,
|
||||
},
|
||||
adGuardHome: {
|
||||
name: "AdGuard Home",
|
||||
@@ -170,6 +201,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/adguard-home.svg",
|
||||
category: ["dnsHole"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/adguard-home"),
|
||||
defaultPort: 3000,
|
||||
},
|
||||
homeAssistant: {
|
||||
name: "Home Assistant",
|
||||
@@ -177,6 +209,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/home-assistant.svg",
|
||||
category: ["smartHomeServer", "calendar"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/home-assistant"),
|
||||
defaultPort: 8123,
|
||||
},
|
||||
openmediavault: {
|
||||
name: "OpenMediaVault",
|
||||
@@ -184,6 +217,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/openmediavault.svg",
|
||||
category: ["healthMonitoring"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/open-media-vault"),
|
||||
defaultPort: 80,
|
||||
},
|
||||
dashDot: {
|
||||
name: "Dash.",
|
||||
@@ -198,6 +232,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/glances.svg",
|
||||
category: ["healthMonitoring"],
|
||||
documentationUrl: null,
|
||||
defaultPort: 61208,
|
||||
},
|
||||
tdarr: {
|
||||
name: "Tdarr",
|
||||
@@ -205,6 +240,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/png/tdarr.png",
|
||||
category: ["mediaTranscoding"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/tdarr"),
|
||||
defaultPort: 8265,
|
||||
},
|
||||
proxmox: {
|
||||
name: "Proxmox",
|
||||
@@ -212,6 +248,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/proxmox.svg",
|
||||
category: ["healthMonitoring"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/proxmox"),
|
||||
defaultPort: 8006,
|
||||
},
|
||||
nextcloud: {
|
||||
name: "Nextcloud",
|
||||
@@ -219,6 +256,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/nextcloud.svg",
|
||||
category: ["calendar", "notifications"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/nextcloud"),
|
||||
defaultPort: 443,
|
||||
},
|
||||
unifiController: {
|
||||
name: "Unifi Controller",
|
||||
@@ -226,6 +264,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/png/unifi.png",
|
||||
category: ["networkController"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/unifi-controller"),
|
||||
defaultPort: 8443,
|
||||
},
|
||||
opnsense: {
|
||||
name: "OPNsense",
|
||||
@@ -233,6 +272,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/opnsense.svg",
|
||||
category: ["firewall"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/opnsense"),
|
||||
defaultPort: 443,
|
||||
},
|
||||
github: {
|
||||
name: "Github",
|
||||
@@ -304,6 +344,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/ntfy.svg",
|
||||
category: ["notifications"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/ntfy"),
|
||||
defaultPort: 80,
|
||||
},
|
||||
ical: {
|
||||
name: "iCal",
|
||||
@@ -318,6 +359,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/anchor.svg",
|
||||
category: ["notes"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/anchor"),
|
||||
defaultPort: 8080,
|
||||
},
|
||||
truenas: {
|
||||
name: "TrueNAS",
|
||||
@@ -325,6 +367,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/truenas.svg",
|
||||
category: ["healthMonitoring"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/truenas"),
|
||||
defaultPort: 80,
|
||||
},
|
||||
unraid: {
|
||||
name: "Unraid",
|
||||
@@ -332,6 +375,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/unraid.svg",
|
||||
category: ["healthMonitoring"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/unraid"),
|
||||
defaultPort: 80,
|
||||
},
|
||||
coolify: {
|
||||
name: "Coolify",
|
||||
@@ -340,12 +384,12 @@ export const integrationDefs = {
|
||||
category: ["healthMonitoring"],
|
||||
// @ts-expect-error - docs page will be created when integration is merged
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/coolify"),
|
||||
defaultPort: 8000,
|
||||
},
|
||||
searchCh: {
|
||||
name: "Search.ch",
|
||||
secretKinds: [[]],
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/search-ch.png",
|
||||
defaultUrl: "https://search.ch",
|
||||
category: ["timetable"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/search-ch"),
|
||||
},
|
||||
@@ -355,6 +399,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/immich.svg",
|
||||
category: ["photoService"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/immich"),
|
||||
defaultPort: 2283,
|
||||
},
|
||||
tracearr: {
|
||||
name: "Tracearr",
|
||||
@@ -362,6 +407,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/tracearr.svg",
|
||||
category: ["mediaMonitoring"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/tracearr"),
|
||||
defaultPort: 7040,
|
||||
},
|
||||
speedtestTracker: {
|
||||
name: "Speedtest Tracker",
|
||||
@@ -369,6 +415,7 @@ export const integrationDefs = {
|
||||
iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/png/speedtest-tracker.png",
|
||||
category: ["speedtest"],
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/speedtest-tracker"),
|
||||
defaultPort: 80,
|
||||
},
|
||||
umami: {
|
||||
name: "Umami",
|
||||
@@ -377,6 +424,7 @@ export const integrationDefs = {
|
||||
category: ["analytics"],
|
||||
defaultUrl: "https://api.umami.is/v1",
|
||||
documentationUrl: createDocumentationLink("/docs/integrations/umami"),
|
||||
defaultPort: 3000,
|
||||
},
|
||||
// This integration only returns mock data, it is used during development (but can also be used in production by directly going to the create page)
|
||||
mock: {
|
||||
@@ -418,6 +466,19 @@ export const getIntegrationDefaultUrl = (integration: IntegrationKind) => {
|
||||
return "defaultUrl" in definition ? definition.defaultUrl : undefined;
|
||||
};
|
||||
|
||||
export const getIntegrationDefaultPort = (kind: IntegrationKind): number | undefined => {
|
||||
const definition = integrationDefs[kind];
|
||||
return "defaultPort" in definition ? definition.defaultPort : undefined;
|
||||
};
|
||||
|
||||
export const getIntegrationApiKeyUrl = (integrationUrl: string, kind: IntegrationKind): string | null => {
|
||||
const definition = integrationDefs[kind];
|
||||
if (!("apiKeySettingsPath" in definition) || !definition.apiKeySettingsPath) return null;
|
||||
const base = integrationUrl.replace(/\/+$/, "");
|
||||
if (!base) return null;
|
||||
return `${base}${definition.apiKeySettingsPath}`;
|
||||
};
|
||||
|
||||
/**
|
||||
* Get all integration kinds that share a category, typed only by the kinds belonging to the category
|
||||
* @param category Category to filter by, belonging to IntegrationCategory
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { getIntegrationApiKeyUrl } from "../integration";
|
||||
|
||||
describe("getIntegrationApiKeyUrl", () => {
|
||||
it("builds URL for sonarr", () => {
|
||||
expect(getIntegrationApiKeyUrl("http://192.168.1.10:8989", "sonarr")).toBe(
|
||||
"http://192.168.1.10:8989/settings/general",
|
||||
);
|
||||
});
|
||||
|
||||
it("builds URL for jellyfin", () => {
|
||||
expect(getIntegrationApiKeyUrl("http://media.local:8096", "jellyfin")).toBe(
|
||||
"http://media.local:8096/web/index.html#!/dashboard/keys",
|
||||
);
|
||||
});
|
||||
|
||||
it("returns null for integrations without apiKeySettingsPath", () => {
|
||||
expect(getIntegrationApiKeyUrl("http://localhost", "plex")).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null for empty URL", () => {
|
||||
expect(getIntegrationApiKeyUrl("", "sonarr")).toBeNull();
|
||||
});
|
||||
|
||||
it("strips trailing slash from base URL", () => {
|
||||
expect(getIntegrationApiKeyUrl("http://sonarr.local/", "sonarr")).toBe(
|
||||
"http://sonarr.local/settings/general",
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,119 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
extractContainerImageName,
|
||||
matchIntegrationKind,
|
||||
matchIntegrationKindFromContainer,
|
||||
} from "../docker-integration-match";
|
||||
|
||||
describe("extractContainerImageName", () => {
|
||||
it("extracts name from full image reference", () => {
|
||||
expect(extractContainerImageName("linuxserver/sonarr:latest")).toBe("sonarr");
|
||||
});
|
||||
|
||||
it("extracts name from ghcr image", () => {
|
||||
expect(extractContainerImageName("ghcr.io/org/radarr:v5")).toBe("radarr");
|
||||
});
|
||||
|
||||
it("handles plain image name", () => {
|
||||
expect(extractContainerImageName("jellyfin")).toBe("jellyfin");
|
||||
});
|
||||
|
||||
it("handles empty string", () => {
|
||||
expect(extractContainerImageName("")).toBe("");
|
||||
});
|
||||
});
|
||||
|
||||
describe("matchIntegrationKind", () => {
|
||||
it("matches exact kind name", () => {
|
||||
expect(matchIntegrationKind("sonarr")).toBe("sonarr");
|
||||
});
|
||||
|
||||
it("matches case-insensitively", () => {
|
||||
expect(matchIntegrationKind("Sonarr")).toBe("sonarr");
|
||||
});
|
||||
|
||||
it("matches icon slug for pi-hole", () => {
|
||||
expect(matchIntegrationKind("pi-hole")).toBe("piHole");
|
||||
});
|
||||
|
||||
it("matches alias pihole", () => {
|
||||
expect(matchIntegrationKind("pihole")).toBe("piHole");
|
||||
});
|
||||
|
||||
it("matches alias adguardhome", () => {
|
||||
expect(matchIntegrationKind("adguardhome")).toBe("adGuardHome");
|
||||
});
|
||||
|
||||
it("matches alias homeassistant", () => {
|
||||
expect(matchIntegrationKind("homeassistant")).toBe("homeAssistant");
|
||||
});
|
||||
|
||||
it("matches substring in image name", () => {
|
||||
expect(matchIntegrationKind("hotio-sonarr")).toBe("sonarr");
|
||||
});
|
||||
|
||||
it("returns null for unknown", () => {
|
||||
expect(matchIntegrationKind("nginx")).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null for empty string", () => {
|
||||
expect(matchIntegrationKind("")).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("matchIntegrationKindFromContainer", () => {
|
||||
it("matches from image name first", () => {
|
||||
expect(
|
||||
matchIntegrationKindFromContainer({
|
||||
image: "linuxserver/sonarr:latest",
|
||||
name: "my-sonarr",
|
||||
}),
|
||||
).toBe("sonarr");
|
||||
});
|
||||
|
||||
it("falls back to container name", () => {
|
||||
expect(
|
||||
matchIntegrationKindFromContainer({
|
||||
image: "custom/myapp:latest",
|
||||
name: "radarr",
|
||||
}),
|
||||
).toBe("radarr");
|
||||
});
|
||||
|
||||
it("returns null when neither matches", () => {
|
||||
expect(
|
||||
matchIntegrationKindFromContainer({
|
||||
image: "nginx:latest",
|
||||
name: "web-proxy",
|
||||
}),
|
||||
).toBeNull();
|
||||
});
|
||||
|
||||
it("excludes dockerHub even when image contains docker", () => {
|
||||
expect(
|
||||
matchIntegrationKindFromContainer({
|
||||
image: "portainer/portainer-ce:latest",
|
||||
name: "docker-proxy",
|
||||
}),
|
||||
).toBeNull();
|
||||
});
|
||||
|
||||
it("excludes ical from container matching", () => {
|
||||
expect(
|
||||
matchIntegrationKindFromContainer({
|
||||
image: "ical-relay:latest",
|
||||
name: "ical",
|
||||
}),
|
||||
).toBeNull();
|
||||
});
|
||||
|
||||
it("excludes github from container matching", () => {
|
||||
expect(
|
||||
matchIntegrationKindFromContainer({
|
||||
image: "github-runner:latest",
|
||||
name: "github-actions",
|
||||
}),
|
||||
).toBeNull();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,40 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { getIntegrationDefaultPort } from "../integration";
|
||||
import { buildIntegrationUrl } from "../integration-url-template";
|
||||
|
||||
describe("buildIntegrationUrl", () => {
|
||||
it("builds subdomain URL", () => {
|
||||
expect(buildIntegrationUrl("sonarr", "homelab.local", "subdomain")).toBe("http://sonarr.homelab.local");
|
||||
});
|
||||
|
||||
it("builds hostPort URL with default port", () => {
|
||||
expect(buildIntegrationUrl("sonarr", "192.168.1.1", "hostPort")).toBe("http://192.168.1.1:8989");
|
||||
});
|
||||
|
||||
it("uses docker port over default port", () => {
|
||||
expect(buildIntegrationUrl("sonarr", "192.168.1.1", "hostPort", 9999)).toBe("http://192.168.1.1:9999");
|
||||
});
|
||||
|
||||
it("builds hostPort URL without port when none known", () => {
|
||||
expect(buildIntegrationUrl("mock", "192.168.1.1", "hostPort")).toBe("http://192.168.1.1");
|
||||
});
|
||||
|
||||
it("strips trailing slashes from host", () => {
|
||||
expect(buildIntegrationUrl("sonarr", "homelab.local/", "subdomain")).toBe("http://sonarr.homelab.local");
|
||||
});
|
||||
|
||||
it("returns empty string for empty host", () => {
|
||||
expect(buildIntegrationUrl("sonarr", "", "subdomain")).toBe("");
|
||||
});
|
||||
|
||||
it("uses pi-hole slug for subdomain mode", () => {
|
||||
expect(buildIntegrationUrl("piHole", "example.com", "subdomain")).toBe("http://pi-hole.example.com");
|
||||
});
|
||||
|
||||
it("reads default ports from integration definitions", () => {
|
||||
expect(getIntegrationDefaultPort("radarr")).toBe(7878);
|
||||
expect(getIntegrationDefaultPort("prowlarr")).toBe(9696);
|
||||
expect(getIntegrationDefaultPort("jellyfin")).toBe(8096);
|
||||
});
|
||||
});
|
||||
@@ -76,6 +76,19 @@ export const featuredIntegrations: readonly IntegrationKind[] = [
|
||||
"jellyfin",
|
||||
];
|
||||
|
||||
export const hiddenFromOnboarding = new Set<IntegrationKind>([
|
||||
"searchCh",
|
||||
"github",
|
||||
"dockerHub",
|
||||
"gitlab",
|
||||
"npm",
|
||||
"codeberg",
|
||||
"linuxServerIO",
|
||||
"gitHubContainerRegistry",
|
||||
"quay",
|
||||
"mock",
|
||||
]);
|
||||
|
||||
export const defaultBookmarkApps = [
|
||||
{
|
||||
name: "Homarr Docs",
|
||||
|
||||
@@ -7,6 +7,7 @@ import { createLogger } from "@homarr/core/infrastructure/logs";
|
||||
import { ErrorWithMetadata } from "@homarr/core/infrastructure/logs/error";
|
||||
import { db, like, or } from "@homarr/db";
|
||||
import { icons } from "@homarr/db/schema";
|
||||
import { extractContainerImageName } from "@homarr/definitions";
|
||||
import type { ContainerState } from "@homarr/docker";
|
||||
import { dockerLabels, DockerSingleton } from "@homarr/docker";
|
||||
|
||||
@@ -23,7 +24,7 @@ export const dockerContainersRequestHandler = createCachedWidgetRequestHandler({
|
||||
cacheDuration: dayjs.duration(20, "seconds"),
|
||||
});
|
||||
|
||||
const extractImage = (container: ContainerInfo) => container.Image.split("/").at(-1)?.split(":").at(0) ?? "";
|
||||
const extractImage = (container: ContainerInfo) => extractContainerImageName(container.Image);
|
||||
|
||||
async function getContainersWithStatsAsync() {
|
||||
const dockerInstances = DockerSingleton.getInstances();
|
||||
|
||||
@@ -101,7 +101,27 @@
|
||||
"configure": {
|
||||
"progress": "{current} of {total}",
|
||||
"skip": "Skip this integration",
|
||||
"finishing": "Setting up your dashboard..."
|
||||
"finishing": "Setting up your dashboard...",
|
||||
"helpers": {
|
||||
"tooltip": "URL helpers",
|
||||
"description": "These helpers try to guess the URL for your services. If it doesn't work, just type the address manually."
|
||||
}
|
||||
},
|
||||
"urlTemplate": {
|
||||
"label": "Base URL",
|
||||
"placeholder": "homelab.local or 192.168.1.1",
|
||||
"hint": "Enter your base domain or IP to auto-fill integration URLs",
|
||||
"preview": "e.g. {example}",
|
||||
"mode": {
|
||||
"subdomain": "Subdomain",
|
||||
"hostPort": "Host:Port"
|
||||
}
|
||||
},
|
||||
"docker": {
|
||||
"detected": "Docker detected {count} services",
|
||||
"detectedBreakdown": "{integrations} integrations · {apps} apps",
|
||||
"appBadge": "App",
|
||||
"appSectionLabel": "Also add {count} apps to dashboard"
|
||||
}
|
||||
},
|
||||
"finish": {
|
||||
@@ -744,6 +764,9 @@
|
||||
},
|
||||
"appHref": {
|
||||
"placeholder": "Custom application URL"
|
||||
},
|
||||
"apiKeySettings": {
|
||||
"label": "Get API key"
|
||||
}
|
||||
},
|
||||
"action": {
|
||||
|
||||
@@ -101,7 +101,27 @@
|
||||
"configure": {
|
||||
"progress": "{current} of {total}",
|
||||
"skip": "Skip this integration",
|
||||
"finishing": "Setting up your dashboard..."
|
||||
"finishing": "Setting up your dashboard...",
|
||||
"helpers": {
|
||||
"tooltip": "URL helpers",
|
||||
"description": "These helpers try to guess the URL for your services. If it doesn't work, just type the address manually."
|
||||
}
|
||||
},
|
||||
"urlTemplate": {
|
||||
"label": "Base URL",
|
||||
"placeholder": "homelab.local or 192.168.1.1",
|
||||
"hint": "Enter your base domain or IP to auto-fill integration URLs",
|
||||
"preview": "e.g. {example}",
|
||||
"mode": {
|
||||
"subdomain": "Subdomain",
|
||||
"hostPort": "Host:Port"
|
||||
}
|
||||
},
|
||||
"docker": {
|
||||
"detected": "Docker detected {count} services",
|
||||
"detectedBreakdown": "{integrations} integrations · {apps} apps",
|
||||
"appBadge": "App",
|
||||
"appSectionLabel": "Also add {count} apps to dashboard"
|
||||
}
|
||||
},
|
||||
"finish": {
|
||||
@@ -744,6 +764,9 @@
|
||||
},
|
||||
"appHref": {
|
||||
"placeholder": "Custom app URL"
|
||||
},
|
||||
"apiKeySettings": {
|
||||
"label": "Get API key"
|
||||
}
|
||||
},
|
||||
"action": {
|
||||
|
||||
Reference in new issue
Block a user