fix(uptime-kuma): fail when a list event is missing after login

Kuma 2.5.6 afterLogin (server/server.js:1839-1848) sends the
notification and API-key lists inside Promise.allSettled and acks the
login regardless. A missing notificationList was read as empty and
would create a second default "email" notification (double mails);
a missing apiKeyList would add a key without removing the old one.
The script now fails the run instead.

Verified against a local 2.5.6: fresh run creates everything, second
run reports no changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

ansible/plays/install-uptime-kuma.yml

@@ -5,6 +5,8 @@
 # Prerequisites:
 # - netbird-server play applied (docker, Traefik on netbird_netbird)
 # - OpenBao homelab/infrastructure/uptime-kuma with keys username, password
+# - OpenBao homelab/infrastructure/uptime-kuma/smtp with keys server, port, username, token
+# - homelab/infrastructure/uptime-kuma-metrics (key api_key) is written by the role
 # - VAULT_TOKEN in the environment (policy: uptime-kuma-vps)
 # - DNS for kuma.renner.uno pointing at the VPS
 

ansible/roles/uptime-kuma/defaults/main.yml

@@ -1,11 +1,20 @@
 ---
 uptime_kuma_version: "2.5.6"
 uptime_kuma_host: kuma.renner.uno
-# Not routed yet; reserved for the public status page.
+uptime_kuma_base_url: "https://{{ uptime_kuma_host }}"
+# Custom domain of the status page; not routed by Traefik yet.
 uptime_kuma_status_host: uptime.renner.uno
+uptime_kuma_status_slug: renner
+uptime_kuma_status_title: Renner
 uptime_kuma_dir: /opt/uptime-kuma
 uptime_kuma_traefik_network: netbird_netbird
 
+uptime_kuma_smtp_from: uptime@renner.uno
+# Alertmanager email receiver in kubernetes/apps/monitoring/helmrelease-prometheus.yaml.
+uptime_kuma_smtp_to: admin@renner.uno
+
 uptime_kuma_openbao_url: https://openbao.renner.uno
 uptime_kuma_openbao_mount: homelab
 uptime_kuma_openbao_path: infrastructure/uptime-kuma
+uptime_kuma_openbao_smtp_path: infrastructure/uptime-kuma/smtp
+uptime_kuma_openbao_metrics_path: infrastructure/uptime-kuma-metrics

ansible/roles/uptime-kuma/files/kuma-setup.js

@@ -1,46 +1,225 @@
-// Creates the Uptime Kuma admin user on first start; exits 0 if already set up.
-// Credentials come from KUMA_SETUP_USERNAME / KUMA_SETUP_PASSWORD only.
+// Bootstraps Uptime Kuma: admin user, general settings, SMTP notification, status page,
+// and (when KUMA_METRICS_ROTATE=true) a fresh Prometheus API key written to KUMA_METRICS_KEY_FILE.
+// All input comes from environment variables; secrets are never printed.
+// Output lines: "admin user created" / "already set up", then "changed: <step>" or "ok: <step>".
+const fs = require("fs");
 const { io } = require("socket.io-client");
 
