refactor(docker): simplify assisted service setup

apps/docs/docs/integrations/docker/index.mdx

@@ -192,15 +192,15 @@ Homarr can show a service as:
 - **Already represented** or **Linked** when an app or integration already matches
 - **Address changed** when a service appears to match an integration but its reachable address has changed
 
-Suggested addresses are ranked and explain where they came from. A published address or Docker endpoint host is normally usable from a browser; a container-name address is server-only and requires Homarr to share the container network. Wildcard addresses such as `0.0.0.0` are never offered as browser destinations. You can edit every suggestion before continuing.
+Set the usual server address once, then choose whether services normally use different ports, subdomains, or paths. Homarr uses that pattern to prefill every detected service. Each suggestion has one editable URL field with the generated and Docker-reported addresses available as autocomplete options, so you can select a suggestion or type any address directly.
 
 :::info[Review before changing]
-Service discovery is read-only. Homarr never creates or changes an app or integration automatically; use the action on an individual suggestion to review and confirm its setup.
+Service discovery is read-only. Homarr never creates or changes an app or integration automatically. **Set up integration** opens the standard prefilled integration form, while **Create app** opens the existing Docker app form, so you can review and confirm the final setup.
 :::
 
-Suggestions appear as a compact task list. Expand an item only when you want to inspect its address, match confidence, or observed health layers. Use the filters to focus on services that need attention or those already represented in Homarr. Refresh runs discovery again. Dismissed suggestions are stored in the current browser using their endpoint-qualified service identity and can be restored from the same helper. If multiple existing items could match, Homarr marks the result as ambiguous and does not choose one automatically.
+Suggestions appear as a compact task list. Expand an item only when you want to edit its URL or inspect relevant setup statuses. Use the filters to focus on services that need attention or those already represented in Homarr. Refresh runs discovery again. Dismissed suggestions are stored in the current browser using their endpoint-qualified service identity and can be restored from the same helper. If multiple existing items could match, Homarr marks the result as ambiguous and does not choose one automatically.
 
-The health badges are an evidence-based projection across Docker, integration configuration, app representation, and persisted widget links. Authentication, API request success, and widget query execution are labeled **Not observed** because Homarr does not currently retain trustworthy last-run results for these layers. Use the suggested integration test or board action to diagnose them live; **Not observed** is never presented as healthy.
+Compact status icons summarize the setup information Homarr can act on. Unknown and non-applicable runtime layers are omitted to keep the helper focused; use the integration form's connection test or the relevant board action for live diagnostics.
 
 If one Docker endpoint is unavailable, Homarr reports that endpoint while continuing to show services from healthy endpoints. An unavailable endpoint is not treated as an empty Docker installation.
 

apps/nextjs/src/app/[locale]/manage/tools/docker/docker-reconciliation-inbox.spec.ts

@@ -1,10 +1,6 @@
 import { describe, expect, test } from "vitest";
 
-import {
-  dismissDockerReconciliationCandidate,
-  filterDockerReconciliationInbox,
-  getValidDockerServiceUrl,
-} from "./docker-reconciliation-inbox";
+import { dismissDockerReconciliationCandidate, filterDockerReconciliationInbox } from "./docker-reconciliation-inbox";
 
 const candidates = [
   { candidateKey: "home:new", state: "newRecognized" as const },
@@ -36,10 +32,4 @@ describe("Docker reconciliation inbox", () => {
     });
     expect(dismissDockerReconciliationCandidate(dismissed, "home:new")).toBe(dismissed);
   });
-
-  test("accepts only HTTP service URLs", () => {
-    expect(getValidDockerServiceUrl("https://service.example.com")).toBe("https://service.example.com/");
-    expect(getValidDockerServiceUrl("ftp://service.example.com")).toBeNull();
-    expect(getValidDockerServiceUrl("service.example.com")).toBeNull();
-  });
 });

apps/nextjs/src/app/[locale]/manage/tools/docker/docker-reconciliation-inbox.ts

@@ -23,12 +23,3 @@ export const filterDockerReconciliationInbox = <Candidate extends DockerReconcil
 
 export const dismissDockerReconciliationCandidate = (dismissedCandidateKeys: string[], candidateKey: string) =>
   dismissedCandidateKeys.includes(candidateKey) ? dismissedCandidateKeys : [...dismissedCandidateKeys, candidateKey];
-
-export const getValidDockerServiceUrl = (value: string) => {
-  try {
-    const url = new URL(value);
-    return url.protocol === "http:" || url.protocol === "https:" ? url.toString() : null;
-  } catch {
-    return null;
-  }
-};

apps/nextjs/src/app/[locale]/manage/tools/docker/docker-reconciliation.tsx

