n8n: its own image built from source, placed data, and what its workflows use

The module named /var/lib/n8n, /services/n8n/n8n-data and n8n.novox.be -
paths and a domain no definition may carry (ADR 0112). State and data are
placed directories; the public name is ${bound:route:name} (depends on
mesh-controller #149), for N8N_HOST and WEBHOOK_URL alike.

The endpoint said 5682 while the container publishes 5678. 5682 was one
machine's host port; the endpoint is the software's port and the mesh
assigns the machine's (ADR 0038).

n8n had been run from an image in a registry that no longer exists: the
upstream image plus shadow, a `media` group (2000) with `node` in it, and
a global `uuid`. That recipe is now this module's Dockerfile, built on the
upstream 1.71.3 image named in build.on by digest, with uuid pinned to the
version the running image carries (14.0.1) - Code nodes require() it. The
media group is how the container writes into the shared media library, a
read-write `access` (ADR 0051), mounted where workflows expect it,
/media-library.

The workflows also use a redis (the Redis nodes of the chat workflows) and a
Selenium Chrome (the scraper), which the previous deployment ran beside n8n.
Both are containers on the module's own network, publishing nothing, pinned
to the digests in use; redis keeps its append-only file in a placed
directory.

The basic-auth secret is gone: N8N_BASIC_AUTH_* was removed in n8n 1.0 and
did nothing. The grant's password is a 0400 file owned by `node`, read
through DB_POSTGRESDB_PASSWORD_FILE, so nothing secret is in the
environment. The credentials' encryption key is n8n's own, in the data
directory (config), and moves with it - nothing to mint or accept.

Verified: catalogue tests with MESH_CATALOGUE set; the Dockerfile built
against the pinned base gives n8n 1.71.3, uid 1000 in group 2000, uuid
14.0.1 - the running image's shape. Throwaway containers: an instance on
PostgreSQL 15 with an owner, a workflow and an encrypted credential;
stopped, copied, dumped from the copy, restored (--no-owner --role, the
uuid-ossp extension pre-made by the superuser) into a grant-shaped
database on the postgres module's pgvector image (PG17); the new shape
(password from the file, data dir copied) serves /healthz, the owner logs
in, the workflow is listed, and the credential decrypts with the carried
key. The node user writes into a root:2000 0775 library through the media
group; redis and Selenium resolve by name on the module network and
Selenium reports ready. Test containers and data removed.

modules/bazarr/module.json

@@ -94,7 +94,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BAZARR_URL": "http://127.0.0.1:${port:6767}",
+        "MESH_BAZARR_URL": "http://127.0.0.1:6767",
         "MESH_BAZARR_API_KEY_FILE": "/run/secrets/api-key",
         "MESH_BAZARR_CONFIG_FILE": "/run/config/config.json",
         "MESH_BAZARR_CONFIG_DIR": "/var/lib/bazarr/config"

modules/bookshelf/module.json

@@ -76,7 +76,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BOOKSHELF_URL": "http://127.0.0.1:${port:8787}",
+        "MESH_BOOKSHELF_URL": "http://127.0.0.1:8787",
         "MESH_BOOKSHELF_CONFIG_DIR": "/var/lib/bookshelf/config"
       },
       "artifact": "runtime"

modules/lidarr/module.json

@@ -75,7 +75,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_LIDARR_URL": "http://127.0.0.1:${port:8686}",
+        "MESH_LIDARR_URL": "http://127.0.0.1:8686",
         "MESH_LIDARR_CONFIG_DIR": "/var/lib/lidarr/config"
       },
       "artifact": "runtime"

modules/n8n/Dockerfile

@@ -0,0 +1,20 @@
+# n8n with what its workflows reach for beyond the upstream image.
+#
+# The base is named, not pinned here (novox/hq issue 044): module.json's `build.on` declares N8N_BASE
+# as the upstream image by digest, and the mesh hands the build its own copy (ADR 0097).
+ARG N8N_BASE
+FROM ${N8N_BASE}
+
+USER root
+# - `media` (GID 2000), with `node` in it: the shared media library is group-writable by the
+#   operator's media group, and a workflow files downloads into it. A container resource cannot add
+#   a supplementary group, so the image's own /etc/group carries it. 2000 is the operator's media
+#   group today; novox/hq 153 proposes reading it from the accessed data (${access:<id>:gid}).
+# - uuid, pinned to the version the workflows were written against: Code nodes require() it
+#   (NODE_FUNCTION_ALLOW_EXTERNAL=*), and a Code node can only require what is installed.
+RUN apk add --no-cache shadow \
+ && groupadd -g 2000 media \
+ && usermod -aG media node \
+ && npm install -g uuid@14.0.1
+
+USER node