-const username = process.env.KUMA_SETUP_USERNAME;
-const password = process.env.KUMA_SETUP_PASSWORD;
-if (!username || !password) {
-    console.error("KUMA_SETUP_USERNAME and KUMA_SETUP_PASSWORD must be set");
+const KUMA_URL = "http://127.0.0.1:3001";
+const EMIT_TIMEOUT_MS = 30000;
+const TOTAL_TIMEOUT_MS = 180000;
+// Defaults the Kuma settings page applies to unset keys before saving (src/pages/Settings.vue).
+const SETTINGS_DEFAULTS = {
+    checkUpdate: true,
+    searchEngineIndex: false,
+    entryPage: "dashboard",
+    nscd: true,
+    keepDataPeriodDays: 180,
+    tlsExpiryNotifyDays: [7, 14, 21],
+    domainExpiryNotifyDays: [7, 14, 21],
+    trustProxy: false,
+};
+
+const REQUIRED = [
+    "KUMA_SETUP_USERNAME",
+    "KUMA_SETUP_PASSWORD",
+    "KUMA_BASE_URL",
+    "KUMA_SMTP_HOST",
+    "KUMA_SMTP_PORT",
+    "KUMA_SMTP_USERNAME",
+    "KUMA_SMTP_PASSWORD",
+    "KUMA_SMTP_FROM",
+    "KUMA_SMTP_TO",
+    "KUMA_STATUS_SLUG",
+    "KUMA_STATUS_TITLE",
+    "KUMA_STATUS_DOMAIN",
+];
+const missing = REQUIRED.filter((name) => !process.env[name]);
+const rotateMetricsKey = process.env.KUMA_METRICS_ROTATE === "true";
+if (rotateMetricsKey && !process.env.KUMA_METRICS_KEY_FILE) {
+    missing.push("KUMA_METRICS_KEY_FILE");
+}
+if (missing.length > 0) {
+    console.error(`missing environment variables: ${missing.join(", ")}`);
     process.exit(2);
 }
+const env = process.env;
 
-const socket = io("http://127.0.0.1:3001", { transports: ["websocket"], reconnection: false });
-const timer = setTimeout(() => {
-    console.error("timeout: no response from Uptime Kuma within 30s");
-    process.exit(1);
-}, 30000);
+const socket = io(KUMA_URL, { transports: ["websocket"], reconnection: false });
+const lists = {};
+const LIST_EVENTS = ["notificationList", "apiKeyList", "statusPageList"];
+for (const event of LIST_EVENTS) {
+    socket.on(event, (data) => {
+        lists[event] = data;
+    });
+}
 
 let finished = false;
 function done(code, msg) {
     if (finished) return;
     finished = true;
-    clearTimeout(timer);
-    (code === 0 ? console.log : console.error)(msg);
+    clearTimeout(watchdog);
+    if (msg) (code === 0 ? console.log : console.error)(msg);
     socket.close();
     process.exit(code);
 }
 
+const watchdog = setTimeout(() => done(1, `timeout: bootstrap did not finish within ${TOTAL_TIMEOUT_MS / 1000}s`), TOTAL_TIMEOUT_MS);
 socket.on("connect_error", (err) => done(1, `connect_error: ${err.message}`));
-socket.on("disconnect", (reason) => done(1, `disconnected before setup finished: ${reason}`));
+socket.on("disconnect", (reason) => done(1, `disconnected before bootstrap finished: ${reason}`));
 
-// Kuma registers socket handlers only after emitting info.
-socket.once("info", () => {
-    socket.emit("needSetup", (needSetup) => {
-        if (!needSetup) {
-            done(0, "already set up");
-            return;
-        }
-        socket.emit("setup", username, password, (res) => {
-            if (res && res.ok) {
-                done(0, "admin user created");
-            } else {
-                done(1, `setup failed: ${res && res.msg ? res.msg : JSON.stringify(res)}`);
-            }
+function call(event, ...args) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`timeout waiting for ${event}`)), EMIT_TIMEOUT_MS);
+        socket.emit(event, ...args, (res) => {
+            clearTimeout(timer);
+            resolve(res);
         });
     });
-});
+}
+
+async function callOk(event, ...args) {
+    const res = await call(event, ...args);
+    if (!res || !res.ok) {
+        throw new Error(`${event} failed: ${res && res.msg ? res.msg : JSON.stringify(res)}`);
+    }
+    return res;
+}
+
+function report(step, changed) {
+    console.log(`${changed ? "changed" : "ok"}: ${step}`);
+}
+
+// Kuma registers socket handlers only after emitting info.
+function waitForInfo() {
+    return new Promise((resolve) => socket.once("info", resolve));
+}
+
+async function setupAdmin() {
+    const needSetup = await call("needSetup");
+    if (!needSetup) {
+        console.log("already set up");
+        return;
+    }
+    await callOk("setup", env.KUMA_SETUP_USERNAME, env.KUMA_SETUP_PASSWORD);
+    console.log("admin user created");
+}
+
+async function login() {
+    await callOk("login", { username: env.KUMA_SETUP_USERNAME, password: env.KUMA_SETUP_PASSWORD, token: "" });
+    // afterLogin sends the lists before the login ack but swallows send failures.
+    for (const event of LIST_EVENTS) {
+        if (lists[event] === undefined) {
+            throw new Error(`${event} not received after login`);
+        }
+    }
+}
+
+async function ensureSettings() {
+    const { data } = await callOk("getSettings");
+    if (data.trustProxy === true && data.primaryBaseURL === env.KUMA_BASE_URL) {
+        report("settings", false);
+        return;
+    }
+    const updated = { ...SETTINGS_DEFAULTS, ...data, trustProxy: true, primaryBaseURL: env.KUMA_BASE_URL };
+    await callOk("setSettings", updated, "");
+    report("settings", true);
+}
+
+async function ensureNotification() {
+    const port = Number(env.KUMA_SMTP_PORT);
+    const desired = {
+        name: "email",
+        type: "smtp",
+        isDefault: true,
+        smtpHost: env.KUMA_SMTP_HOST,
+        smtpPort: port,
+        // 465 is implicit TLS; any other port uses STARTTLS.
+        smtpSecure: port === 465,
+        smtpIgnoreSTARTTLS: false,
+        smtpUsername: env.KUMA_SMTP_USERNAME,
+        smtpPassword: env.KUMA_SMTP_PASSWORD,
+        smtpFrom: env.KUMA_SMTP_FROM,
+        smtpTo: env.KUMA_SMTP_TO,
+    };
+    const existing = (lists.notificationList || []).filter((n) => n.name === desired.name).sort((a, b) => a.id - b.id)[0];
+    const current = existing ? JSON.parse(existing.config || "{}") : {};
+    const upToDate =
+        existing && existing.isDefault === true && Object.keys(desired).every((key) => current[key] === desired[key]);
+    if (upToDate) {
+        report("notification", false);
+        return;
+    }
+    await callOk("addNotification", { ...current, ...desired, applyExisting: true }, existing ? existing.id : null);
+    report("notification", true);
+}
+
+async function fetchPublicGroupList(slug) {
+    const res = await fetch(`${KUMA_URL}/api/status-page/${encodeURIComponent(slug)}`);
+    if (!res.ok) {
+        throw new Error(`GET /api/status-page/${slug} returned ${res.status}`);
+    }
+    const body = await res.json();
+    return (body.publicGroupList || []).map((group) => ({
+        id: group.id,
+        name: group.name,
+        monitorList: (group.monitorList || []).map((monitor) => {
+            const entry = { id: monitor.id };
+            if (monitor.sendUrl !== undefined) entry.sendUrl = monitor.sendUrl;
+            if (monitor.url !== undefined) entry.url = monitor.url;
+            return entry;
+        }),
+    }));
+}
+
+async function ensureStatusPage() {
+    const slug = env.KUMA_STATUS_SLUG;
+    let changed = false;
+    const pages = Object.values(lists.statusPageList || {});
+    if (!pages.some((page) => page.slug === slug)) {
+        await callOk("addStatusPage", env.KUMA_STATUS_TITLE, slug);
+        changed = true;
+    }
+    const { config } = await callOk("getStatusPage", slug);
+    const domains = config.domainNameList || [];
+    if (config.title !== env.KUMA_STATUS_TITLE || !domains.includes(env.KUMA_STATUS_DOMAIN)) {
+        // saveStatusPage replaces all groups, so the current ones are sent back unchanged.
+        const publicGroupList = await fetchPublicGroupList(slug);
+        const updated = {
+            ...config,
+            title: env.KUMA_STATUS_TITLE,
+            domainNameList: domains.includes(env.KUMA_STATUS_DOMAIN) ? domains : [...domains, env.KUMA_STATUS_DOMAIN],
+        };
+        await callOk("saveStatusPage", slug, updated, config.icon, publicGroupList);
+        changed = true;
+    }
+    report("status page", changed);
+}
+
+async function rotateMetricsApiKey() {
+    if (!rotateMetricsKey) {
+        report("metrics api key", false);
+        return;
+    }
+    for (const key of (lists.apiKeyList || []).filter((k) => k.name === "prometheus")) {
+        await callOk("deleteAPIKey", key.id);
+    }
+    const res = await callOk("addAPIKey", { name: "prometheus", expires: null, active: 1 });
+    fs.writeFileSync(env.KUMA_METRICS_KEY_FILE, res.key, { mode: 0o600 });
+    report("metrics api key", true);
+}
+
+async function main() {
+    await waitForInfo();
+    await setupAdmin();
+    await login();
+    await ensureSettings();
+    await ensureNotification();
+    await ensureStatusPage();
+    await rotateMetricsApiKey();
+}
+
+main().then(
+    () => done(0),
+    (err) => done(1, err.message)
+);

