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 <noreply@anthropic.com>
246 lines
16 KiB
TypeScript
246 lines
16 KiB
TypeScript
/**
|
|
* 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<string, string | null> = {
|
|
"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<void>((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<Server>((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";
|
|
});
|
|
});
|