modules/n8n/module.json

@@ -18,44 +18,60 @@
     }
   },
   "binds": {
-    "postgres-database": "/var/lib/n8n/database.json",
-    "route": "/var/lib/n8n/route.json"
+    "postgres-database": "${dir:state}/database.json",
+    "route": "${dir:state}/route.json"
   },
   "secrets": {
-    "postgres-database": "/var/lib/n8n/database.secret"
-  },
-  "own-secrets": {
-    "basic-auth": "/var/lib/n8n/basic-auth.secret"
+    "postgres-database": "${dir:state}/database.secret"
   },
+  "accesses": [
+    {
+      "path": "/services/media",
+      "mode": "read-write"
+    }
+  ],
   "listens": [
     {
       "name": "web",
-      "port": 5682,
+      "port": 5678,
       "protocol": "tcp",
       "from": "mesh",
-      "why": "the n8n editor and webhook endpoints over http; the public name n8n.novox.be is a route grant, and route-proxy reaches it on this published port"
+      "why": "the n8n editor, its REST API and the webhook endpoints workflows are triggered through; a public name is the route's"
     }
   ],
   "resources": [
     {
       "id": "state",
       "type": "directory",
-      "path": "/var/lib/n8n",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
     },
     {
       "id": "data",
       "type": "directory",
-      "path": "/services/n8n/n8n-data",
       "mode": "0700",
       "owner": "1000:1000"
     },
+    {
+      "id": "cache",
+      "type": "directory",
+      "mode": "0700",
+      "owner": "999:999"
+    },
+    {
+      "id": "database-secret",
+      "type": "file",
+      "path": "${dir:state}/n8n-database.secret",
+      "mode": "0400",
+      "owner": "1000:1000",
+      "content": "${secret:postgres-database}"
+    },
     {
       "id": "server-env",
       "type": "file",
-      "path": "/var/lib/n8n/server.env",
+      "path": "${dir:state}/server.env",
       "mode": "0600",
-      "content": "N8N_HOST=n8n.novox.be\nN8N_PORT=5678\nN8N_PROTOCOL=https\nWEBHOOK_URL=https://n8n.novox.be/\nN8N_BASIC_AUTH_ACTIVE=true\nN8N_BASIC_AUTH_USER=admin\nN8N_BASIC_AUTH_PASSWORD=${secret:basic-auth}\nNODE_FUNCTION_ALLOW_BUILTIN=*\nNODE_FUNCTION_ALLOW_EXTERNAL=*\nDB_TYPE=postgresdb\nDB_POSTGRESDB_HOST=${bound:postgres-database:at}\nDB_POSTGRESDB_PORT=${bound:postgres-database:port}\nDB_POSTGRESDB_DATABASE=${bound:postgres-database:as}\nDB_POSTGRESDB_USER=${bound:postgres-database:as}\nDB_POSTGRESDB_PASSWORD=${secret:postgres-database}\n"
+      "content": "N8N_HOST=${bound:route:name}\nN8N_PORT=5678\nN8N_PROTOCOL=https\nWEBHOOK_URL=https://${bound:route:name}/\nNODE_FUNCTION_ALLOW_BUILTIN=*\nNODE_FUNCTION_ALLOW_EXTERNAL=*\nDB_TYPE=postgresdb\nDB_POSTGRESDB_HOST=${bound:postgres-database:at}\nDB_POSTGRESDB_PORT=${bound:postgres-database:port}\nDB_POSTGRESDB_DATABASE=${bound:postgres-database:as}\nDB_POSTGRESDB_USER=${bound:postgres-database:as}\nDB_POSTGRESDB_PASSWORD_FILE=/run/secrets/database\n"
     },
     {
       "id": "net",
@@ -66,18 +82,61 @@
       "id": "server",
       "type": "container",
       "name": "n8n",
-      "image": "n8nio/n8n@sha256:4846eb2f4b874ab04cde7fc1e249d2ddaec66e9aea64439beb2972cfea88e3c0",
+      "artifact": "server",
       "network": "n8n",
       "env-file": [
-        "/var/lib/n8n/server.env"
+        "${dir:state}/server.env"
       ],
       "ports": [
         "5678"
       ],
       "volumes": [
-        "/services/n8n/n8n-data:/home/node/.n8n"
+        "${dir:data}:/home/node/.n8n",
+        "${dir:state}/n8n-database.secret:/run/secrets/database:ro",
+        "/services/media:/media-library"
+      ]
+    },
+    {
+      "id": "cache-server",
+      "type": "container",
+      "name": "n8n-redis",
+      "image": "redis@sha256:8a1efc5f479551822b47424ccae982026b633f28818eab0387348120a61e10e2",
+      "network": "n8n",
+      "args": [
+        "redis-server",
+        "--appendonly",
+        "yes"
       ],
-      "secrets-in-environment": "n8n's loader honours <VAR>_FILE for every setting; convertible, awaiting a bed that proves it (N8N_BASIC_AUTH_* was removed in n8n 1.0 and is likely dead)"
+      "volumes": [
+        "${dir:cache}:/data"
+      ]
+    },
+    {
+      "id": "browser",
+      "type": "container",
+      "name": "n8n-selenium",
+      "image": "selenium/standalone-chrome@sha256:9ae1c78e9b2ca9fe4b22e57873b5ee34aeb8e814e3122293eef4c3abe4c5f448",
+      "network": "n8n",
+      "env": {
+        "SE_ENABLE_TRACING": "false",
+        "SE_NODE_MAX_SESSIONS": "5",
+        "SE_NODE_OVERRIDE_MAX_SESSIONS": "true"
+      }
     }
-  ]
+  ],
+  "build": {
+    "on": [
+      {
+        "arg": "N8N_BASE",
+        "image": "n8nio/n8n@sha256:4846eb2f4b874ab04cde7fc1e249d2ddaec66e9aea64439beb2972cfea88e3c0"
+      }
+    ],
+    "artifacts": [
+      {
+        "name": "server",
+        "kind": "image",
+        "from": "Dockerfile"
+      }
+    ]
+  }
 }