ansible/roles/uptime-kuma/tasks/main.yml

@@ -14,6 +14,33 @@
   register: _uptime_kuma_secret
   no_log: true
 
+- name: Read SMTP credentials from OpenBao
+  community.hashi_vault.vault_kv2_get:
+    url: "{{ uptime_kuma_openbao_url }}"
+    engine_mount_point: "{{ uptime_kuma_openbao_mount }}"
+    path: "{{ uptime_kuma_openbao_smtp_path }}"
+    auth_method: token
+  delegate_to: localhost
+  become: false
+  run_once: true
+  register: _uptime_kuma_smtp
+  no_log: true
+
+- name: Read metrics API key from OpenBao
+  community.hashi_vault.vault_kv2_get:
+    url: "{{ uptime_kuma_openbao_url }}"
+    engine_mount_point: "{{ uptime_kuma_openbao_mount }}"
+    path: "{{ uptime_kuma_openbao_metrics_path }}"
+    auth_method: token
+  delegate_to: localhost
+  become: false
+  run_once: true
+  register: _uptime_kuma_metrics_secret
+  failed_when:
+    - _uptime_kuma_metrics_secret.failed | default(false)
+    - "'Invalid or missing path' not in (_uptime_kuma_metrics_secret.msg | default(''))"
+  no_log: true
+
 - name: Ensure Uptime Kuma directories exist
   ansible.builtin.file:
     path: "{{ item }}"
