From 12f2662465beb8e87dcb612e7d067ed34a815767 Mon Sep 17 00:00:00 2001 From: Bobban Rydh Date: Sat, 24 Oct 2026 21:23:13 +0200 Subject: [PATCH] Suggested checks for the apps in your containers With Dockhand connected, an image the app recognises (about 20 with a health endpoint of their own, plus a few dozen web UIs) is offered as an endpoint check on that app's own health address, with what a good answer looks like set up as a value check: Immich's ping says pong, Nextcloud's status.php is not in maintenance, Gitea's health says pass, and so on. Asked on the Docker host's address at the port the container publishes. Container ports are now read from Dockhand's list. Co-Authored-By: Claude Sonnet 5.5 --- INTEGRATIONS.md | 1 + README.md | 4 +- docs/MONITORING.md | 6 + server/src/integrations/dockhand/adapter.ts | 48 ++++ server/src/routes/endpoints.ts | 2 +- server/src/services/appCatalog.ts | 109 +++++++++ server/src/services/endpointSuggestions.ts | 83 +++++++ server/test/appCatalog.test.ts | 245 ++++++++++++++++++++ web/src/api/client.ts | 2 + web/src/components/EndpointSuggestions.tsx | 7 +- 10 files changed, 502 insertions(+), 5 deletions(-) create mode 100644 server/src/services/appCatalog.ts create mode 100644 server/test/appCatalog.test.ts diff --git a/INTEGRATIONS.md b/INTEGRATIONS.md index 0d8e795..472c886 100644 --- a/INTEGRATIONS.md +++ b/INTEGRATIONS.md @@ -56,6 +56,7 @@ the dashboard views themselves load fine. (UniFi, Nginx Proxy Manager, Home Assi - **Auth:** Bearer token against Dockhand's own API - **Actions used:** list environments/containers, check for image updates, start/stop/restart a container - **Required access:** A Dockhand API token belonging to a user with access to every environment (Docker host) you want visible, with permission to **start/stop/restart containers and trigger update checks** in each — not just view them. +- **Suggested checks:** each container's image and published ports are also used to suggest an endpoint check on the app's own health address ([MONITORING.md](docs/MONITORING.md#endpoint-checks-and-heartbeats)). Ports are read from whatever shape Dockhand's container list carries them in (Docker's own, `"0.0.0.0:8080->80/tcp"` strings or inspect's map) — **not checked against a live Dockhand**; if none is read, the Docker host's listening ports from its agent stand in. - **Container health:** on the 15-minute health pass the app also reads every container's state and status text and raises alerts for what is broken — see [Docker containers that are broken](docs/MONITORING.md#docker-containers-that-are-broken). A Docker host that Dockhand cannot read (its Hawser agent is down) is an alert too, and its containers' alerts are held, not cleared. The Docker page shows each container's problem and has a **Leave alone** button. diff --git a/README.md b/README.md index e7e6806..1ec34ae 100644 --- a/README.md +++ b/README.md @@ -590,7 +590,9 @@ dashboard and in `/metrics`. Results are kept for two weeks, then as hours (four **Suggested checks** (on the Endpoints page, administrators). From what the app already knows it offers checks you could add with a click: a **web port a server's agent sees open** (80, 443, 8080, 8443 — when a server has both the plain and the secure one, the secure one, since it also reads the certificate), under the name DNS gives that server if there is one (an A or AAAA record with one of its addresses, or an alias to it), otherwise its own hostname or address; and a **secret that already reads a -certificate**, since a check also hears when the service stops answering. Each is linked to its server. Something a check already covers is never offered, **Not for me** +certificate**, since a check also hears when the service stops answering; and, with Dockhand connected, **the apps in your containers**, recognised from their images and checked on each one's own health address with what a good +answer looks like — Immich's ping must say `pong`, Nextcloud's `status.php` must not be in maintenance mode, Gitea's health must say `pass`, Grafana's database must be `ok`, Authentik's health endpoint must answer, and so on for about forty +apps (the ones with no open health endpoint get a plain "the page answers"). They are asked on the Docker host's address (the server the app knows by that name) at the port the container publishes. Each is linked to its server. Something a check already covers is never offered, **Not for me** stops one being offered (and they can be brought back), and nothing is asked until you add it. Uptime Kuma's monitors are not offered: they are already being watched, and the adapter only keeps a host and port for them, not the address. diff --git a/docs/MONITORING.md b/docs/MONITORING.md index ccb0b23..b744d22 100644 --- a/docs/MONITORING.md +++ b/docs/MONITORING.md @@ -237,6 +237,12 @@ daily summaries for the charts and uptime figures. - **A header, for an API that wants a token.** A web check can send one header with its request (usually `Authorization: Bearer …`). The value is stored **encrypted** when `CREDENTIALS_ENCRYPTION_KEY` is set, is never sent back to the browser (the form says *Saved — leave blank to keep it*), and goes only to the address you gave — **not to another host a redirect leads to**. - What an administrator types in cannot be just anything: loopback, link-local and cloud-metadata addresses are refused, and the connection goes to the one address that passed the check. LAN and public hosts are fine. +- **Apps in your containers.** With Dockhand connected, an image the app recognises (Immich, Paperless-ngx, Nextcloud, Vaultwarden, Authentik, Gitea, Grafana, Prometheus, Jellyfin, n8n, ntfy, Gotify, Nginx Proxy Manager, Open WebUI, Ollama, SearXNG, Wiki.js, + BookStack, Homebox, Semaphore, Meilisearch, and a few dozen with just a web page) is offered as a check on **that app's own health address**, with what a good answer looks like set up as a [value check](#endpoint-checks-and-heartbeats): Immich's + `/api/server/ping` must say `res` = `pong`, Nextcloud's `/status.php` `maintenance` = `false`, Gitea's `/api/healthz` `status` = `pass`, Grafana's `/api/health` `database` = `ok`, Prometheus's `/-/healthy` must contain "Healthy". It is asked on the Docker + host's address — the server the app knows under the Docker environment's name in Dockhand, first usable IPv4 — at the **port the container publishes** (from Dockhand; if Dockhand does not say, the one the host's agent sees listening that the app is known to use). + Only running containers, only hosts the app knows, and only what no check covers already is offered; where an app is recognised the plain "something answers on 8080" suggestion for that port is replaced by it. The paths are those the projects publish for the purpose, **not tried against live + instances here**: a wrong one is a failing check you can edit. Uptime Kuma's monitors are not looked at, so something you already watch there may be offered — *Not for me* stops it. - The app suggests checks it can already work out (a web port a server's agent sees open, a secret with a host) under *Endpoints → Suggested*, and proxied hosts Nginx Proxy Manager serves. **Heartbeats** (Monitoring → Heartbeats) are the other direction: a cron job or script **calls an address when it finishes**, and the app alerts when it does *not*. A heartbeat has a **period** and a **grace**; it is diff --git a/server/src/integrations/dockhand/adapter.ts b/server/src/integrations/dockhand/adapter.ts index 62afbbe..98dacb1 100644 --- a/server/src/integrations/dockhand/adapter.ts +++ b/server/src/integrations/dockhand/adapter.ts @@ -23,6 +23,51 @@ export interface DockhandEnvironment { connectionType: string; } +/** A port a container publishes (or only listens on, when `publicPort` is null). */ +export interface DockhandPort { + privatePort: number | null; + publicPort: number | null; + protocol: string; +} + +/** + * The ports in whatever shape the container list carries them: Docker's own (`[{ IP, PrivatePort, PublicPort, Type }]`, camelCase or snake_case), strings like + * `"0.0.0.0:8080->80/tcp"`, or Docker inspect's map (`{ "80/tcp": [{ HostIp, HostPort }] }`). Anything else is no ports. Read defensively: the exact shape has not been + * checked against a live Dockhand. + */ +export function parsePorts(raw: unknown): DockhandPort[] { + const num = (v: unknown): number | null => { + const n = typeof v === "string" ? Number(v) : v; + return typeof n === "number" && Number.isInteger(n) && n > 0 && n <= 65535 ? n : null; + }; + const out: DockhandPort[] = []; + if (Array.isArray(raw)) { + for (const item of raw) { + if (typeof item === "string") { + const m = /^(?:(?:[\w.:[\]]+):)?(\d+)->(\d+)(?:\/(\w+))?$/.exec(item.trim()) ?? /^(\d+)\/(\w+)$/.exec(item.trim()); + if (!m) continue; + if (item.includes("->")) out.push({ publicPort: num(m[1]), privatePort: num(m[2]), protocol: m[3] ?? "tcp" }); + else out.push({ publicPort: null, privatePort: num(m[1]), protocol: m[2] }); + } else if (item && typeof item === "object") { + const o = item as Record; + out.push({ + privatePort: num(o.PrivatePort ?? o.privatePort ?? o.private_port ?? o.containerPort), + publicPort: num(o.PublicPort ?? o.publicPort ?? o.public_port ?? o.hostPort ?? o.HostPort), + protocol: String(o.Type ?? o.type ?? o.protocol ?? o.Protocol ?? "tcp").toLowerCase(), + }); + } + } + } else if (raw && typeof raw === "object") { + for (const [key, bindings] of Object.entries(raw as Record)) { + const m = /^(\d+)(?:\/(\w+))?$/.exec(key); + if (!m) continue; + const list = Array.isArray(bindings) && bindings.length > 0 ? bindings : [null]; + for (const b of list) out.push({ privatePort: num(m[1]), publicPort: num((b as Record | null)?.HostPort ?? (b as Record | null)?.hostPort), protocol: m[2] ?? "tcp" }); + } + } + return out.filter((p) => p.privatePort !== null || p.publicPort !== null); +} + export interface DockhandContainer { id: string; name: string; @@ -35,6 +80,8 @@ export interface DockhandContainer { updateAvailable: boolean | null; newerVersion: string | null; checkedAt: string | null; + /** The ports it publishes, as far as Dockhand says. */ + ports: DockhandPort[]; } /** Every container Dockhand could read, and the Docker hosts it could not (so a missing host is not mistaken for a host with nothing on it). */ @@ -119,6 +166,7 @@ export function createDockhandAdapter(config: DockhandConfig): DockhandAdapter { updateAvailable: record ? !!record.hasImageUpdate : null, newerVersion: record?.newerVersion ?? null, checkedAt: record?.checkedAt ?? null, + ports: parsePorts(c.ports ?? c.Ports ?? c.portMappings ?? c.NetworkSettings?.Ports), }; }); } catch (err) { diff --git a/server/src/routes/endpoints.ts b/server/src/routes/endpoints.ts index 68ea2d1..9f3775d 100644 --- a/server/src/routes/endpoints.ts +++ b/server/src/routes/endpoints.ts @@ -152,7 +152,7 @@ endpointsRouter.post("/suggestions/add", requireRole("admin"), asyncHandler(asyn if (have >= MAX_CHECKS) return res.status(409).json({ error: "too_many", message: `At most ${MAX_CHECKS} checks.`, added }); const [row] = await db .insert(endpointChecks) - .values(valuesOf({ name: s.name, kind: s.kind, target: s.target, port: s.port, serverId: s.serverId })) + .values(valuesOf({ name: s.name, kind: s.kind, target: s.target, port: s.port, serverId: s.serverId, expectStatus: s.expectStatus ?? null, keyword: s.keyword ?? null, valuePath: s.valuePath ?? null, valueOp: s.valueOp ?? null, valueExpected: s.valueExpected ?? null, insecure: s.insecure })) .returning(); have++; added.push({ id: row.id, name: row.name }); diff --git a/server/src/services/appCatalog.ts b/server/src/services/appCatalog.ts new file mode 100644 index 0000000..1e666d5 --- /dev/null +++ b/server/src/services/appCatalog.ts @@ -0,0 +1,109 @@ +/** + * What the apps people run in containers answer when they are well: the address of each one's own health check, and what a good answer looks like. From the container's + * image the app can say "this is Immich" and offer a check on `/api/server/ping` that wants `res` to be `pong`, instead of a bare "something answers on port 2283". + * + * The paths and answers are those the projects publish for the purpose (Immich's ping, Nextcloud's status.php, Authentik's health endpoints, Gitea's healthz, Grafana's health …), + * not guesses. They have not been tried against live instances here; one that is wrong shows as a failing check, which can be edited. Apps with no such endpoint get a plain + * "the web page answers" check on `/`. Nothing here asks anything: it only recognises images. + */ + +export interface CatalogApp { + id: string; + name: string; + /** Matched against the image's repository (registry and tag left off), lower-case. */ + match: RegExp; + /** The ports the app listens on inside the container, in order of preference. */ + ports: number[]; + /** Of those, the ones that speak TLS (self-signed, usually). */ + tlsPorts?: number[]; + path: string; + /** Good status codes, "200-399" when left out. */ + expectStatus?: string; + /** Text the answer must contain. */ + keyword?: string; + /** A value in a JSON answer, and what it should be. */ + value?: { path: string; op: "=" | "contains"; expected: string }; + /** One line on what the check wants, for the person adding it. */ + says: string; +} + +const web = (id: string, name: string, match: RegExp, ports: number[], path = "/"): CatalogApp => ({ id, name, match, ports, path, says: "the web page answers" }); + +export const APPS: CatalogApp[] = [ + { id: "immich", name: "Immich", match: /immich-app\/immich-server/, ports: [2283, 3001], path: "/api/server/ping", value: { path: "res", op: "=", expected: "pong" }, says: "its ping answers “pong”" }, + { id: "paperless", name: "Paperless-ngx", match: /paperless-ngx\/paperless-ngx|^paperlessngx\/paperless-ngx/, ports: [8000], path: "/accounts/login/", expectStatus: "200", says: "its login page answers" }, + { id: "nextcloud", name: "Nextcloud", match: /nextcloud-releases\/aio-apache|^(library\/)?nextcloud$|linuxserver\/nextcloud/, ports: [11000, 80, 443], tlsPorts: [443], path: "/status.php", value: { path: "maintenance", op: "=", expected: "false" }, says: "status.php answers, and it is not in maintenance mode" }, + { id: "vaultwarden", name: "Vaultwarden", match: /vaultwarden\/server/, ports: [80, 8080], path: "/alive", expectStatus: "200", says: "its /alive answers" }, + { id: "authentik", name: "Authentik", match: /goauthentik\/server/, ports: [9000, 9443], tlsPorts: [9443], path: "/-/health/live/", expectStatus: "200-299", says: "its health endpoint says it is alive" }, + { id: "gitea", name: "Gitea", match: /^(gitea\/)?gitea$/, ports: [3000, 80], path: "/api/healthz", value: { path: "status", op: "=", expected: "pass" }, says: "its health check says “pass”" }, + { id: "grafana", name: "Grafana", match: /grafana\/grafana/, ports: [3000], path: "/api/health", value: { path: "database", op: "=", expected: "ok" }, says: "its database is “ok”" }, + { id: "prometheus", name: "Prometheus", match: /prom\/prometheus|prometheus\/prometheus/, ports: [9090], path: "/-/healthy", keyword: "Healthy", says: "it says it is healthy" }, + { id: "jellyfin", name: "Jellyfin", match: /jellyfin\/jellyfin|linuxserver\/jellyfin/, ports: [8096, 8920], tlsPorts: [8920], path: "/health", keyword: "Healthy", says: "it says it is healthy" }, + { id: "n8n", name: "n8n", match: /n8nio\/n8n/, ports: [5678], path: "/healthz", value: { path: "status", op: "=", expected: "ok" }, says: "its health check says “ok”" }, + { id: "ntfy", name: "ntfy", match: /binwiederhier\/ntfy/, ports: [80], path: "/v1/health", value: { path: "healthy", op: "=", expected: "true" }, says: "it says it is healthy" }, + { id: "gotify", name: "Gotify", match: /gotify\/server/, ports: [80], path: "/health", value: { path: "health", op: "=", expected: "green" }, says: "its health is “green”" }, + { id: "npm", name: "Nginx Proxy Manager", match: /jc21\/nginx-proxy-manager/, ports: [81], path: "/api/", value: { path: "status", op: "=", expected: "OK" }, says: "its API says “OK”" }, + { id: "open-webui", name: "Open WebUI", match: /open-webui\/open-webui/, ports: [8080], path: "/health", value: { path: "status", op: "=", expected: "true" }, says: "its health check is true" }, + { id: "ollama", name: "Ollama", match: /ollama\/ollama/, ports: [11434], path: "/", keyword: "Ollama is running", says: "it says “Ollama is running”" }, + { id: "searxng", name: "SearXNG", match: /searxng\/searxng/, ports: [8080], path: "/healthz", expectStatus: "200", says: "its /healthz answers" }, + { id: "wikijs", name: "Wiki.js", match: /requarks\/wiki/, ports: [3000], path: "/healthz", expectStatus: "200", says: "its /healthz answers" }, + { id: "bookstack", name: "BookStack", match: /bookstack/, ports: [80, 6875], path: "/status", value: { path: "database", op: "=", expected: "true" }, says: "its database is reachable" }, + { id: "homebox", name: "Homebox", match: /homebox/, ports: [7745], path: "/api/v1/status", value: { path: "health", op: "=", expected: "true" }, says: "its status says it is healthy" }, + { id: "semaphore", name: "Semaphore", match: /semaphoreui\/semaphore/, ports: [3000], path: "/api/ping", keyword: "pong", says: "its ping answers “pong”" }, + { id: "meilisearch", name: "Meilisearch", match: /getmeili\/meilisearch/, ports: [7700], path: "/health", value: { path: "status", op: "=", expected: "available" }, says: "it says it is “available”" }, + // Apps with no health endpoint of their own that is open without signing in: the page answers. + web("technitium", "Technitium DNS", /technitium\/dns-server/, [5380]), + web("homepage", "Homepage", /gethomepage\/homepage/, [3000]), + web("homarr", "Homarr", /homarr/, [7575]), + web("firefly", "Firefly III", /fireflyiii\/core/, [8080]), + web("grocy", "Grocy", /grocy/, [80, 9283]), + web("freshrss", "FreshRSS", /freshrss\/freshrss/, [80]), + web("kanboard", "Kanboard", /kanboard\/kanboard/, [80]), + web("planka", "Planka", /plankanban\/planka/, [1337]), + web("snipeit", "Snipe-IT", /snipe\/snipe-it/, [80]), + web("wallos", "Wallos", /bellamy\/wallos/, [80]), + web("2fauth", "2FAuth", /2fauth\/2fauth/, [8000]), + web("duplicati", "Duplicati", /duplicati/, [8200]), + web("dockge", "Dockge", /louislam\/dockge/, [5001]), + web("karakeep", "Karakeep", /karakeep-app\/karakeep/, [3000]), + web("it-tools", "IT-Tools", /corentinth\/it-tools/, [80]), + web("drawio", "draw.io", /jgraph\/drawio/, [8080]), + web("phpipam", "phpIPAM", /phpipam\/phpipam-www/, [80]), + web("netbox", "NetBox", /netboxcommunity\/netbox/, [8080], "/login/"), + web("nexterm", "Nexterm", /nexterm\/aio/, [6989]), +]; + +/** The repository part of an image reference, lower-case: registry, tag and digest left off ("ghcr.io/immich-app/immich-server:v3@sha256:…" → "immich-app/immich-server"). */ +export function repoOf(image: string): string { + let r = image.trim().toLowerCase().replace(/@sha256:[0-9a-f]+$/, ""); + r = r.replace(/:[^/:]+$/, ""); + // The first part is a registry when it has a dot or a port, or is localhost. + const parts = r.split("/"); + if (parts.length > 1 && (/[.:]/.test(parts[0]) || parts[0] === "localhost")) parts.shift(); + return parts.join("/"); +} + +/** Pure: which app an image is, or null. An image that is only a digest ("sha256:…") says nothing. */ +export function appForImage(image: string): CatalogApp | null { + if (/^sha256:/i.test(image.trim())) return null; + const repo = repoOf(image); + return APPS.find((a) => a.match.test(repo)) ?? null; +} + +export interface PublishedPort { + privatePort: number | null; + publicPort: number | null; + protocol: string; +} + +/** Pure: the port to ask an app on — the published one for the port it listens on, or the only published one — with the port inside the container; null when it cannot be told. */ +export function portFor(app: CatalogApp, published: PublishedPort[]): { port: number; inner: number | null } | null { + const tcp = published.filter((p) => p.publicPort !== null && p.protocol.toLowerCase() !== "udp"); + for (const inner of app.ports) { + const hit = tcp.find((p) => p.privatePort === inner); + if (hit) return { port: hit.publicPort as number, inner }; + } + const distinct = [...new Set(tcp.map((p) => p.publicPort as number))]; + if (distinct.length !== 1) return null; + return { port: distinct[0], inner: tcp.find((p) => p.publicPort === distinct[0])?.privatePort ?? null }; +} diff --git a/server/src/services/endpointSuggestions.ts b/server/src/services/endpointSuggestions.ts index 8c1ea5e..52db613 100644 --- a/server/src/services/endpointSuggestions.ts +++ b/server/src/services/endpointSuggestions.ts @@ -7,6 +7,8 @@ * server it forwards to. * - A secret that already has a host to read the certificate from, as a certificate check: the secret only warns about the expiry, this also hears * when the service stops answering. + * - An app running in a container Dockhand reports (Immich, Paperless, Nextcloud, Gitea, Grafana, Authentik …), recognised from its image, as a check on that app's own + * health address with what a good answer looks like (services/appCatalog.ts) — on the Docker host's address, at the port the container publishes. * * It only reads what is stored (no network), leaves out what a check already covers, and remembers what somebody said no to. Uptime Kuma's monitors are * not offered: they are already being watched, and the adapter only keeps a host and port for them, not the address. @@ -16,6 +18,11 @@ import { dnsRecordsCache, endpointChecks, secrets, servers } from "../db/schema. import { isLoopback } from "./agentPorts.js"; import { npmIntegrationIds, readNpm } from "./npmReader.js"; import { matchServerForTarget } from "./uptimeKumaMatch.js"; +import { appForImage, portFor, type PublishedPort } from "./appCatalog.js"; +import { loadIntegrationConfig } from "../integrations/loadIntegration.js"; +import { createDockhandAdapter } from "../integrations/dockhand/adapter.js"; +import { integrations } from "../db/schema.js"; +import { and, eq } from "drizzle-orm"; import { getInternalFlag, setInternalFlag } from "./settingsStore.js"; export interface Suggestion { @@ -29,6 +36,14 @@ export interface Suggestion { serverName: string | null; /** Why it is offered, in a sentence. */ reason: string; + /** For an app recognised from its container: what the check wants, and the settings that make it so. */ + checks?: string; + expectStatus?: string | null; + keyword?: string | null; + valuePath?: string | null; + valueOp?: "=" | "contains" | null; + valueExpected?: string | null; + insecure?: boolean; } export interface SuggestionInput { @@ -39,6 +54,8 @@ export interface SuggestionInput { dismissed: Set; /** Hosts an Nginx Proxy Manager serves, with the server they forward to when the app knows it. */ proxied?: { domain: string; secure: boolean; serverId: number | null; serverName: string | null; integrationName: string }[]; + /** Containers Dockhand reports, with the Docker host each runs on (its name there). */ + containers?: { environmentName: string; name: string; image: string; state: string; ports: PublishedPort[] }[]; } /** The web ports worth offering, and what they speak. */ @@ -75,6 +92,46 @@ function coverage(existing: SuggestionInput["existing"]): Set { export function suggestChecks(input: SuggestionInput): { suggestions: Suggestion[]; dismissed: Suggestion[] } { const covered = coverage(input.existing); const all = new Map(); + /** The ports an app has been offered on, by server, so the plain "something answers on 8080" suggestion is not offered as well. */ + const appPorts = new Set(); + + // Apps recognised from their containers: asked on the Docker host's address, at the port the container publishes, on the app's own health address. + const matchable = input.servers.map((s) => ({ id: s.id, name: s.name, hostname: s.hostname, ips: s.ips })); + for (const c of input.containers ?? []) { + if (c.state !== "running") continue; + const app = appForImage(c.image); + if (!app) continue; + const server = matchServerForTarget(c.environmentName, matchable); + if (!server) continue; + const listening = new Set(input.servers.find((s) => s.id === server.id)?.ports.filter((p) => (p.protocol ?? "tcp") === "tcp").map((p) => p.port)); + // When Dockhand says nothing about ports, the host's own listening ports (from its agent) stand in: the one the app is known to use. + const chosen = c.ports.length > 0 ? portFor(app, c.ports) : (() => { const p = app.ports.find((x) => listening.has(x)); return p === undefined ? null : { port: p, inner: p }; })(); + const ip = server.ips.map((i) => i.trim()).find(usableIPv4); + if (!chosen || !ip) continue; + const tls = chosen.inner !== null ? (app.tlsPorts ?? []).includes(chosen.inner) : (app.tlsPorts ?? []).includes(chosen.port); + const scheme = tls ? "https" : "http"; + if (covered.has(`web:${ip}:${chosen.port}`)) continue; + const key = `app|${app.id}|${ip}|${chosen.port}`; + if (all.has(key)) continue; + appPorts.add(`${server.id}:${chosen.port}`); + all.set(key, { + key, + kind: "http", + name: `${app.name} on ${server.name}`, + target: `${scheme}://${ip}:${chosen.port}${app.path}`, + port: null, + serverId: server.id, + serverName: server.name, + reason: `${c.name} runs ${app.name} on ${server.name}.`, + checks: app.says, + expectStatus: app.expectStatus ?? null, + keyword: app.keyword ?? null, + valuePath: app.value?.path ?? null, + valueOp: app.value?.op ?? null, + valueExpected: app.value?.expected ?? null, + insecure: tls, + }); + } for (const s of input.servers) { const ips = new Set(s.ips.map((i) => i.trim().toLowerCase())); @@ -96,6 +153,8 @@ export function suggestChecks(input: SuggestionInput): { suggestions: Suggestion for (const port of Object.keys(WEB_PORTS).map(Number).filter((p) => listening.has(p))) { // Plain and secure on the same server: the secure one is the real service (the plain one is most likely its redirect), and reads the certificate. if (SECURE_TWIN[port] !== undefined && listening.has(SECURE_TWIN[port])) continue; + // An app that is known to be there already has a better check offered. + if (appPorts.has(`${s.id}:${port}`)) continue; const scheme = WEB_PORTS[port]; const fallback = hostname && hostname.includes(".") ? [hostname] : [s.ips.map((i) => i.trim()).find(usableIPv4)].filter((x): x is string => !!x); const hosts = dnsNames.length > 0 ? dnsNames.slice(0, MAX_NAMES_PER_PORT) : fallback; @@ -193,6 +252,29 @@ function jsonArray(stored: string | null): T[] { } } +/** The containers of every enabled Dockhand, kept a minute so opening the page twice does not ask every Docker host twice. A Dockhand that cannot be read adds nothing. */ +let containerCache: { at: number; rows: NonNullable } | null = null; +async function dockerContainers(): Promise> { + if (containerCache && Date.now() - containerCache.at < 60_000) return containerCache.rows; + const rows: NonNullable = []; + for (const row of await db.select({ id: integrations.id }).from(integrations).where(and(eq(integrations.type, "dockhand"), eq(integrations.enabled, true)))) { + try { + const loaded = await loadIntegrationConfig(row.id); + if (!loaded) continue; + for (const c of await createDockhandAdapter(loaded.config as never).listContainers()) rows.push({ environmentName: c.environmentName, name: c.name, image: c.image, state: c.state, ports: c.ports ?? [] }); + } catch { + // nothing from this one + } + } + containerCache = { at: Date.now(), rows }; + return rows; +} + +/** For tests: forget what was read. */ +export function resetContainerCacheForTests(): void { + containerCache = null; +} + export async function loadSuggestions(): Promise<{ suggestions: Suggestion[]; dismissed: Suggestion[] }> { const [serverRows, dnsRows, secretRows, existing, dismissed] = await Promise.all([ db.select({ id: servers.id, name: servers.name, hostname: servers.hostname, ipAddresses: servers.ipAddresses, listeningPorts: servers.listeningPorts }).from(servers), @@ -213,6 +295,7 @@ export async function loadSuggestions(): Promise<{ suggestions: Suggestion[]; di } } return suggestChecks({ + containers: await dockerContainers(), proxied, servers: serverRows.map((s) => ({ id: s.id, name: s.name, hostname: s.hostname, ips: jsonArray(s.ipAddresses).filter((i) => typeof i === "string"), ports: jsonArray<{ protocol?: string; port: number; address?: string }>(s.listeningPorts).filter((p) => p && Number.isInteger(p.port)) })), dns: dnsRows, diff --git a/server/test/appCatalog.test.ts b/server/test/appCatalog.test.ts new file mode 100644 index 0000000..c15f20f --- /dev/null +++ b/server/test/appCatalog.test.ts @@ -0,0 +1,245 @@ +/** + * Suggested checks from the apps running in containers: which app an image is, which port to ask it on, what the check wants, and how that turns into suggestions and checks that + * are added with the right settings. + * + * Run with: npm test --workspace server + */ +import { test, describe, before, after } from "node:test"; +import assert from "node:assert/strict"; +import { createServer as createHttpServer, type Server } from "node:http"; +import { mkdtempSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import type { AddressInfo } from "node:net"; + +const dir = mkdtempSync(join(tmpdir(), "hm-appcatalog-")); +process.env.DATABASE_PATH = join(dir, "test.sqlite"); +process.env.SESSION_DIR = join(dir, "sessions"); +process.env.CREDENTIALS_ENCRYPTION_KEY = "ab".repeat(32); +process.env.HEALTH_STARTUP_GRACE_MS = "0"; + +const express = (await import("express")).default; +const { db } = await import("../src/db/client.js"); +const { users, servers, integrations, endpointChecks } = await import("../src/db/schema.js"); +const { runMigrations } = await import("../src/db/migrate.js"); +const cat = await import("../src/services/appCatalog.js"); +const { parsePorts } = await import("../src/integrations/dockhand/adapter.js"); +const sug = await import("../src/services/endpointSuggestions.js"); +const { endpointsRouter } = await import("../src/routes/endpoints.js"); +const { isValuePath, valueProblem } = await import("../src/services/valueCheck.js"); +const { eq } = await import("drizzle-orm"); + +await runMigrations(); + +describe("which app an image is", () => { + test("the repository of an image, with registry, tag and digest left off", () => { + assert.equal(cat.repoOf("ghcr.io/immich-app/immich-server:v3"), "immich-app/immich-server"); + assert.equal(cat.repoOf("docker.n8n.io/n8nio/n8n"), "n8nio/n8n"); + assert.equal(cat.repoOf("docker.gitea.com/gitea:latest"), "gitea"); + assert.equal(cat.repoOf("docker.io/valkey/valkey:9@sha256:4963247afc4cd33c7d3b2d2816b9f7f8eeebab148d29056c2ca4d7cbc966f2d9"), "valkey/valkey"); + assert.equal(cat.repoOf("localhost:5000/team/app:1"), "team/app"); + assert.equal(cat.repoOf("adminer:latest"), "adminer"); + assert.equal(cat.repoOf("louislam/dockge:latest"), "louislam/dockge", "a Docker Hub user is not a registry"); + }); + + test("the apps in a real set of containers, and what is left alone", () => { + const expected: Record = { + "ghcr.io/immich-app/immich-server:v3": "immich", + "ghcr.io/immich-app/immich-machine-learning:v3": null, + "ghcr.io/paperless-ngx/paperless-ngx:latest": "paperless", + "ghcr.io/nextcloud-releases/aio-apache:latest": "nextcloud", + "ghcr.io/nextcloud-releases/aio-nextcloud:latest": null, + "ghcr.io/nextcloud-releases/all-in-one:latest": null, + "docker.gitea.com/gitea:latest": "gitea", + "ghcr.io/goauthentik/server:2026.8.3": "authentik", + "docker.n8n.io/n8nio/n8n": "n8n", + "grafana/grafana:latest": "grafana", + "prom/prometheus": "prometheus", + "quay.io/prometheus/node-exporter:latest": null, + "vaultwarden/server:latest": "vaultwarden", + "ghcr.io/bitwarden/web:2026.9.0": null, + "lscr.io/linuxserver/bookstack:latest": "bookstack", + "ghcr.io/sysadminsmedia/homebox:latest": "homebox", + "binwiederhier/ntfy": "ntfy", + "gotify/server:latest": "gotify", + "jc21/nginx-proxy-manager:latest": "npm", + "jc21/mariadb-aria:latest": null, + "ollama/ollama:latest": "ollama", + "ghcr.io/open-webui/open-webui:main": "open-webui", + "semaphoreui/semaphore:v2.20.16-beta1": "semaphore", + "getmeili/meilisearch:v1.41.0": "meilisearch", + "docker.io/technitium/dns-server:latest": "technitium", + "ghcr.io/requarks/wiki:latest": "wikijs", + "lscr.io/linuxserver/duplicati:latest": "duplicati", + "docker.io/netboxcommunity/netbox:latest": "netbox", + "gitea.labsconnect.se/bobban/homelab-manager-homelab-manager:latest": null, + "sha256:117302266443aed6e3ea5da9ef815f96fbafe44be8fd992887636f46bbaa074f": null, + "postgres:16-alpine": null, + "alpine": null, + }; + for (const [image, id] of Object.entries(expected)) assert.equal(cat.appForImage(image)?.id ?? null, id, image); + }); + + test("every catalog entry has a path, a port and, where it checks a value, a path the value check can read", () => { + assert.ok(cat.APPS.length > 30); + assert.equal(new Set(cat.APPS.map((a) => a.id)).size, cat.APPS.length, "ids are unique"); + for (const a of cat.APPS) { + assert.ok(a.path.startsWith("/") && a.ports.length > 0 && a.says, a.id); + if (a.value) assert.equal(valueProblem(a.value.path, a.value.op, a.value.expected), null, `${a.id}: the value check is one the checks accept`); + if (a.value) assert.ok(isValuePath(a.value.path), a.id); + if (a.expectStatus) assert.match(a.expectStatus, /^\d{3}(-\d{3})?(, ?\d{3}(-\d{3})?)*$/, a.id); + } + }); +}); + +describe("the ports of a container", () => { + test("Docker's own list, strings, and inspect's map", () => { + assert.deepEqual(parsePorts([{ IP: "0.0.0.0", PrivatePort: 80, PublicPort: 8080, Type: "tcp" }, { PrivatePort: 53, Type: "udp" }]), [ + { privatePort: 80, publicPort: 8080, protocol: "tcp" }, + { privatePort: 53, publicPort: null, protocol: "udp" }, + ]); + assert.deepEqual(parsePorts([{ privatePort: 3000, publicPort: 3001, type: "tcp" }]), [{ privatePort: 3000, publicPort: 3001, protocol: "tcp" }]); + assert.deepEqual(parsePorts(["0.0.0.0:8080->80/tcp", "[::]:8443->443/tcp", "9000/tcp"]), [ + { publicPort: 8080, privatePort: 80, protocol: "tcp" }, + { publicPort: 8443, privatePort: 443, protocol: "tcp" }, + { publicPort: null, privatePort: 9000, protocol: "tcp" }, + ]); + assert.deepEqual(parsePorts({ "80/tcp": [{ HostIp: "0.0.0.0", HostPort: "8081" }], "443/tcp": null }), [ + { privatePort: 80, publicPort: 8081, protocol: "tcp" }, + { privatePort: 443, publicPort: null, protocol: "tcp" }, + ]); + for (const nothing of [undefined, null, "", 5, [], {}, [{ nonsense: true }], ["not a port"]]) assert.deepEqual(parsePorts(nothing), []); + }); + + test("the port to ask: the published one for what the app listens on, or the only one published", () => { + const immich = cat.APPS.find((a) => a.id === "immich")!; + assert.deepEqual(cat.portFor(immich, [{ privatePort: 2283, publicPort: 12283, protocol: "tcp" }, { privatePort: 22, publicPort: 2222, protocol: "tcp" }]), { port: 12283, inner: 2283 }); + assert.deepEqual(cat.portFor(immich, [{ privatePort: 8000, publicPort: 8123, protocol: "tcp" }]), { port: 8123, inner: 8000 }, "remapped inside: the only one published"); + assert.equal(cat.portFor(immich, [{ privatePort: 1, publicPort: 11, protocol: "tcp" }, { privatePort: 2, publicPort: 22, protocol: "tcp" }]), null, "two, and neither is the app's"); + assert.equal(cat.portFor(immich, [{ privatePort: 53, publicPort: 53, protocol: "udp" }]), null, "udp is not web"); + assert.equal(cat.portFor(immich, [{ privatePort: 2283, publicPort: null, protocol: "tcp" }]), null, "not published"); + }); +}); + +describe("what is suggested", () => { + const S = (id: number, name: string, ips: string[], ports: number[] = []) => ({ id, name, hostname: null, ips, ports: ports.map((port) => ({ port, protocol: "tcp" })) }); + const base = (): import("../src/services/endpointSuggestions.js").SuggestionInput => ({ servers: [S(1, "Jazz", ["10.0.0.7"]), S(2, "Jackie", ["10.0.0.5"]), S(3, "Nova", ["10.0.0.9"], [8000])], dns: [], secrets: [], existing: [], dismissed: new Set() }); + const container = (environmentName: string, name: string, image: string, ports: { privatePort: number; publicPort: number | null; protocol?: string }[] = [], state = "running") => ({ environmentName, name, image, state, ports: ports.map((p) => ({ protocol: "tcp", ...p })) }); + + test("an app on a known Docker host is checked on its own health address, with what a good answer looks like", () => { + const { suggestions } = sug.suggestChecks({ ...base(), containers: [container("Jazz", "immich_server", "ghcr.io/immich-app/immich-server:v3", [{ privatePort: 2283, publicPort: 2283 }])] }); + assert.equal(suggestions.length, 1); + const s = suggestions[0]; + assert.deepEqual([s.key, s.name, s.target, s.serverName, s.kind], ["app|immich|10.0.0.7|2283", "Immich on Jazz", "http://10.0.0.7:2283/api/server/ping", "Jazz", "http"]); + assert.deepEqual([s.valuePath, s.valueOp, s.valueExpected, s.checks], ["res", "=", "pong", "its ping answers “pong”"]); + assert.match(s.reason, /immich_server runs Immich on Jazz/); + }); + + test("the port is the one published; with no ports said, the one the host's agent sees listening; with neither, nothing", () => { + const remapped = sug.suggestChecks({ ...base(), containers: [container("Jackie", "gitea", "docker.gitea.com/gitea:latest", [{ privatePort: 3000, publicPort: 3030 }, { privatePort: 22, publicPort: 222 }])] }); + assert.equal(remapped.suggestions[0].target, "http://10.0.0.5:3030/api/healthz"); + const viaAgent = sug.suggestChecks({ ...base(), containers: [container("Nova", "paperless-ngx-webserver-1", "ghcr.io/paperless-ngx/paperless-ngx:latest")] }); + assert.deepEqual([viaAgent.suggestions[0]?.target, viaAgent.suggestions[0]?.expectStatus], ["http://10.0.0.9:8000/accounts/login/", "200"]); + const neither = sug.suggestChecks({ ...base(), containers: [container("Jazz", "immich_server", "ghcr.io/immich-app/immich-server:v3")] }); + assert.deepEqual(neither.suggestions, []); + }); + + test("a TLS-only port is asked over https and accepts a certificate that is not trusted", () => { + const s = sug.suggestChecks({ ...base(), containers: [container("Jazz", "authentik-server-1", "ghcr.io/goauthentik/server:2026.8.3", [{ privatePort: 9443, publicPort: 9443 }])] }).suggestions[0]; + assert.deepEqual([s.target, s.insecure, s.expectStatus], ["https://10.0.0.7:9443/-/health/live/", true, "200-299"]); + }); + + test("what is not offered: stopped containers, unknown images, hosts the app does not know, what a check already covers, and one app twice", () => { + const containers = [ + container("Jazz", "stopped-immich", "ghcr.io/immich-app/immich-server:v3", [{ privatePort: 2283, publicPort: 2283 }], "exited"), + container("Jazz", "mystery", "ghcr.io/someone/thing:1", [{ privatePort: 80, publicPort: 80 }]), + container("Elsewhere", "immich_server", "ghcr.io/immich-app/immich-server:v3", [{ privatePort: 2283, publicPort: 2283 }]), + container("Jackie", "gitea", "docker.gitea.com/gitea:latest", [{ privatePort: 3000, publicPort: 3000 }]), + container("Jazz", "grafana-grafana-1", "grafana/grafana:latest", [{ privatePort: 3000, publicPort: 3000 }]), + container("Jazz", "grafana-again", "grafana/grafana:latest", [{ privatePort: 3000, publicPort: 3000 }]), + ]; + const input = { ...base(), containers, existing: [{ kind: "http", target: "http://10.0.0.5:3000/", port: null }] }; + assert.deepEqual(sug.suggestChecks(input).suggestions.map((s) => s.key), ["app|grafana|10.0.0.7|3000"], "gitea is covered, grafana is offered once"); + const dismissed = sug.suggestChecks({ ...input, dismissed: new Set(["app|grafana|10.0.0.7|3000"]) }); + assert.deepEqual([dismissed.suggestions.length, dismissed.dismissed.length], [0, 1]); + }); + + test("a web port the agent sees is not offered again as a bare port when an app is known to be there", () => { + const withPort = { ...base(), servers: [S(1, "Jazz", ["10.0.0.7"], [8080])], dns: [{ name: "search.lab.example", type: "A", content: "10.0.0.7" }] }; + const plain = sug.suggestChecks(withPort).suggestions; + assert.deepEqual(plain.map((s) => s.target), ["http://search.lab.example:8080/"]); + const both = sug.suggestChecks({ ...withPort, containers: [container("Jazz", "searxng", "docker.io/searxng/searxng:latest", [{ privatePort: 8080, publicPort: 8080 }])] }).suggestions; + assert.deepEqual(both.map((s) => s.key), ["app|searxng|10.0.0.7|8080"], "the app's check replaces it"); + }); +}); + +describe("added through the route", () => { + let dockhand: Server; + let app: Server; + let base = ""; + let who = "admin"; + + before(async () => { + await db.insert(users).values([ + { oidcSub: "admin", name: "Ada", role: "admin" }, + { oidcSub: "viewer", name: "Vic", role: "viewer" }, + ]); + await db.insert(servers).values({ name: "Jazz", apiTokenHash: "j", apiTokenPrefix: "j", ipAddresses: JSON.stringify(["10.0.0.7"]) }); + dockhand = createHttpServer((req, res) => { + const url = new URL(req.url ?? "", "http://x"); + res.setHeader("content-type", "application/json"); + if (url.pathname === "/api/environments") return void res.end(JSON.stringify([{ id: 1, name: "Jazz", connectionType: "hawser" }])); + if (url.pathname === "/api/containers/pending-updates") return void res.end(JSON.stringify({ pendingUpdates: [] })); + if (url.pathname === "/api/containers") + return void res.end(JSON.stringify([{ id: "a", name: "immich_server", image: "ghcr.io/immich-app/immich-server:v3", state: "running", status: "Up 2 days", ports: [{ IP: "0.0.0.0", PrivatePort: 2283, PublicPort: 2283, Type: "tcp" }] }])); + res.statusCode = 404; + res.end("{}"); + }); + await new Promise((r) => dockhand.listen(0, "127.0.0.1", r)); + await db.insert(integrations).values({ type: "dockhand", name: "Dockhand", baseUrl: "", config: JSON.stringify({ url: `http://127.0.0.1:${(dockhand.address() as AddressInfo).port}`, token: "t" }) }); + const a = express(); + a.use(express.json()); + a.use((req, _res, next) => { + (req as unknown as { session: unknown }).session = { user: { sub: who } }; + next(); + }); + a.use("/api/endpoints", endpointsRouter); + app = await new Promise((resolve) => { + const s = a.listen(0, "127.0.0.1", () => resolve(s)); + }); + base = `http://127.0.0.1:${(app.address() as AddressInfo).port}/api/endpoints`; + }); + after(() => { + dockhand.close(); + app.close(); + try { + rmSync(dir, { recursive: true, force: true }); + } catch { + // Windows keeps the database file locked until the process exits. + } + }); + + const call = (method: string, path: string, body?: unknown) => fetch(`${base}${path}`, { method, headers: { "content-type": "application/json", connection: "close" }, body: body === undefined ? undefined : JSON.stringify(body) }); + + test("the app is offered, adding it makes a check that asks the right thing, and then it is no longer offered", async () => { + sug.resetContainerCacheForTests(); + const list = (await (await call("GET", "/suggestions")).json()) as { suggestions: { key: string; name: string; target: string; checks?: string }[] }; + const s = list.suggestions.find((x) => x.key.startsWith("app|immich"))!; + assert.deepEqual([s.name, s.target, s.checks], ["Immich on Jazz", "http://10.0.0.7:2283/api/server/ping", "its ping answers “pong”"]); + + const added = await call("POST", "/suggestions/add", { keys: [s.key] }); + assert.equal(added.status, 201); + const [check] = await db.select().from(endpointChecks).where(eq(endpointChecks.name, "Immich on Jazz")); + assert.deepEqual([check.kind, check.target, check.valuePath, check.valueOp, check.valueExpected, check.serverId !== null], ["http", "http://10.0.0.7:2283/api/server/ping", "res", "=", "pong", true]); + sug.resetContainerCacheForTests(); + const again = (await (await call("GET", "/suggestions")).json()) as { suggestions: { key: string }[] }; + assert.ok(!again.suggestions.some((x) => x.key.startsWith("app|immich")), "covered now"); + }); + + test("only an administrator is offered them", async () => { + who = "viewer"; + assert.equal((await call("GET", "/suggestions")).status, 403); + assert.equal((await call("POST", "/suggestions/add", { keys: ["app|immich|10.0.0.7|2283"] })).status, 403); + who = "admin"; + }); +}); diff --git a/web/src/api/client.ts b/web/src/api/client.ts index 95e9031..2b0c37c 100644 --- a/web/src/api/client.ts +++ b/web/src/api/client.ts @@ -1204,6 +1204,8 @@ export interface EndpointSuggestion { serverId: number | null; serverName: string | null; reason: string; + /** For an app recognised from its container: what the check wants. */ + checks?: string; } export type HeartbeatState = "off" | "waiting" | "up" | "running" | "late" | "failed"; diff --git a/web/src/components/EndpointSuggestions.tsx b/web/src/components/EndpointSuggestions.tsx index d2bca11..cfecb43 100644 --- a/web/src/components/EndpointSuggestions.tsx +++ b/web/src/components/EndpointSuggestions.tsx @@ -5,8 +5,8 @@ import { readableError } from "../utils/errors"; import { toast } from "../utils/toast"; /** - * Checks the app could set up for you, from what it already knows: a web port a server is listening on (with the name DNS gives it) and a certificate a secret already - * reads. One click adds one, a button adds them all; "Not for me" stops one being offered, and they can be brought back. Administrators only, like the checks. + * Checks the app could set up for you, from what it already knows: a web port a server is listening on (with the name DNS gives it), an app recognised from its container + * (on its own health address), and a certificate a secret already reads. One click adds one, a button adds them all; "Not for me" stops one being offered, and they can be brought back. Administrators only, like the checks. */ export default function EndpointSuggestions({ onAdded }: { onAdded: () => void }) { const [offered, setOffered] = useState(null); @@ -90,7 +90,7 @@ export default function EndpointSuggestions({ onAdded }: { onAdded: () => void } {open && offered.length > 0 && ( <>
- From what the app already knows: web ports your servers are listening on (with the names DNS gives them) and certificates your secrets read. Nothing is asked until you add it. + From what the app already knows: web ports your servers are listening on (with the names DNS gives them), apps it recognises in your Docker containers (each on its own health address) and certificates your secrets read. Nothing is asked until you add it.
{offered.map((s) => ( @@ -104,6 +104,7 @@ export default function EndpointSuggestions({ onAdded }: { onAdded: () => void } {s.target} {s.port !== null ? `:${s.port}` : ""}
+ {s.checks &&
Checks that {s.checks}.
}
{s.reason} {s.serverId !== null && s.serverName && (