worker: require credentials for the queue dashboard, keep health routes ahead of it

apps/public/content/docs/self-hosting/deploy-coolify.mdx

@@ -89,7 +89,7 @@ Coolify deploys OpenPanel with the following services:
 
 - **opapi**: OpenPanel API server (handles `/api` routes)
 - **opdashboard**: OpenPanel dashboard (frontend)
-- **opworker**: Background worker for processing events
+- **opworker**: Background worker for processing events (no public domain, see below)
 - **opdb**: PostgreSQL database
 - **opkv**: Redis cache
 - **opch**: ClickHouse analytics database
@@ -114,6 +114,12 @@ Coolify automatically handles these variables:
 
 You can configure optional variables like `ALLOW_REGISTRATION`, `RESEND_API_KEY`, `OPENAI_API_KEY`, etc. through Coolify's environment variable interface.
 
+#### The worker service
+
+`opworker` has no public domain and ships with `DISABLE_BULLBOARD=1`. Nothing on it is meant to be reached from the internet; the API and dashboard talk to it over the internal network, and Coolify's healthcheck uses localhost.
+
+If you want the queue dashboard, set `BULLBOARD_USERNAME` and `BULLBOARD_PASSWORD`, remove `DISABLE_BULLBOARD`, and reach it through your own proxy or an SSH tunnel. Basic auth is a thin lock, so do not put it on a public hostname on its own. The dashboard is read-only unless you also set `BULLBOARD_READONLY=0`.
+
 ### Updating OpenPanel
 
 To update OpenPanel in Coolify:

apps/public/content/docs/self-hosting/environment-variables.mdx