@@ -5,6 +5,7 @@ import {
   Accordion,
   ActionIcon,
   Alert,
+  Autocomplete,
   Avatar,
   Badge,
   Button,
@@ -13,43 +14,45 @@ import {
   Group,
   Paper,
   SegmentedControl,
-  Select,
   SimpleGrid,
   Stack,
   Text,
-  TextInput,
   ThemeIcon,
   Tooltip,
 } from "@mantine/core";
 import { useLocalStorage } from "@mantine/hooks";
 import {
   IconAlertTriangle,
-  IconArrowRight,
+  IconApps,
+  IconCheck,
   IconChevronDown,
+  IconEye,
   IconEyeOff,
-  IconRefresh,
   IconBrandDocker,
+  IconMinus,
+  IconPlugConnected,
+  IconRefresh,
+  IconSettings,
 } from "@tabler/icons-react";
 
 import type { RouterOutputs } from "@homarr/api";
 import { clientApi } from "@homarr/api/client";
-import { getIntegrationName } from "@homarr/definitions";
+import type { UrlTemplateMode } from "@homarr/definitions";
+import { buildAppUrl, buildIntegrationUrl, getIntegrationDefaultPort, getIntegrationName } from "@homarr/definitions";
 import { useModalAction } from "@homarr/modals";
 import { AddDockerAppToHomarr } from "@homarr/modals-collection";
 import { showErrorNotification } from "@homarr/notifications";
-import { useScopedI18n } from "@homarr/translation/client";
+import { normalizeServiceUrl, ServiceUrlTemplate } from "@homarr/onboarding";
+import { useI18n, useScopedI18n } from "@homarr/translation/client";
 import { Link } from "@homarr/ui";
+import { IntegrationSelectModal } from "~/components/integration/integration-select-modal";
 import type { DockerReconciliationInboxFilter } from "./docker-reconciliation-inbox";
-import {
-  dismissDockerReconciliationCandidate,
-  filterDockerReconciliationInbox,
-  getValidDockerServiceUrl,
-} from "./docker-reconciliation-inbox";
+import { dismissDockerReconciliationCandidate, filterDockerReconciliationInbox } from "./docker-reconciliation-inbox";
 
 type ReconciliationCandidate = RouterOutputs["docker"]["reconcileServices"]["candidates"][number];
 type ServiceHealth = RouterOutputs["docker"]["getServiceHealth"]["services"][number];
 
-export const DockerReconciliation = () => {
+export const DockerReconciliation = ({ defaultServerOrigin }: { defaultServerOrigin: string }) => {
   const t = useScopedI18n("docker.reconciliation");
   const utils = clientApi.useUtils();
   const panelId = useId();
@@ -79,6 +82,14 @@ export const DockerReconciliation = () => {
     key: "homarr-docker-reconciliation-dismissed",
     defaultValue: [],
   });
+  const [serverOrigin, setServerOrigin] = useLocalStorage({
+    key: "homarr-docker-service-origin",
+    defaultValue: defaultServerOrigin,
+  });
+  const [urlMode, setUrlMode] = useLocalStorage<UrlTemplateMode>({
+    key: "homarr-docker-service-url-mode",
+    defaultValue: "hostPort",
+  });
 
   if (reconciliation.isError) {
     return (
@@ -119,9 +130,6 @@ export const DockerReconciliation = () => {
                   {t("suggestions", { count: String(attentionCount) })}
                 </Badge>
               </Group>
-              <Text c="dimmed" size="sm">
-                {t("description")}
-              </Text>
             </div>
           </Group>
           <Button
@@ -144,6 +152,13 @@ export const DockerReconciliation = () => {
         <Collapse id={panelId} expanded={isOpen}>
           <Divider mb="sm" />
           <Stack gap="sm">
+            <ServiceUrlTemplate
+              serverOrigin={serverOrigin}
+              onServerOriginChange={setServerOrigin}
+              mode={urlMode}
+              onModeChange={setUrlMode}
+            />
+
             <Group justify="space-between">
               <SegmentedControl
                 size="xs"
@@ -184,12 +199,14 @@ export const DockerReconciliation = () => {
                 {reconciliation.data.candidates.length === 0 ? t("empty") : t("emptyFilter")}
               </Text>
             ) : (
-              <Accordion multiple variant="separated" radius="sm" chevronPosition="left">
+              <Accordion multiple variant="separated" radius="sm" chevron={null}>
                 {candidates.map((candidate) => (
                   <DockerReconciliationCandidate
                     key={candidate.candidateKey}
                     candidate={candidate}
                     health={health.data?.services.find(({ key }) => key === candidate.candidateKey)}
+                    serverOrigin={serverOrigin}
+                    urlMode={urlMode}
                     onDismiss={() =>
                       setDismissedCandidateKeys((current) =>
                         dismissDockerReconciliationCandidate(current, candidate.candidateKey),
@@ -209,82 +226,99 @@ export const DockerReconciliation = () => {
 const DockerReconciliationCandidate = ({
   candidate,
   health,
+  serverOrigin,
+  urlMode,
   onDismiss,
 }: {
   candidate: ReconciliationCandidate;
   health: ServiceHealth | undefined;
+  serverOrigin: string;
+  urlMode: UrlTemplateMode;
   onDismiss: () => void;
 }) => {
   const t = useScopedI18n("docker.reconciliation");
-  const { openModal } = useModalAction(AddDockerAppToHomarr);
-  const initialUrlCandidate =
-    candidate.urlCandidates.find(
-      ({ url, scopes }) => url.length > 0 && (candidate.match ? true : scopes.includes("browser")),
-    ) ?? candidate.urlCandidates.find(({ source }) => source === "manual");
-  const [selectedCandidateId, setSelectedCandidateId] = useState(initialUrlCandidate?.id ?? null);
-  const [url, setUrl] = useState(initialUrlCandidate?.url ?? "");
-  const selectedCandidate = candidate.urlCandidates.find(({ id }) => id === selectedCandidateId);
-  const validatedUrl = getValidDockerServiceUrl(url);
-  const isInvalidUrl = url.length > 0 && validatedUrl === null;
-  const target = getCandidateTarget(candidate, validatedUrl ?? "");
+  const tGlobal = useI18n();
+  const { openModal: openAppModal } = useModalAction(AddDockerAppToHomarr);
+  const { openModal: openIntegrationModal } = useModalAction(IntegrationSelectModal);
+  const templateUrl = getTemplateUrl(candidate, serverOrigin, urlMode);
+  const urlSuggestions = Array.from(
+    new Set([templateUrl, ...candidate.urlCandidates.map(({ url }) => url)].filter((url) => url.length > 0)),
+  );
+  const initialUrl = urlSuggestions[0] ?? "";
+  const [url, setUrl] = useState(initialUrl);
+  const target = getCandidateTarget(candidate);
   const actionNeedsUrl = target.kind === "createApp" || target.kind === "setupIntegration";
-  const isActionDisabled = actionNeedsUrl && validatedUrl === null;
+  const visibleHealthLayers =
+    health?.layers.filter(({ status }) => status !== "notApplicable" && status !== "notObserved") ?? [];
 
   useEffect(() => {
-    setSelectedCandidateId(initialUrlCandidate?.id ?? null);
-    setUrl(initialUrlCandidate?.url ?? "");
-  }, [initialUrlCandidate?.id, initialUrlCandidate?.url]);
+    setUrl(initialUrl);
+  }, [initialUrl]);
 
   return (
     <Accordion.Item value={candidate.candidateKey}>
       <Group wrap="nowrap" gap={4} pr="sm">
-        <Accordion.Control style={{ flex: 1 }}>
-          <Group wrap="nowrap" style={{ minWidth: 0 }}>
+        <Accordion.Control
+          style={{ flex: 1 }}
+          icon={
             <Avatar src={candidate.container.iconUrl} radius="sm" size="sm">
               {candidate.container.name.at(0)?.toUpperCase()}
             </Avatar>
-            <div style={{ minWidth: 0 }}>
-              <Group gap="xs" wrap="nowrap">
-                <Text fw={600} size="sm" truncate>
-                  {candidate.container.name}
-                </Text>
-                <Badge color={stateColor(candidate.state)} variant="light" size="xs">
-                  {t(`state.${candidate.state}`)}
-                </Badge>
-              </Group>
-              <Text c="dimmed" size="xs">
-                {candidate.endpointName}
+          }
+        >
+          <div style={{ minWidth: 0 }}>
+            <Group gap="xs" wrap="nowrap">
+              <Text fw={600} size="sm" truncate>
+                {candidate.container.name}
               </Text>
-            </div>
-          </Group>
+              <Badge color={stateColor(candidate.state)} variant="light" size="xs">
+                {t(`state.${candidate.state}`)}
+              </Badge>
+            </Group>
+            <Text c="dimmed" size="xs">
+              {candidate.endpointName}
+            </Text>
+          </div>
         </Accordion.Control>
         <Group gap={4} wrap="nowrap">
-          {target.kind === "createApp" ? (
+          {target.kind === "createApp" && (
             <Button
               variant="light"
               size="compact-xs"
-              rightSection={<IconArrowRight size={14} />}
-              disabled={isActionDisabled}
+              leftSection={<IconApps size={14} />}
               onClick={() =>
-                openModal({
+                openAppModal({
                   selectedContainers: [candidate.container],
-                  initialUrls: validatedUrl ? [validatedUrl] : undefined,
+                  initialUrls: [(normalizeServiceUrl(url) ?? url) || null],
                 })
               }
             >
               {t("action.createApp")}
             </Button>
-          ) : (
+          )}
+          {target.kind === "setupIntegration" && (
+            <Button
+              variant="light"
+              size="compact-xs"
+              leftSection={<IconPlugConnected size={14} />}
+              onClick={() =>
+                openIntegrationModal({
+                  initialKind: target.integrationKind,
+                  initialName: candidate.container.name,
+                  initialUrl: normalizeServiceUrl(url) ?? url,
+                })
+              }
+            >
+              {t("action.setupIntegration")}
+            </Button>
+          )}
+          {(target.kind === "reviewIntegration" || target.kind === "viewRepresentation") && (
             <Button
               component={Link}
               href={target.href}
               variant="light"
               size="compact-xs"
-              rightSection={<IconArrowRight size={14} />}
-              disabled={isActionDisabled}
-              onClick={(event) => {
-                if (isActionDisabled) event.preventDefault();
-              }}
+              leftSection={target.kind === "reviewIntegration" ? <IconSettings size={14} /> : <IconEye size={14} />}
             >
               {t(`action.${target.kind}`)}
             </Button>
@@ -299,64 +333,36 @@ const DockerReconciliationCandidate = ({
 
       <Accordion.Panel>
         <Stack gap="sm">
-          {candidate.match && (
-            <Group gap="xs">
-              <Badge variant="outline" size="sm">
-                {candidate.match.kind}
-              </Badge>
-              <Text c="dimmed" size="xs">
-                {t("match", { confidence: t(`confidence.${candidate.match.confidence}`) })}
-              </Text>
-            </Group>
-          )}
-
           {candidate.representation.signals.ambiguous && (
             <Alert color="yellow" icon={<IconAlertTriangle size={16} />}>
               {t("ambiguous")}
             </Alert>
           )}
 
-          {health && (
-            <div>
-              <Text c="dimmed" size="xs" mb={4}>
-                {t("health.title")}
-              </Text>
-              <Group gap={4}>
-                {health.layers.map((layer) => (
-                  <Badge key={layer.layer} color={healthStatusColor(layer.status)} variant="dot" size="sm">
-                    {t(`health.layer.${layer.layer}`)}: {t(`health.status.${layer.status}`)}
-                  </Badge>
-                ))}
-              </Group>
-            </div>
+          {visibleHealthLayers.length > 0 && (
+            <SimpleGrid cols={{ base: 1, sm: 2, lg: 3 }} spacing="xs">
+              {visibleHealthLayers.map((layer) => (
+                <Group key={layer.layer} gap="xs" wrap="nowrap">
+                  <HealthStatusIcon status={layer.status} />
+                  <Text size="xs">
+                    {t(`health.layer.${layer.layer}`)} ·{" "}
+                    <Text component="span" c="dimmed" inherit>
+                      {t(`health.status.${layer.status}`)}
+                    </Text>
+                  </Text>
+                </Group>
+              ))}
+            </SimpleGrid>
           )}
 
           {actionNeedsUrl && (
-            <SimpleGrid cols={{ base: 1, sm: 2 }}>
-              <Select
-                label={t("url.label")}
-                description={
-                  selectedCandidate ? t(`reason.${selectedCandidate.reason}`) : t("reason.manualHostRequired")
-                }
-                value={selectedCandidateId}
-                data={candidate.urlCandidates.map((item) => ({
-                  value: item.id,
-                  label: item.url || t("url.manual"),
-                }))}
-                onChange={(value) => {
-                  setSelectedCandidateId(value);
-                  setUrl(candidate.urlCandidates.find(({ id }) => id === value)?.url ?? "");
-                }}
-              />
-              <TextInput
-                label={t("url.inputLabel")}
-                aria-label={t("url.inputLabel")}
-                value={url}
-                placeholder="https://service.example.com"
-                error={isInvalidUrl ? t("url.invalid") : undefined}
-                onChange={(event) => setUrl(event.currentTarget.value)}
-              />
-            </SimpleGrid>
+            <Autocomplete
+              label={tGlobal("integration.field.url.label")}
+              value={url}
+              data={urlSuggestions}
+              placeholder={t("url.manual")}
+              onChange={setUrl}
+            />
           )}
         </Stack>
       </Accordion.Panel>
@@ -364,7 +370,7 @@ const DockerReconciliationCandidate = ({
   );
 };
 
-const getCandidateTarget = (candidate: ReconciliationCandidate, url: string) => {
+const getCandidateTarget = (candidate: ReconciliationCandidate) => {
   if (candidate.representation.signals.ambiguous) {
     if (candidate.nextAction === "reviewIntegration" && candidate.match) {
       const params = new URLSearchParams({ search: getIntegrationName(candidate.match.kind) });
@@ -373,9 +379,7 @@ const getCandidateTarget = (candidate: ReconciliationCandidate, url: string) =>
     return { kind: "viewRepresentation" as const, href: "/manage/apps" };
   }
   if (candidate.state === "newRecognized" && candidate.match) {
-    const params = new URLSearchParams({ kind: candidate.match.kind, name: candidate.container.name });
-    if (url) params.set("url", url);
-    return { kind: "setupIntegration" as const, href: `/manage/integrations/new?${params.toString()}` };
+    return { kind: "setupIntegration" as const, integrationKind: candidate.match.kind };
   }
 
   if (candidate.state === "newApp") return { kind: "createApp" as const };
@@ -398,8 +402,39 @@ const stateColor = (state: ReconciliationCandidate["state"]) => {
   return "blue";
 };
 
-const healthStatusColor = (status: ServiceHealth["layers"][number]["status"]) => {
-  if (["available", "configured", "linked"].includes(status)) return "green";
-  if (["missing", "changed", "unused"].includes(status)) return "yellow";
-  return "gray";
+const getTemplateUrl = (candidate: ReconciliationCandidate, serverOrigin: string, urlMode: UrlTemplateMode) => {
+  if (!serverOrigin.trim()) return "";
+
+  const tcpPorts = candidate.container.ports?.filter(({ Type }) => Type.toLowerCase() === "tcp") ?? [];
+  let publishedPort = tcpPorts.find(({ PublicPort }) => PublicPort)?.PublicPort;
+
+  if (candidate.match) {
+    const defaultPort = getIntegrationDefaultPort(candidate.match.kind);
+    const preferredPort = tcpPorts.find(
+      ({ PrivatePort, PublicPort }) => PrivatePort === defaultPort && PublicPort !== undefined,
+    );
+    publishedPort = preferredPort?.PublicPort ?? publishedPort;
+    return buildIntegrationUrl(candidate.match.kind, serverOrigin, urlMode, publishedPort);
+  }
+
+  return buildAppUrl(candidate.container.name, serverOrigin, urlMode, publishedPort);
+};
+
+const HealthStatusIcon = ({ status }: { status: ServiceHealth["layers"][number]["status"] }) => {
+  let color = "gray";
+  let icon = <IconMinus size={12} />;
+
+  if (["available", "configured", "linked"].includes(status)) {
+    color = "green";
+    icon = <IconCheck size={12} />;
+  } else if (["missing", "changed", "unused"].includes(status)) {
+    color = "yellow";
+    icon = <IconAlertTriangle size={12} />;
+  }
+
+  return (
+    <ThemeIcon color={color} variant="light" radius="xl" size="sm">
+      {icon}
+    </ThemeIcon>
+  );
 };

apps/nextjs/src/app/[locale]/manage/tools/docker/page.tsx

@@ -1,8 +1,10 @@
+import { headers } from "next/headers";
 import { notFound } from "next/navigation";
 import { Stack, Title } from "@mantine/core";
 
 import { api } from "@homarr/api/server";
 import { auth } from "@homarr/auth/next";
+import { extractBaseUrlFromHeaders } from "@homarr/common";
 import { env } from "@homarr/docker/env";
 import { getScopedI18n } from "@homarr/translation/server";
 
@@ -16,7 +18,10 @@ export default async function DockerPage() {
     notFound();
   }
 
-  const { containers, endpoints, timestamp } = await api.docker.getContainers();
+  const [{ containers, endpoints, timestamp }, requestHeaders] = await Promise.all([
+    api.docker.getContainers(),
+    headers(),
+  ]);
   const tDocker = await getScopedI18n("docker");
 
   return (
@@ -24,7 +29,7 @@ export default async function DockerPage() {
       <DynamicBreadcrumb />
       <Stack>
         <Title order={1}>{tDocker("title")}</Title>
-        <DockerReconciliation />
+        <DockerReconciliation defaultServerOrigin={extractBaseUrlFromHeaders(requestHeaders)} />
         <DockerTable initialData={{ containers, endpoints, timestamp }} />
       </Stack>
     </>

apps/nextjs/src/components/integration/integration-select-modal.tsx

@@ -19,11 +19,14 @@ interface IntegrationSelectModalProps {
   enableMockIntegration?: boolean;
   allowedKinds?: readonly IntegrationKind[];
   completionBoardId?: string;
+  initialKind?: IntegrationKind;
+  initialUrl?: string;
+  initialName?: string;
 }
 
 export const IntegrationSelectModal = createModal<IntegrationSelectModalProps>(({ actions, innerProps }) => {
-  const [step, setStep] = useState<"select" | "form">("select");
-  const [selectedKind, setSelectedKind] = useState<IntegrationKind | null>(null);
+  const [step, setStep] = useState<"select" | "form">(innerProps.initialKind ? "form" : "select");
+  const [selectedKind, setSelectedKind] = useState<IntegrationKind | null>(innerProps.initialKind ?? null);
   const { openModal: openCompletionModal } = useModalAction(IntegrationCompletionModal);
 
   const handleSelect = (kind: IntegrationKind) => {
@@ -35,6 +38,7 @@ export const IntegrationSelectModal = createModal<IntegrationSelectModalProps>((
     setStep("select");
     setSelectedKind(null);
   };
+  const handleFormBack = innerProps.initialKind ? actions.closeModal : handleBack;
 
   const handleSuccess = (result?: CreatedIntegrationResult) => {
     actions.closeModal();
@@ -48,12 +52,18 @@ export const IntegrationSelectModal = createModal<IntegrationSelectModalProps>((
   if (step === "form" && selectedKind) {
     return (
       <ScrollArea.Autosize mah="80vh">
-        <Group gap="xs" mb="md" style={{ cursor: "pointer" }} onClick={handleBack}>
+        <Group gap="xs" mb="md" style={{ cursor: "pointer" }} onClick={handleFormBack}>
           <IconArrowLeft size={18} />
           <IntegrationAvatar kind={selectedKind} size="sm" />
           <Title order={4}>{getIntegrationName(selectedKind)}</Title>
         </Group>
-        <NewIntegrationForm kind={selectedKind} onSuccess={handleSuccess} onCancel={handleBack} />
+        <NewIntegrationForm
+          kind={selectedKind}
+          initialUrl={innerProps.initialUrl}
+          initialName={innerProps.initialName}
+          onSuccess={handleSuccess}
+          onCancel={handleFormBack}
+        />
       </ScrollArea.Autosize>
     );
   }

packages/modals-collection/src/docker/add-docker-app-to-homarr.tsx

@@ -8,35 +8,35 @@ import { useZodForm } from "@homarr/form";
 import { createModal } from "@homarr/modals";
 import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
 import { useI18n } from "@homarr/translation/client";
+import { appHrefSchema } from "@homarr/validation/app";
 
 interface AddDockerAppToHomarrProps {
   selectedContainers: RouterOutputs["docker"]["getContainers"]["containers"];
-  initialUrls?: string[];
+  initialUrls?: (string | null)[];
 }
 
+const formSchema = z.object({
+  containerUrls: z.array(appHrefSchema),
+});
+
 export const AddDockerAppToHomarrModal = createModal<AddDockerAppToHomarrProps>(({ actions, innerProps }) => {
   const t = useI18n();
-  const form = useZodForm(
-    z.object({
-      containerUrls: z.array(z.string().url().nullable()),
-    }),
-    {
-      initialValues: {
-        containerUrls: innerProps.selectedContainers.map((container, index) => {
-          const initialUrl = innerProps.initialUrls?.[index];
-          if (initialUrl) return initialUrl;
+  const form = useZodForm(formSchema, {
+    initialValues: {
+      containerUrls: innerProps.selectedContainers.map((container, index) => {
+        const initialUrl = innerProps.initialUrls?.[index];
+        if (initialUrl !== undefined) return initialUrl;
 
-          const candidates = buildDockerServiceUrlCandidates({
-            containerName: container.name,
-            endpointHost: container.host,
-            ports: container.ports,
-          }).filter(({ url }) => url.length > 0);
+        const candidates = buildDockerServiceUrlCandidates({
+          containerName: container.name,
+          endpointHost: container.host,
+          ports: container.ports,
+        }).filter(({ url }) => url.length > 0);
 
-          return candidates.find(({ scopes }) => scopes.includes("browser"))?.url ?? candidates[0]?.url ?? null;
-        }),
-      },
+        return candidates.find(({ scopes }) => scopes.includes("browser"))?.url ?? candidates[0]?.url ?? null;
+      }),
     },
-  );
+  });
   const { mutate, isPending } = clientApi.app.createMany.useMutation({
     onSuccess() {
       actions.closeModal();
@@ -52,13 +52,13 @@ export const AddDockerAppToHomarrModal = createModal<AddDockerAppToHomarrProps>(
       });
     },
   });
-  const handleSubmit = () => {
+  const handleSubmit = ({ containerUrls }: z.infer<typeof formSchema>) => {
     mutate(
       innerProps.selectedContainers.map((container, index) => ({
         name: container.name,
         iconUrl: container.iconUrl,
         description: null,
-        href: form.values.containerUrls[index] ?? null,
+        href: containerUrls[index] ?? null,
         pingUrl: null,
       })),
     );

packages/onboarding/src/index.ts

@@ -1,3 +1,5 @@
 export { OnboardingAuthShell } from "./onboarding-auth-shell";
 export { OnboardingStudio } from "./onboarding-studio";
+export { normalizeServiceUrl } from "./discovery-selection";
+export { ServiceUrlTemplate } from "./service-url-template";
 export type { OnboardingEnvironment, OnboardingStudioProps } from "./types";

packages/onboarding/src/onboarding-studio.module.css

@@ -358,6 +358,7 @@
   display: flex;
   width: max-content;
   min-width: 100%;
+  margin: 0;
   padding: 0.2rem;
   border-radius: var(--mantine-radius-md);
   background: var(--mantine-color-default);

packages/onboarding/src/service-url-template.tsx

@@ -0,0 +1,106 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { useRef, useState } from "react";
+import { FloatingIndicator, Stack, TextInput, UnstyledButton } from "@mantine/core";
+
+import type { UrlTemplateMode } from "@homarr/definitions";
+import { useScopedI18n } from "@homarr/translation/client";
+
+import { useOnboardingSounds } from "./use-onboarding-sounds";
+import classes from "./onboarding-studio.module.css";
+
+interface FloatingControlProps<T extends string> {
+  value: T;
+  onChange: (value: T) => void;
+  options: readonly { value: T; label: ReactNode }[];
+  ariaLabel: string;
+}
+
+export const OnboardingFloatingControl = <T extends string>({
+  value,
+  onChange,
+  options,
+  ariaLabel,
+}: FloatingControlProps<T>) => {
+  const [rootRef, setRootRef] = useState<HTMLFieldSetElement | null>(null);
+  const controlRefs = useRef<Record<string, HTMLButtonElement | null>>({});
+  const sounds = useOnboardingSounds();
+
+  return (
+    <div className={classes.floatingControlScroller}>
+      <fieldset ref={setRootRef} className={classes.floatingControlRoot} aria-label={ariaLabel}>
+        <FloatingIndicator
+          target={controlRefs.current[value] ?? null}
+          parent={rootRef}
+          className={classes.floatingControlIndicator}
+        />
+        {options.map((option) => {
+          const selected = value === option.value;
+          return (
+            <UnstyledButton
+              key={option.value}
+              ref={(node) => {
+                controlRefs.current[option.value] = node;
+              }}
+              type="button"
+              className={classes.floatingControl}
+              data-active={selected}
+              aria-pressed={selected}
+              onClick={() => {
+                sounds.click();
+                onChange(option.value);
+              }}
+            >
+              {option.label}
+            </UnstyledButton>
+          );
+        })}
+      </fieldset>
+    </div>
+  );
+};
+
+interface ServiceUrlTemplateProps {
+  serverOrigin: string;
+  onServerOriginChange: (value: string) => void;
+  mode: UrlTemplateMode;
+  onModeChange: (value: UrlTemplateMode) => void;
+  readOnly?: boolean;
+  required?: boolean;
+}
+
+export const ServiceUrlTemplate = ({
+  serverOrigin,
+  onServerOriginChange,
+  mode,
+  onModeChange,
+  readOnly,
+  required,
+}: ServiceUrlTemplateProps) => {
+  const t = useScopedI18n("init.studio.essentials");
+
+  return (
+    <Stack gap="sm">
+      <TextInput
+        label={t("serverTitle")}
+        placeholder="home.lan · 192.168.1.10 · https://homarr.example.com"
+        value={serverOrigin}
+        onChange={(event) => onServerOriginChange(event.currentTarget.value)}
+        readOnly={readOnly}
+        required={required}
+        withAsterisk={required}
+      />
+      <OnboardingFloatingControl
+        ariaLabel={t("urlModeLabel")}
+        value={mode}
+        onChange={onModeChange}
+        options={[
+          { value: "hostPort", label: t("hostPort") },
+          { value: "subdomain", label: t("subdomain") },
+          { value: "path", label: t("path") },
+        ]}
+      />
+    </Stack>
+  );
+};

packages/onboarding/src/setup-studio.tsx

@@ -15,7 +15,6 @@ import {
   ColorSwatch,
   CopyButton,
   Fieldset,
-  FloatingIndicator,
   Group,
   Paper,
   PasswordInput,
@@ -99,6 +98,7 @@ import type { OnboardingStudioProps } from "./types";
 import { getBoardValidationErrors } from "./board-validation";
 import { OnboardingBackdrop } from "./onboarding-backdrop";
 import { OnboardingWordmark } from "./onboarding-wordmark";
+import { OnboardingFloatingControl, ServiceUrlTemplate } from "./service-url-template";
 import { useOnboardingSounds } from "./use-onboarding-sounds";
 import {
   normalizeServiceUrl,
@@ -152,57 +152,6 @@ const initialSecondaryColor = "#fd7e14";
 const emptyDiscoveredIntegrations: DockerDiscoveryData["integrations"] = [];
 const emptyDiscoveredApps: DockerDiscoveryData["apps"] = [];
 
-interface OnboardingFloatingControlProps<T extends string> {
-  value: T;
-  onChange: (value: T) => void;
-  options: readonly { value: T; label: ReactNode }[];
-  ariaLabel: string;
-}
-
-const OnboardingFloatingControl = <T extends string>({
-  value,
-  onChange,
-  options,
-  ariaLabel,
-}: OnboardingFloatingControlProps<T>) => {
-  const [rootRef, setRootRef] = useState<HTMLDivElement | null>(null);
-  const controlRefs = useRef<Record<string, HTMLButtonElement | null>>({});
-  const sounds = useOnboardingSounds();
-
-  return (
-    <div className={classes.floatingControlScroller}>
-      <div ref={setRootRef} className={classes.floatingControlRoot} role="group" aria-label={ariaLabel}>
-        <FloatingIndicator
-          target={controlRefs.current[value] ?? null}
-          parent={rootRef}
-          className={classes.floatingControlIndicator}
-        />
-        {options.map((option) => {
-          const selected = value === option.value;
-          return (
-            <UnstyledButton
-              key={option.value}
-              ref={(node) => {
-                controlRefs.current[option.value] = node;
-              }}
-              type="button"
-              className={classes.floatingControl}
-              data-active={selected}
-              aria-pressed={selected}
-              onClick={() => {
-                sounds.click();
-                onChange(option.value);
-              }}
-            >
-              {option.label}
-            </UnstyledButton>
-          );
-        })}
-      </div>
-    </div>
-  );
-};
-
 export const SetupStudio = ({ environment, assistantConfiguration }: OnboardingStudioProps) => {
   const t = useScopedI18n("init.studio");
   const tCommon = useScopedI18n("common.action");
@@ -924,24 +873,13 @@ const Essentials = (props: StudioSectionProps) => {
         <Alert variant="light" icon={<IconInfoCircle size={18} />} my="xs">
           {t("serverOriginHelp")}
         </Alert>
-        <TextInput
-          label={t("serverTitle")}
-          placeholder="home.lan · 192.168.1.10 · https://homarr.example.com"
-          value={props.serverOrigin}
-          onChange={(event) => props.setServerOrigin(event.currentTarget.value)}
+        <ServiceUrlTemplate
+          serverOrigin={props.serverOrigin}
+          onServerOriginChange={props.setServerOrigin}
+          mode={props.urlMode}
+          onModeChange={props.setUrlMode}
           readOnly={!isHydrated}
           required
-          withAsterisk
-        />
-        <OnboardingFloatingControl
-          ariaLabel={t("urlModeLabel")}
-          value={props.urlMode}
-          onChange={props.setUrlMode}
-          options={[
-            { value: "hostPort", label: t("hostPort") },
-            { value: "subdomain", label: t("subdomain") },
-            { value: "path", label: t("path") },
-          ]}
         />
         {props.serverOrigin ? (
           <Code block>{buildIntegrationUrl("sonarr", props.serverOrigin, props.urlMode)}</Code>

packages/translation/src/lang/en.json

@@ -7079,23 +7079,17 @@
     "title": "Containers",
     "reconciliation": {
       "title": "Assisted Docker setup",
-      "description": "Optional suggestions to connect Docker services with Homarr apps and integrations.",
       "suggestions": "{count, plural, =0 {No suggestions} one {# suggestion} other {# suggestions}}",
       "attention": "{count} need attention",
       "endpointUnavailable": "Some services could not be checked because these endpoints are unavailable: {names}",
       "empty": "No visible Docker services were found.",
       "emptyFilter": "No services match this view.",
       "ambiguous": "More than one existing item could match this service. Homarr will not choose one automatically.",
-      "match": "{confidence} confidence match",
       "filter": {
         "attention": "Needs attention",
         "represented": "Already set up",
         "all": "All"
       },
-      "confidence": {
-        "high": "High",
-        "medium": "Medium"
-      },
       "state": {
         "newRecognized": "Ready to connect",
         "newApp": "New service",
@@ -7104,19 +7098,9 @@
         "moved": "Address changed"
       },
       "url": {
-        "label": "Service address",
-        "inputLabel": "Service URL",
-        "manual": "Enter an address manually",
-        "invalid": "Enter a valid HTTP or HTTPS URL"
-      },
-      "reason": {
-        "publishedAddress": "Published address reported by Docker",
-        "dockerEndpointHost": "Docker endpoint host combined with the published port",
-        "sharedContainerNetwork": "Server-only address for services sharing the container network",
-        "manualHostRequired": "Enter the address that your browser or Homarr server can reach"
+        "manual": "Enter an address manually"
       },
       "health": {
-        "title": "Observed service layers",
         "layer": {
           "docker": "Docker",
           "integrationConfiguration": "Integration",