@@ -63,15 +90,80 @@
   retries: 30
   delay: 5
 
-- name: Create the admin user if Uptime Kuma is not set up
-  ansible.builtin.command: docker compose exec -T -e KUMA_SETUP_USERNAME -e KUMA_SETUP_PASSWORD uptime-kuma node /app/kuma-setup.js
+- name: Check the stored metrics API key against Uptime Kuma
+  ansible.builtin.uri:
+    url: http://127.0.0.1:3001/metrics
+    headers:
+      Authorization: "Basic {{ (':' ~ _uptime_kuma_metrics_key) | b64encode }}"
+    status_code: [200, 401]
+  vars:
+    _uptime_kuma_metrics_key: "{{ (_uptime_kuma_metrics_secret.secret | default({})).api_key | default('') }}"
+  when: _uptime_kuma_metrics_key | length > 0
+  register: _uptime_kuma_metrics_check
+  no_log: true
+
+- name: Remove a leftover metrics API key handoff file
+  ansible.builtin.file:
+    path: "{{ uptime_kuma_dir }}/data/.metrics-api-key"
+    state: absent
+
+- name: Bootstrap Uptime Kuma
+  ansible.builtin.command:
+    argv:
+      - docker
+      - compose
+      - exec
+      - -T
+      - -e
+      - KUMA_SETUP_USERNAME
+      - -e
+      - KUMA_SETUP_PASSWORD
+      - -e
+      - KUMA_BASE_URL
+      - -e
+      - KUMA_SMTP_HOST
+      - -e
+      - KUMA_SMTP_PORT
+      - -e
+      - KUMA_SMTP_USERNAME
+      - -e
+      - KUMA_SMTP_PASSWORD
+      - -e
+      - KUMA_SMTP_FROM
+      - -e
+      - KUMA_SMTP_TO
+      - -e
+      - KUMA_STATUS_SLUG
+      - -e
+      - KUMA_STATUS_TITLE
+      - -e
+      - KUMA_STATUS_DOMAIN
+      - -e
+      - KUMA_METRICS_ROTATE
+      - -e
+      - KUMA_METRICS_KEY_FILE
+      - uptime-kuma
+      - node
+      - /app/kuma-setup.js
   args:
     chdir: "{{ uptime_kuma_dir }}"
   environment:
     KUMA_SETUP_USERNAME: "{{ _uptime_kuma_secret.secret.username }}"
     KUMA_SETUP_PASSWORD: "{{ _uptime_kuma_secret.secret.password }}"
+    KUMA_BASE_URL: "{{ uptime_kuma_base_url }}"
+    KUMA_SMTP_HOST: "{{ _uptime_kuma_smtp.secret.server }}"
+    KUMA_SMTP_PORT: "{{ _uptime_kuma_smtp.secret.port }}"
+    KUMA_SMTP_USERNAME: "{{ _uptime_kuma_smtp.secret.username }}"
+    KUMA_SMTP_PASSWORD: "{{ _uptime_kuma_smtp.secret.token }}"
+    KUMA_SMTP_FROM: "{{ uptime_kuma_smtp_from }}"
+    KUMA_SMTP_TO: "{{ uptime_kuma_smtp_to }}"
+    KUMA_STATUS_SLUG: "{{ uptime_kuma_status_slug }}"
+    KUMA_STATUS_TITLE: "{{ uptime_kuma_status_title }}"
+    KUMA_STATUS_DOMAIN: "{{ uptime_kuma_status_host }}"
+    KUMA_METRICS_ROTATE: "{{ 'false' if (_uptime_kuma_metrics_check.status | default(0)) == 200 else 'true' }}"
+    KUMA_METRICS_KEY_FILE: /app/data/.metrics-api-key
   register: _uptime_kuma_setup