@@ -603,6 +603,45 @@ Disable BullMQ board UI. Set to `true` or `1` to disable the queue monitoring da
 DISABLE_BULLBOARD=true
 ```
 
+### BULLBOARD_USERNAME
+
+**Type**: `string`
+**Required**: No
+**Default**: none
+
+Username for the queue dashboard. The dashboard is not mounted unless both `BULLBOARD_USERNAME` and `BULLBOARD_PASSWORD` are set; without them the worker returns 404 for `/` and `/api/queues`. Requests must then carry HTTP basic credentials. `/metrics`, `/healthcheck`, `/healthz/live` and `/healthz/ready` stay open either way.
+
+**Example**:
+```bash
+BULLBOARD_USERNAME=admin
+```
+
+### BULLBOARD_PASSWORD
+
+**Type**: `string`
+**Required**: No
+**Default**: none
+
+Password for the queue dashboard. See `BULLBOARD_USERNAME`.
+
+**Example**:
+```bash
+BULLBOARD_PASSWORD=a-long-random-string
+```
+
+### BULLBOARD_READONLY
+
+**Type**: `boolean`
+**Required**: No
+**Default**: `true`
+
+The dashboard is read-only by default: it shows queues and jobs but will not pause, retry, empty or add anything. Set to `0` or `false` to allow those actions.
+
+**Example**:
+```bash
+BULLBOARD_READONLY=0
+```
+
 ### DISABLE_WORKERS
 
 **Type**: `boolean`

apps/worker/src/app.test.ts

@@ -0,0 +1,237 @@
+/**
+ * The queue dashboard is mounted at `/` and therefore catches every path that
+ * nothing before it claimed. These tests pin down two things: it is not
+ * reachable without credentials, and it never shadows the metrics or health
+ * routes that container orchestration and Prometheus call with no credentials.
+ *
+ * The queue, db and redis modules are replaced wholesale — the routes are
+ * exercised over a real socket, but nothing here talks to a datastore.
+ */
+
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { makeQueue } = vi.hoisted(() => {
+  const makeQueue = (name: string) => ({
+    name,
+    // BullMQAdapter refuses anything that does not look like a BullMQ queue.
+    metaValues: { version: 'bullmq5.0.0' },
+    getJobCounts: async () => ({
+      active: 0,
+      waiting: 0,
+      'waiting-children': 0,
+      prioritized: 0,
+      completed: 0,
+      failed: 0,
+      delayed: 0,
+      paused: 0,
+    }),
+    isPaused: async () => false,
+    getJobs: async () => [],
+  });
+  return { makeQueue };
+});
+
+vi.mock('@openpanel/queue', () => ({
+  eventsGroupQueues: [],
+  sessionsQueue: makeQueue('sessions'),
+  cronQueue: makeQueue('cron'),
+  notificationQueue: makeQueue('notification'),
+  importQueue: makeQueue('import'),
+  insightsQueue: makeQueue('insights'),
+  gscQueue: makeQueue('gsc'),
+  cohortComputeQueue: makeQueue('cohortCompute'),
+}));
+
+vi.mock('@openpanel/db', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@openpanel/db')>();
+  return {
+    ...actual,
+    db: { $executeRaw: async () => 1 },
+    chQuery: async () => [{ 1: 1 }],
+  };
+});
+
+vi.mock('@openpanel/redis', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@openpanel/redis')>();
+  return { ...actual, getRedisCache: () => ({ ping: async () => 'PONG' }) };
+});
+
+// The local-only cron trigger routes drag in every job module; they are not
+// what is under test.
+vi.mock('./boot-debug', () => ({ bootDebugRoutes: vi.fn() }));
+
+// An empty registry — the real one has collectors that scrape Redis and
+// ClickHouse. What matters here is that /metrics answers, not what it says.
+vi.mock('./metrics', async () => {
+  const client = (await import('prom-client')).default;
+  return { register: new client.Registry() };
+});
+
+import { createApp } from './app';
+
+const USERNAME = 'queues';
+const PASSWORD = 'correct-horse';
+
+const basic = (username: string, password: string) =>
+  `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+
+let server: Server | undefined;
+
+/** Boots the app on an ephemeral port and returns its origin. */
+async function boot() {
+  const app = createApp();
+  server = await new Promise<Server>((resolve) => {
+    const listening = app.listen(0, () => resolve(listening));
+  });
+  const { port } = server.address() as AddressInfo;
+  return `http://127.0.0.1:${port}`;
+}
+
+const OPEN_ROUTES = [
+  '/healthcheck',
+  '/healthz/live',
+  '/healthz/ready',
+  '/metrics',
+];
+
+beforeEach(() => {
+  for (const key of [
+    'BULLBOARD_USERNAME',
+    'BULLBOARD_PASSWORD',
+    'BULLBOARD_READONLY',
+    'DISABLE_BULLBOARD',
+  ]) {
+    delete process.env[key];
+  }
+});
+
+afterEach(async () => {
+  if (server) {
+    await new Promise((resolve) => server?.close(resolve));
+    server = undefined;
+  }
+});
+
+describe('worker http app', () => {
+  describe('with credentials configured', () => {
+    beforeEach(() => {
+      process.env.BULLBOARD_USERNAME = USERNAME;
+      process.env.BULLBOARD_PASSWORD = PASSWORD;
+    });
+
+    it('rejects the dashboard and its api without an Authorization header', async () => {
+      const origin = await boot();
+
+      for (const path of ['/', '/api/queues']) {
+        const res = await fetch(`${origin}${path}`);
+        expect(res.status, path).toBe(401);
+        expect(res.headers.get('www-authenticate')).toMatch(/^Basic/);
+      }
+    });
+
+    it('rejects a mutating route without an Authorization header', async () => {
+      const origin = await boot();
+
+      const res = await fetch(`${origin}/api/queues/cron/pause`, {
+        method: 'PUT',
+      });
+
+      expect(res.status).toBe(401);
+    });
+
+    it('rejects a wrong password of the same length as the right one', async () => {
+      const origin = await boot();
+      const wrong = `${'x'.repeat(PASSWORD.length - 1)}y`;
+      expect(wrong).toHaveLength(PASSWORD.length);
+
+      const res = await fetch(`${origin}/api/queues`, {
+        headers: { authorization: basic(USERNAME, wrong) },
+      });
+
+      expect(res.status).toBe(401);
+    });
+
+    it('serves the queue list, read-only, with the right credentials', async () => {
+      const origin = await boot();
+
+      const res = await fetch(`${origin}/api/queues`, {
+        headers: { authorization: basic(USERNAME, PASSWORD) },
+      });
+
+      expect(res.status).toBe(200);
+      const body = (await res.json()) as {
+        queues: {
+          name: string;
+          readOnlyMode: boolean;
+          allowRetries: boolean;
+        }[];
+      };
+      expect(body.queues.map((queue) => queue.name)).toContain('cron');
+      expect(body.queues.every((queue) => queue.readOnlyMode)).toBe(true);
+      expect(body.queues.some((queue) => queue.allowRetries)).toBe(false);
+    });
+
+    it('allows writes when BULLBOARD_READONLY is turned off', async () => {
+      process.env.BULLBOARD_READONLY = '0';
+      const origin = await boot();
+
+      const res = await fetch(`${origin}/api/queues`, {
+        headers: { authorization: basic(USERNAME, PASSWORD) },
+      });
+
+      const body = (await res.json()) as {
+        queues: { readOnlyMode: boolean; allowRetries: boolean }[];
+      };
+      expect(body.queues.every((queue) => queue.readOnlyMode)).toBe(false);
+      expect(body.queues.every((queue) => queue.allowRetries)).toBe(true);
+    });
+  });
+
+  it('does not mount the dashboard when no credentials are configured', async () => {
+    const origin = await boot();
+
+    const res = await fetch(`${origin}/api/queues`);
+
+    expect(res.status).toBe(404);
+  });
+
+  it('does not mount the dashboard when DISABLE_BULLBOARD is set', async () => {
+    process.env.DISABLE_BULLBOARD = '1';
+    process.env.BULLBOARD_USERNAME = USERNAME;
+    process.env.BULLBOARD_PASSWORD = PASSWORD;
+    const origin = await boot();
+
+    const res = await fetch(`${origin}/api/queues`);
+
+    expect(res.status).toBe(404);
+  });
+
+  describe.each([
+    ['no credentials', {}],
+    [
+      'credentials set',
+      { BULLBOARD_USERNAME: USERNAME, BULLBOARD_PASSWORD: PASSWORD },
+    ],
+    [
+      'dashboard disabled',
+      {
+        DISABLE_BULLBOARD: '1',
+        BULLBOARD_USERNAME: USERNAME,
+        BULLBOARD_PASSWORD: PASSWORD,
+      },
+    ],
+  ])('metrics and health with %s', (_label, env) => {
+    it('answer without credentials', async () => {
+      Object.assign(process.env, env);
+      const origin = await boot();
+
+      for (const path of OPEN_ROUTES) {
+        const res = await fetch(`${origin}${path}`);
+        expect(res.status, path).not.toBe(401);
+        expect(res.status, path).toBe(200);
+      }
+    });
+  });
+});