modules/nzbget/module.json

@@ -81,7 +81,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_NZBGET_URL": "http://127.0.0.1:${port:6789}",
+        "MESH_NZBGET_URL": "http://127.0.0.1:6789",
         "MESH_NZBGET_PASSWORD_FILE": "/run/secrets/password",
         "MESH_NZBGET_CONFIG_FILE": "/run/config/config.json",
         "MESH_NZBGET_CONFIG_DIR": "/var/lib/nzbget/config"

modules/qbittorrent/client.ts

@@ -3,10 +3,8 @@
 // qbittorrent. Both this module's tools and its events entrypoint import it, and nothing outside
 // qbittorrent does.
 //
-// The WebUI authenticates with a session cookie obtained by POSTing credentials, and guards
-// against CSRF by checking the Referer header. The cookie was `SID` before qBittorrent 5.2 and is
-// `QBT_SID_<port>` since, and a successful login answers 200 "Ok." before and 204 with no body
-// since — both are accepted. Node's fetch keeps no cookie jar, so the cookie is
+// The WebUI authenticates with a session cookie (SID) obtained by POSTing credentials, and guards
+// against CSRF by checking the Referer header. Node's fetch keeps no cookie jar, so the SID is
 // captured on login and carried by hand on every later call, with a single re-login on expiry.
 
 import { readFileSync } from "node:fs";
@@ -41,21 +39,6 @@ function meshConfig(file?: string): Record<string, string> {
   catch { return {}; }
 }
 
