From 9c45a806c8942df14c35b30e4e1323290cb24cdf Mon Sep 17 00:00:00 2001 From: Bobban Rydh Date: Tue, 15 Sep 2026 00:04:34 +0200 Subject: [PATCH] Add Dockhand integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Third live integration: container status across every Docker host Dockhand manages, with start/stop/restart actions — matching the "dashboard + basic actions" depth from the plan. Talks to Dockhand's own aggregating REST API (bearer tokens, dh_...) rather than the raw Docker Engine API on each host directly, so one credential covers every host Dockhand is already connected to. Adapter built against Dockhand's real published OpenAPI spec (fetched from https://github.com/strausmann/mcp-dockhand/blob/main/docs/dockhand-openapi.json, 257 documented paths) since the instance itself isn't reachable from here — same "verify against the real shape, don't guess" approach as Gitea, just via the spec instead of a live instance: - GET /api/environments — the Docker hosts Dockhand knows about - GET /api/containers?env=&all=true — containers per host ({id, name, image, state, status}) - POST /api/containers/{id}/{start,stop,restart}?env= server/src/integrations/dockhand/adapter.ts fans the environments call out to one containers call per host (Promise.all) and flattens the result, tagging each container with its environment; one unreachable host returns an empty list for that host rather than failing the whole dashboard view. Follows the same config-in-UI + encrypted-credential pattern as Tailscale and Gitea. Verified: full build passes. Since Dockhand isn't reachable from here, ran a 14-check HTTP test against the live server instead of the real API — role gating, credential non-leakage, disabled-integration blocking, and (critically) re-confirmed the wrong_type crash-safety pattern holds for this third adapter type: hitting the Dockhand routes on a differently-typed integration row returns a clean 400 rather than crashing the process, and the server keeps responding to /health afterward. Real container data and the start/stop/restart actions still need verification once this app runs on the user's LAN where Dockhand is reachable. Co-Authored-By: Claude Sonnet 5 --- server/src/integrations/dockhand/adapter.ts | 126 +++++++++++++++++ server/src/integrations/fieldSchemas.ts | 4 + server/src/integrations/registry.ts | 3 + server/src/routes/integrations.ts | 72 ++++++++++ web/src/api/client.ts | 34 +++++ web/src/pages/Dashboard.tsx | 28 +++- web/src/pages/Integrations.tsx | 141 ++++++++++++++++++++ 7 files changed, 407 insertions(+), 1 deletion(-) create mode 100644 server/src/integrations/dockhand/adapter.ts diff --git a/server/src/integrations/dockhand/adapter.ts b/server/src/integrations/dockhand/adapter.ts new file mode 100644 index 0000000..0ea3ebe --- /dev/null +++ b/server/src/integrations/dockhand/adapter.ts @@ -0,0 +1,126 @@ +/** + * Dockhand adapter — uses Dockhand's own aggregating REST API (not the raw + * Docker Engine API on each host directly). Requires config: url, token + * + * Dockhand is a multi-host Docker manager; "environments" are the individual + * Docker hosts/agents it's connected to, and containers are listed/controlled + * per environment. + * + * API reference verified against Dockhand's published OpenAPI spec + * (https://github.com/strausmann/mcp-dockhand/blob/main/docs/dockhand-openapi.json). + */ + +export interface DockhandConfig { + url: string; + token: string; +} + +export interface DockhandEnvironment { + id: number; + name: string; + connectionType: string; +} + +export interface DockhandContainer { + id: string; + name: string; + image: string; + state: string; // "running" | "exited" | "paused" | "restarting" | "created" | "dead" + status: string; // human string, e.g. "Up 2 hours (healthy)" + environmentId: number; + environmentName: string; +} + +export interface DockhandAdapter { + ping(): Promise<{ ok: boolean; latencyMs?: number; error?: string }>; + listContainers(): Promise; + startContainer(environmentId: number, containerId: string): Promise; + stopContainer(environmentId: number, containerId: string): Promise; + restartContainer(environmentId: number, containerId: string): Promise; +} + +export function createDockhandAdapter(config: DockhandConfig): DockhandAdapter { + function base() { + return config.url.replace(/\/$/, ""); + } + + function headers() { + return { + Authorization: `Bearer ${config.token}`, + Accept: "application/json", + "Content-Type": "application/json", + }; + } + + async function api(method: string, path: string): Promise { + const res = await fetch(`${base()}${path}`, { method, headers: headers() }); + const text = await res.text(); + let data: any = null; + try { + data = text ? JSON.parse(text) : null; + } catch { + // non-JSON error page + } + if (!res.ok) { + throw new Error(data?.message || data?.error || `Dockhand API error: HTTP ${res.status}`); + } + return data; + } + + async function listEnvironments(): Promise { + const data = await api("GET", "/api/environments"); + return (Array.isArray(data) ? data : []).map((e: any) => ({ + id: e.id, + name: e.name, + connectionType: e.connectionType, + })); + } + + async function listContainers(): Promise { + const environments = await listEnvironments(); + const perEnv = await Promise.all( + environments.map(async (env) => { + try { + const data = await api("GET", `/api/containers?env=${env.id}&all=true`); + return (Array.isArray(data) ? data : []).map((c: any) => ({ + id: c.id, + name: c.name, + image: c.image, + state: c.state, + status: c.status, + environmentId: env.id, + environmentName: env.name, + })); + } catch { + // one unreachable host shouldn't take down the whole dashboard view + return []; + } + }), + ); + return perEnv.flat(); + } + + async function startContainer(environmentId: number, containerId: string): Promise { + await api("POST", `/api/containers/${encodeURIComponent(containerId)}/start?env=${environmentId}`); + } + + async function stopContainer(environmentId: number, containerId: string): Promise { + await api("POST", `/api/containers/${encodeURIComponent(containerId)}/stop?env=${environmentId}`); + } + + async function restartContainer(environmentId: number, containerId: string): Promise { + await api("POST", `/api/containers/${encodeURIComponent(containerId)}/restart?env=${environmentId}`); + } + + async function ping(): Promise<{ ok: boolean; latencyMs?: number; error?: string }> { + const start = Date.now(); + try { + await api("GET", "/api/environments"); + return { ok: true, latencyMs: Date.now() - start }; + } catch (err) { + return { ok: false, error: err instanceof Error ? err.message : String(err) }; + } + } + + return { ping, listContainers, startContainer, stopContainer, restartContainer }; +} diff --git a/server/src/integrations/fieldSchemas.ts b/server/src/integrations/fieldSchemas.ts index d7754b0..dab9e74 100644 --- a/server/src/integrations/fieldSchemas.ts +++ b/server/src/integrations/fieldSchemas.ts @@ -19,6 +19,10 @@ export const INTEGRATION_FIELDS: Partial; @@ -20,6 +21,8 @@ export function createIntegrationAdapter(type: IntegrationType, config: Integrat return createTailscaleAdapter(config as any); case "gitea": return createGiteaAdapter(config as any); + case "dockhand": + return createDockhandAdapter(config as any); default: throw new Error(`Integration type "${type}" is not implemented yet`); } diff --git a/server/src/routes/integrations.ts b/server/src/routes/integrations.ts index f11e1db..f02e026 100644 --- a/server/src/routes/integrations.ts +++ b/server/src/routes/integrations.ts @@ -16,6 +16,7 @@ import { createIntegrationAdapter } from "../integrations/registry.js"; import { loadIntegrationConfig } from "../integrations/loadIntegration.js"; import { createTailscaleAdapter } from "../integrations/tailscale/adapter.js"; import { createGiteaAdapter } from "../integrations/gitea/adapter.js"; +import { createDockhandAdapter } from "../integrations/dockhand/adapter.js"; import { asyncHandler } from "../utils/asyncHandler.js"; export const integrationsRouter = Router(); @@ -397,3 +398,74 @@ integrationsRouter.post( } }), ); + +// ─── Dockhand ──────────────────────────────────────────────────────────────── + +async function requireDockhandAdapter(req: Request, res: Response) { + const id = Number(req.params.id); + const loaded = await loadIntegrationConfig(id); + if (!loaded) { + res.status(404).json({ error: "not_found" }); + return null; + } + if (loaded.integration.type !== "dockhand") { + res.status(400).json({ error: "wrong_type" }); + return null; + } + if (!loaded.integration.enabled) { + res.status(400).json({ error: "integration_disabled" }); + return null; + } + return { integration: loaded.integration, adapter: createDockhandAdapter(loaded.config as any) }; +} + +integrationsRouter.get("/:id/dockhand/containers", asyncHandler(async (req, res) => { + const found = await requireDockhandAdapter(req, res); + if (!found) return; + + try { + const containers = await found.adapter.listContainers(); + res.json({ + containers, + summary: { + total: containers.length, + running: containers.filter((c) => c.state === "running").length, + }, + }); + } catch (err) { + res.status(502).json({ error: err instanceof Error ? err.message : String(err) }); + } +})); + +const dockhandActions = ["start", "stop", "restart"] as const; + +for (const action of dockhandActions) { + integrationsRouter.post( + `/:id/dockhand/environments/:envId/containers/:containerId/${action}`, + requireRole("operator"), + asyncHandler(async (req, res) => { + const found = await requireDockhandAdapter(req, res); + if (!found) return; + + const envId = Number(req.params.envId); + if (!Number.isInteger(envId)) { + return res.status(400).json({ error: "invalid_environment_id" }); + } + + try { + await found.adapter[`${action}Container`](envId, req.params.containerId); + await recordAudit({ + actor: req.currentUser!, + category: "integration", + action: `${action}_container`, + targetType: "dockhand_container", + targetId: req.params.containerId, + detail: { integrationId: found.integration.id, environmentId: envId }, + }); + res.status(204).end(); + } catch (err) { + res.status(502).json({ error: err instanceof Error ? err.message : String(err) }); + } + }), + ); +} diff --git a/web/src/api/client.ts b/web/src/api/client.ts index 92f2553..f927122 100644 --- a/web/src/api/client.ts +++ b/web/src/api/client.ts @@ -222,6 +222,21 @@ export interface GiteaRepo { latestRun: GiteaWorkflowRun | null; } +export interface DockhandContainer { + id: string; + name: string; + image: string; + state: string; + status: string; + environmentId: number; + environmentName: string; +} + +export interface DockhandContainersResponse { + containers: DockhandContainer[]; + summary: { total: number; running: number }; +} + export class UnauthorizedError extends Error {} export class ForbiddenError extends Error {} @@ -400,5 +415,24 @@ export const api = { { method: "POST" }, ), }, + dockhand: { + containers: (integrationId: number) => + request(`/api/integrations/${integrationId}/dockhand/containers`), + start: (integrationId: number, envId: number, containerId: string) => + request( + `/api/integrations/${integrationId}/dockhand/environments/${envId}/containers/${encodeURIComponent(containerId)}/start`, + { method: "POST" }, + ), + stop: (integrationId: number, envId: number, containerId: string) => + request( + `/api/integrations/${integrationId}/dockhand/environments/${envId}/containers/${encodeURIComponent(containerId)}/stop`, + { method: "POST" }, + ), + restart: (integrationId: number, envId: number, containerId: string) => + request( + `/api/integrations/${integrationId}/dockhand/environments/${envId}/containers/${encodeURIComponent(containerId)}/restart`, + { method: "POST" }, + ), + }, }, }; diff --git a/web/src/pages/Dashboard.tsx b/web/src/pages/Dashboard.tsx index 7bf4166..795bc91 100644 --- a/web/src/pages/Dashboard.tsx +++ b/web/src/pages/Dashboard.tsx @@ -16,10 +16,16 @@ interface GiteaSummary { failing: number; } +interface DockhandSummary { + running: number; + total: number; +} + export default function Dashboard({ user }: { user: CurrentUser }) { const [integrations, setIntegrations] = useState(null); const [tailscaleSummary, setTailscaleSummary] = useState(null); const [giteaSummary, setGiteaSummary] = useState(null); + const [dockhandSummary, setDockhandSummary] = useState(null); useEffect(() => { api.integrations.list().then((res) => setIntegrations(res.integrations)); @@ -54,6 +60,18 @@ export default function Dashboard({ user }: { user: CurrentUser }) { .catch(() => setGiteaSummary(null)); }, [integrations]); + useEffect(() => { + const dockhand = integrations?.find((i) => i.type === "dockhand" && i.enabled); + if (!dockhand) { + setDockhandSummary(null); + return; + } + api.integrations.dockhand + .containers(dockhand.id) + .then((res) => setDockhandSummary({ running: res.summary.running, total: res.summary.total })) + .catch(() => setDockhandSummary(null)); + }, [integrations]); + return ( <>
@@ -71,7 +89,8 @@ export default function Dashboard({ user }: { user: CurrentUser }) { const integration = integrations?.find((i) => i.type === type && i.enabled); const isLiveTailscale = type === "tailscale" && integration && tailscaleSummary; const isLiveGitea = type === "gitea" && integration && giteaSummary; - const isLive = isLiveTailscale || isLiveGitea; + const isLiveDockhand = type === "dockhand" && integration && dockhandSummary; + const isLive = isLiveTailscale || isLiveGitea || isLiveDockhand; return (
@@ -107,6 +126,13 @@ export default function Dashboard({ user }: { user: CurrentUser }) {
{giteaSummary!.failing} with a failing build
)}
+ ) : isLiveDockhand ? ( +
+
+ {dockhandSummary!.running}/{dockhandSummary!.total} +
+
containers running
+
) : (
{integration ? ( diff --git a/web/src/pages/Integrations.tsx b/web/src/pages/Integrations.tsx index 1f203d3..dae8451 100644 --- a/web/src/pages/Integrations.tsx +++ b/web/src/pages/Integrations.tsx @@ -2,6 +2,8 @@ import { useEffect, useState } from "react"; import { api, type CurrentUser, + type DockhandContainer, + type DockhandContainersResponse, type GiteaRepo, type IntegrationSummary, type IntegrationType, @@ -10,6 +12,22 @@ import { } from "../api/client"; import IntegrationForm from "../components/IntegrationForm"; +function containerStateBadge(state: string) { + switch (state) { + case "running": + return Running; + case "exited": + case "dead": + return {state === "dead" ? "Dead" : "Exited"}; + case "paused": + return Paused; + case "restarting": + return Restarting; + default: + return {state}; + } +} + function runStatusBadge(repo: GiteaRepo) { const run = repo.latestRun; if (!run) return No runs; @@ -62,6 +80,11 @@ export default function Integrations({ user }: { user: CurrentUser }) { const [loadingRepos, setLoadingRepos] = useState(false); const [rerunningRun, setRerunningRun] = useState(null); + const [dockhandData, setDockhandData] = useState(null); + const [dockhandError, setDockhandError] = useState(null); + const [loadingContainers, setLoadingContainers] = useState(false); + const [actingOnContainer, setActingOnContainer] = useState(null); + function loadIntegrations() { api.integrations .list() @@ -96,6 +119,16 @@ export default function Integrations({ user }: { user: CurrentUser }) { .finally(() => setLoadingRepos(false)); } + function loadDockhandContainers(id: number) { + setLoadingContainers(true); + setDockhandError(null); + api.integrations.dockhand + .containers(id) + .then((res) => setDockhandData(res)) + .catch((err) => setDockhandError(err instanceof Error ? err.message : String(err))) + .finally(() => setLoadingContainers(false)); + } + useEffect(() => { if (selected?.type === "tailscale" && selected.enabled && !managing) { loadTailscaleDevices(selected.id); @@ -107,6 +140,11 @@ export default function Integrations({ user }: { user: CurrentUser }) { } else { setGiteaRepos(null); } + if (selected?.type === "dockhand" && selected.enabled && !managing) { + loadDockhandContainers(selected.id); + } else { + setDockhandData(null); + } // eslint-disable-next-line react-hooks/exhaustive-deps }, [selectedId, managing, integrations]); @@ -165,6 +203,21 @@ export default function Integrations({ user }: { user: CurrentUser }) { } } + async function containerAction(c: DockhandContainer, action: "start" | "stop" | "restart") { + if (!selectedId) return; + if (action === "stop" && !confirm(`Stop container "${c.name}"?`)) return; + setActingOnContainer(c.id); + setDockhandError(null); + try { + await api.integrations.dockhand[action](selectedId, c.environmentId, c.id); + loadDockhandContainers(selectedId); + } catch (err) { + setDockhandError(err instanceof Error ? err.message : String(err)); + } finally { + setActingOnContainer(null); + } + } + return ( <>
@@ -406,6 +459,94 @@ export default function Integrations({ user }: { user: CurrentUser }) {
+ ) : selected?.type === "dockhand" ? ( +
+
+

+ Containers + {dockhandData && ( + + {dockhandData.summary.running}/{dockhandData.summary.total} running + + )} +

+
+ +
+
+ {dockhandError &&
{dockhandError}
} +
+ + + + + + + + {canEdit && } + + + + {dockhandData?.containers.map((c) => ( + + + + + + {canEdit && ( + + )} + + ))} + {dockhandData?.containers.length === 0 && ( + + + + )} + +
ContainerHostImageStatusActions
{c.name}{c.environmentName}{c.image} + {containerStateBadge(c.state)} +
{c.status}
+ 		+
+ {c.state === "running" ? ( + <> + + + + ) : ( + + )} +
+
+ No containers found across any environment. +
+
+
) : (