-  changed_when: "'admin user created' in _uptime_kuma_setup.stdout"
+  changed_when: "'admin user created' in _uptime_kuma_setup.stdout or 'changed:' in _uptime_kuma_setup.stdout"
   failed_when: false
   no_log: true
 
@@ -80,6 +172,33 @@
     msg: "kuma-setup.js failed: rc={{ _uptime_kuma_setup.rc | default('undefined') }} stdout={{ _uptime_kuma_setup.stdout | default('') }} stderr={{ _uptime_kuma_setup.stderr | default('') }}"
   when: (_uptime_kuma_setup.rc | default(1)) != 0
 
+- name: Store the new metrics API key in OpenBao
+  when: "'changed: metrics api key' in _uptime_kuma_setup.stdout"
+  block:
+    - name: Read the new metrics API key
+      ansible.builtin.slurp:
+        src: "{{ uptime_kuma_dir }}/data/.metrics-api-key"
+      register: _uptime_kuma_new_metrics_key
+      no_log: true
+
+    - name: Write the metrics API key to OpenBao
+      community.hashi_vault.vault_kv2_write:
+        url: "{{ uptime_kuma_openbao_url }}"
+        engine_mount_point: "{{ uptime_kuma_openbao_mount }}"
+        path: "{{ uptime_kuma_openbao_metrics_path }}"
+        auth_method: token
+        data:
+          api_key: "{{ _uptime_kuma_new_metrics_key.content | b64decode }}"
+      delegate_to: localhost
+      become: false
+      run_once: true
+      no_log: true
+  always:
+    - name: Remove the metrics API key handoff file
+      ansible.builtin.file:
+        path: "{{ uptime_kuma_dir }}/data/.metrics-api-key"
+        state: absent
+
 - name: Record setup completion
   ansible.builtin.copy:
     content: ""

kubernetes/apps/hermes/hermes.yaml

@@ -49,7 +49,7 @@ spec:
         # connects from the pod network. No env equivalent exists, so it is
         # set in config.yaml on every start (idempotent).
         - name: config
-          image: nousresearch/hermes-agent:v0.22.2 # {"$imagepolicy": "flux-system:hermes"}
+          image: nousresearch/hermes-agent:v2026.9.24 # {"$imagepolicy": "flux-system:hermes"}
           command:
             - /opt/hermes/.venv/bin/hermes
             - config
@@ -89,7 +89,7 @@ spec:
               mountPath: /tools
       containers:
         - name: hermes
-          image: nousresearch/hermes-agent:v0.22.2 # {"$imagepolicy": "flux-system:hermes"}
+          image: nousresearch/hermes-agent:v2026.9.24 # {"$imagepolicy": "flux-system:hermes"}
           args: ["gateway", "run"]
           env:
             - name: HERMES_DASHBOARD

kubernetes/infrastructure/image-automation/hermes.yaml

@@ -8,9 +8,6 @@ spec:
   interval: 1h
 ---
 # v-prefix tags (v0.22.2). The filter skips rc.*, -desktop and per-arch tags.
-# The repo also carries the retired date-versioned releases (v2026.4.3 ..
-# v2026.9.24, last one 2026-09-24); as semver they sort above 0.x, so the
-# range caps below 1.0.0 or the policy picks the old v2026.9.24.
 apiVersion: image.toolkit.fluxcd.io/v1
 kind: ImagePolicy
 metadata:
@@ -24,4 +21,4 @@ spec:
     extract: '$ver'
   policy:
     semver:
-      range: ">=0.22.2 <1.0.0"
+      range: ">=0.22.2"

kubernetes/infrastructure/openbao/policies/uptime-kuma-vps.hcl

@@ -1,10 +1,18 @@
 # OpenBao policy: uptime-kuma-vps
-# Read-only on the Uptime Kuma admin credentials; self-renewal for the CI token. NOT applied by Flux.
+# Read on the Uptime Kuma admin and SMTP credentials; read/write on the metrics API key; self-renewal for the CI token. NOT applied by Flux.
 
 path "homelab/data/infrastructure/uptime-kuma" {
   capabilities = ["read"]
 }
 
+path "homelab/data/infrastructure/uptime-kuma/smtp" {
+  capabilities = ["read"]
+}
+
+path "homelab/data/infrastructure/uptime-kuma-metrics" {
+  capabilities = ["read", "create", "update"]
+}
+
 path "auth/token/renew-self" {
   capabilities = ["update"]
 }