-/** The WebUI username from qBittorrent's own qBittorrent.conf, in the config directory the mesh
- *  mounts read-only (MESH_QBITTORRENT_CONFIG_DIR, which is the container's /config). The software's
- *  file is the truth about who may log in, so the tools ask it rather than a setting that could
- *  disagree. Absent, unreadable or unset yields undefined. */
-function confUsername(dir: string | undefined): string | undefined {
-  if (!dir) return undefined;
-  try {
-    const line = readFileSync(`${dir.replace(/\/$/, "")}/qBittorrent/qBittorrent.conf`, "utf8")
-      .split(/\r?\n/)
-      .find((l) => l.startsWith("WebUI\\Username="));
-    const value = line?.slice("WebUI\\Username=".length).trim();
-    return value ? value : undefined;
-  } catch { return undefined; }
-}
-
 /** Read a secret the mesh mounted at a file path (an own-secret delivered by `secret accept`);
  *  absent or unreadable yields undefined so callers fall back rather than crash. */
 function readSecret(file?: string): string | undefined {
@@ -66,8 +49,7 @@ function readSecret(file?: string): string | undefined {
 
 export class QbittorrentClient {
   readonly baseUrl: string;
-  /** The session cookie as `name=value`, sent back exactly as it was set. */
-  private session: string | null = null;
+  private sid: string | null = null;
 
   constructor(
     baseUrl: string,
@@ -81,9 +63,7 @@ export class QbittorrentClient {
    * Build from the module's resolved environment. URL and password are read from
    * MESH_QBITTORRENT_URL and MESH_QBITTORRENT_PASSWORD; both must be present — an unconfigured
    * qBittorrent throws rather than pretend to be reachable, so the tools/events simply do not load
-   * (the harness treats the throw as "exposes nothing"). The user is read from qBittorrent.conf,
-   * falling back to "admin", the image's default. The password cannot be read there — qBittorrent
-   * keeps only a PBKDF2 hash — so it is the own-secret the operator accepts.
+   * (the harness treats the throw as "exposes nothing"). The user defaults to "admin".
    */
   static fromEnv(env: NodeJS.ProcessEnv = process.env): QbittorrentClient {
     const cfg = meshConfig(env.MESH_QBITTORRENT_CONFIG_FILE);
@@ -92,9 +72,7 @@ export class QbittorrentClient {
     if (!url || !password) {
       throw new Error("qBittorrent not configured — set MESH_QBITTORRENT_URL and MESH_QBITTORRENT_PASSWORD");
     }
-    // The WebUI username: a setting or the environment if one says so, else whatever
-    // qBittorrent.conf holds (an adopted machine keeps its own), else the image's "admin".
-    const user = cfg.user ?? env.MESH_QBITTORRENT_USER ?? confUsername(env.MESH_QBITTORRENT_CONFIG_DIR) ?? "admin";
+    const user = cfg.user ?? env.MESH_QBITTORRENT_USER ?? "admin";
     return new QbittorrentClient(url, user, password);
   }
 
@@ -104,22 +82,19 @@ export class QbittorrentClient {
       headers: { "Content-Type": "application/x-www-form-urlencoded", Referer: this.baseUrl },
       body: new URLSearchParams({ username: this.user, password: this.password }),
     });
-    if (res.status === 401) throw new Error("qBittorrent login rejected — check credentials");
     if (!res.ok) throw new Error(`qBittorrent login: ${res.status} ${await res.text()}`);
-    // 4.x/5.0/5.1 answer 200 "Ok." or 200 "Fails."; 5.2 answers 204 with no body, or 401.
-    const body = (await res.text()).trim();
-    if (res.status !== 204 && body !== "Ok.") {
+    if ((await res.text()).trim() !== "Ok.") {
       throw new Error("qBittorrent login rejected — check credentials");
     }
-    const match = res.headers.get("set-cookie")?.match(/((?:QBT_)?SID(?:_\d+)?)=([^;]+)/);
-    if (!match) throw new Error("qBittorrent login returned no session cookie");
-    this.session = `${match[1]}=${match[2]}`;
+    const match = res.headers.get("set-cookie")?.match(/SID=([^;]+)/);
+    if (!match) throw new Error("qBittorrent login returned no SID cookie");
+    this.sid = match[1];
   }
 
   private async call(method: "GET" | "POST", path: string, form?: Record<string, string>): Promise<Response> {
-    if (!this.session) await this.login();
+    if (!this.sid) await this.login();
     const doFetch = (): Promise<Response> => {
-      const headers: Record<string, string> = { Referer: this.baseUrl, Cookie: this.session ?? "" };
+      const headers: Record<string, string> = { Referer: this.baseUrl, Cookie: `SID=${this.sid}` };
       const init: RequestInit = { method, headers };
       if (form) {
         headers["Content-Type"] = "application/x-www-form-urlencoded";
@@ -128,8 +103,8 @@ export class QbittorrentClient {
       return fetch(`${this.baseUrl}/api/v2/${path}`, init);
     };
     let res = await doFetch();
-    if (res.status === 403 || res.status === 401) {
-      // The session expired — re-authenticate once and retry, rather than fail a routine call.
+    if (res.status === 403) {
+      // The SID expired — re-authenticate once and retry, rather than fail a routine call.
       await this.login();
       res = await doFetch();
     }

modules/qbittorrent/module.json

@@ -17,24 +17,10 @@
   "listens": [
     {
       "name": "web",
-      "port": 8112,
+      "port": 8080,
       "protocol": "tcp",
       "from": "mesh",
-      "why": "the download client's pages, and the WebUI API its consumers and its own tools call. qBittorrent refuses a request whose Host names a port other than the one it listens on, so it listens on the machine port itself (host network, WEBUI_PORT=${port:8112}) and the two cannot differ on any machine"
-    },
-    {
-      "name": "peers",
-      "port": 6881,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "incoming BitTorrent peer connections; announced to trackers and peers, so qBittorrent listens on the machine port itself (TORRENTING_PORT=${port:6881})"
-    },
-    {
-      "name": "peers-udp",
-      "port": 6881,
-      "protocol": "udp",
-      "from": "mesh",
-      "why": "DHT and uTP on the same number as the peer port"
+      "why": "the download client's pages"
     }
   ],
   "accesses": [
@@ -50,15 +36,10 @@
       "path": "/var/lib/mesh/qbittorrent",
       "mode": "0700"
     },
-    {
-      "id": "state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "."
-    },
     {
       "id": "config",
       "type": "directory",
+      "path": "/services/qbittorrent/config",
       "mode": "0700",
       "owner": "1000:1000"
     },
@@ -66,24 +47,24 @@
       "id": "server",
       "type": "container",
       "name": "qbittorrent",
-      "image": "lscr.io/linuxserver/qbittorrent@sha256:457e4eec2ee3f5e4ef59f237ad51f6143deba9f7445ab48bb5204a98888ef9aa",
+      "image": "lscr.io/linuxserver/qbittorrent@sha256:a00b6a597a3832a1814cde0ef60abc55c94644f3f80902c3432f6af6de8d4a96",
       "env": {
         "PUID": "1000",
         "PGID": "1000",
-        "TZ": "Etc/UTC",
-        "WEBUI_PORT": "${port:8112}",
-        "TORRENTING_PORT": "${port:6881}"
+        "TZ": "Etc/UTC"
       },
-      "volumes": [
-        "${dir:config}:/config",
-        "/services/media/downloads:/downloads"
+      "ports": [
+        "8080"
       ],
-      "network": "host"
+      "volumes": [
+        "/services/qbittorrent/config:/config",
+        "/services/media/downloads:/downloads"
+      ]
     },
     {
       "id": "runtime-config",
       "type": "file",
-      "path": "${dir:state}/config.json",
+      "path": "/var/lib/mesh/qbittorrent/config.json",
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
@@ -96,46 +77,22 @@
       "volumes": [
         "/var/lib/mesh/qbittorrent/broker:/run/secrets/broker:ro",
         "/var/lib/mesh/qbittorrent/password:/run/secrets/password:ro",
-        "${dir:state}/config.json:/run/config/config.json:ro",
-        "${dir:config}:/var/lib/qbittorrent/config:ro"
+        "/var/lib/mesh/qbittorrent/config.json:/run/config/config.json:ro",
+        "/services/qbittorrent/config:/var/lib/qbittorrent/config:ro"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_QBITTORRENT_URL": "http://127.0.0.1:${port:8112}",
+        "MESH_QBITTORRENT_URL": "http://127.0.0.1:8080",
         "MESH_QBITTORRENT_PASSWORD_FILE": "/run/secrets/password",
         "MESH_QBITTORRENT_CONFIG_FILE": "/run/config/config.json",
         "MESH_QBITTORRENT_CONFIG_DIR": "/var/lib/qbittorrent/config"
       },
       "restart-on": [
-        "runtime-config",
-        "needs-password"
+        "runtime-config"
       ],
       "artifact": "runtime"
     }
   ],
-  "provides": [
-    "qbittorrent-api"
-  ],
-  "serves": {
-    "qbittorrent-api": {
-      "scheme": "http",
-      "port": 8112,
-      "url-base": "",
-      "username": "admin"
-    }
-  },
-  "requires": [
-    "route"
-  ],
-  "contributes": {
-    "route": {
-      "label": "qbittorrent",
-      "endpoint": "web"
-    }
-  },
-  "binds": {
-    "route": "${dir:state}/route.json"
-  },
   "build": {
     "on": [
       {

modules/radarr/module.json

@@ -75,7 +75,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_RADARR_URL": "http://127.0.0.1:${port:7878}",
+        "MESH_RADARR_URL": "http://127.0.0.1:7878",
         "MESH_RADARR_CONFIG_DIR": "/var/lib/radarr/config"
       },
       "artifact": "runtime"

modules/searxng/module.json

@@ -100,7 +100,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SEARXNG_URL": "http://127.0.0.1:${port:8080}",
+        "MESH_SEARXNG_URL": "http://127.0.0.1:8080",
         "MESH_SEARXNG_CONFIG_FILE": "/run/config/config.json"
       },
       "restart-on": [

modules/sonarr/module.json

@@ -80,7 +80,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SONARR_URL": "http://127.0.0.1:${port:8989}",
+        "MESH_SONARR_URL": "http://127.0.0.1:8989",
         "MESH_SONARR_CONFIG_DIR": "/var/lib/sonarr/config"
       },
       "artifact": "runtime"