Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(infra): report pinned datastore hosts and start nothing for them

Yudhi Armyndharis2e4613cd521b
diff --git a/dashboard/src/pages/Infrastructure.test.ts b/dashboard/src/pages/Infrastructure.test.ts
index 05a7ec80c..85460631b 100644
--- a/dashboard/src/pages/Infrastructure.test.ts
+++ b/dashboard/src/pages/Infrastructure.test.ts
@@ -1075,9 +1075,30 @@ type Combo = (typeof COMBOS)[number];
const comboLabel = (c: Combo) => `${c.file}/${c.pin}/${c.running ? 'bundled' : 'external'}`;
const shownMode = (c: Combo) => (c.mode.builtInSet ? c.mode.builtIn : c.running);
+/** The notes rendered right under a toggle row, in order. */
+function notesUnderToggle(container: HTMLElement, labelText: string): string[] {
+ const notes: string[] = [];
+ let next = toggleInput(container, labelText).closest('.toggle-row')?.nextElementSibling;
+ while (next?.classList.contains('env-pin-note')) {
+ notes.push(next.textContent?.trim() ?? '');
+ next = next.nextElementSibling;
+ }
+ return notes;
+}
+
+const ENV_PIN_NOTE = /^Pinned by the environment variable (\S+)/;
+
function builtInNoteOf(container: HTMLElement, labelText: string): string | null {
- const next = toggleInput(container, labelText).closest('.toggle-row')?.nextElementSibling;
- return next?.classList.contains('env-pin-note') ? (next.textContent?.trim() ?? null) : null;
+ return notesUnderToggle(container, labelText).find(note => !ENV_PIN_NOTE.test(note)) ?? null;
+}
+
+/** The variable the pin note under a toggle names, or null when there is none. */
+function hostPinNoteOf(container: HTMLElement, labelText: string): string | null {
+ for (const note of notesUnderToggle(container, labelText)) {
+ const name = ENV_PIN_NOTE.exec(note)?.[1];
+ if (name) return name;
+ }
+ return null;
}
COMBOS.forEach((_, i) => {
@@ -1093,6 +1114,12 @@ COMBOS.forEach((_, i) => {
database: { connected: true, type: 'postgres', host: 'shared-db-host', builtIn: database.running },
redis: { enabled: true, connected: true, host: 'redis.internal', port: 6379, builtIn: redis.running },
storage: { type: 's3', bucket: 'media', builtIn: storage.running, s3Available: true },
+ // A pinned host is reported, so the page can say why its toggle cannot take effect.
+ envPinned: [
+ database.pin !== 'none' && 'DATABASE_HOST',
+ redis.pin !== 'none' && 'REDIS_HOST',
+ storage.pin !== 'none' && 'S3_ENDPOINT',
+ ].filter((key): key is string => typeof key === 'string'),
},
saved: {
...SAVED_CONFIG,
@@ -1107,12 +1134,13 @@ COMBOS.forEach((_, i) => {
await awaitSeeded(container);
const rows = [
- { combo: database, label: 'Use Built-in PostgreSQL Container' },
- { combo: redis, label: 'Use Built-in Redis Container' },
- { combo: storage, label: 'Use Built-in MinIO Container' },
+ { combo: database, label: 'Use Built-in PostgreSQL Container', hostKey: 'DATABASE_HOST' },
+ { combo: redis, label: 'Use Built-in Redis Container', hostKey: 'REDIS_HOST' },
+ { combo: storage, label: 'Use Built-in MinIO Container', hostKey: 'S3_ENDPOINT' },
];
- for (const { combo, label } of rows) {
+ for (const { combo, label, hostKey } of rows) {
assert.equal(toggleInput(container, label).checked, shownMode(combo), `${label} toggle`);
+ assert.equal(hostPinNoteOf(container, label), combo.pin === 'none' ? null : hostKey, `${label} pin note`);
const note =
!combo.mode.builtInSet || combo.mode.builtIn === combo.running
? null
@@ -1253,6 +1281,43 @@ test('without a reported pin those fields show no note, even when running and sa
);
});
+// The documented .env route to external services: the hosts are pinned, so the Use Built-in toggle cannot take
+// effect, and the note under it says which variable decides instead of the toggle reading OFF again after a reload.
+test('a host the environment pins is named under its Use Built-in toggle', async () => {
+ const { screen } = rtl;
+ resetFetchCalls();
+ overrides = {
+ status: {
+ ...INFRA_STATUS,
+ database: { connected: true, type: 'postgres', host: 'db.external.example', builtIn: false },
+ redis: { enabled: true, connected: true, host: 'cache.external.example', port: 6379, builtIn: false },
+ storage: { type: 's3', bucket: 'media', builtIn: false, s3Available: true },
+ envPinned: ['DATABASE_HOST', 'REDIS_HOST', 'S3_ENDPOINT'],
+ },
+ saved: {
+ ...SAVED_CONFIG,
+ database: { ...SAVED_CONFIG.database, host: 'db.external.example', builtIn: false, builtInSet: false },
+ redis: {
+ enabled: true,
+ builtIn: false,
+ builtInSet: false,
+ host: 'cache.external.example',
+ port: '6379',
+ passwordSet: false,
+ },
+ storage: { ...SAVED_CONFIG.storage, type: 's3', builtIn: false, builtInSet: false },
+ },
+ };
+ const { container } = renderInfrastructure();
+
+ await screen.findByText('Database Configuration');
+ await awaitSeeded(container);
+
+ assert.equal(hostPinNoteOf(container, 'Use Built-in PostgreSQL Container'), 'DATABASE_HOST');
+ assert.equal(hostPinNoteOf(container, 'Use Built-in Redis Container'), 'REDIS_HOST');
+ assert.equal(hostPinNoteOf(container, 'Use Built-in MinIO Container'), 'S3_ENDPOINT');
+});
+
test('the engine radio seeds from the effective engine when ENGINE_TYPE is pinned', async () => {
const { screen, waitFor } = rtl;
resetFetchCalls();
diff --git a/dashboard/src/pages/Infrastructure.tsx b/dashboard/src/pages/Infrastructure.tsx
index cff36127c..a52c9d291 100644
--- a/dashboard/src/pages/Infrastructure.tsx
+++ b/dashboard/src/pages/Infrastructure.tsx
@@ -191,7 +191,8 @@ export function Infrastructure() {
// as an environment pin even on a stock stack with no variable set anywhere (#1082).
// Pin-only: PUPPETEER_ARGS cannot go through settingNote, because the running list is re-tokenized and
// gains the pinned `--lang` flag, so it never string-compares equal to the saved value. The headless
- // flag and the two paths do have a running and a saved value, but show only a reported pin as well.
+ // flag and the two paths do have a running and a saved value, but show only a reported pin as well, and so
+ // do the three datastore hosts, under the Use Built-in toggle a pinned host overrides.
const pinNote = (envKey: string) =>
infraStatus?.envPinned?.includes(envKey) ? (
<p className="env-pin-note">
@@ -299,6 +300,7 @@ export function Infrastructure() {
infraStatus.database.builtIn,
savedBuiltIn(savedConfig.database, infraStatus.database.builtIn),
)}
+ {pinNote('DATABASE_HOST')}
{!configForm.dbConfig.builtIn && (
<div className="config-form">
@@ -602,6 +604,7 @@ export function Infrastructure() {
infraStatus.redis.builtIn,
savedBuiltIn(savedConfig.redis, infraStatus.redis.builtIn),
)}
+ {pinNote('REDIS_HOST')}
{!configForm.redisConfig.builtIn && (
<div className="config-form">
@@ -801,6 +804,7 @@ export function Infrastructure() {
infraStatus.storage.builtIn,
savedBuiltIn(savedConfig.storage, infraStatus.storage.builtIn),
)}
+ {pinNote('S3_ENDPOINT')}
{!configForm.storageConfig.builtIn && (
<>
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index af93d3159..f86c2e298 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -5529,7 +5529,7 @@ The `queue.webhooks` counters are live BullMQ job counts (`pending` = waiting +
`builtIn` (on `database`/`redis`/`storage`) reports whether OpenWA's own bundled container is actually running _and_ backing this service, detected live from the labelled container; when Docker is unreachable it falls back to the saved `*_BUILTIN` flag (one pinned by the environment first, else the one in `data/.env.generated`), and a host name alone counts for nothing there, since an external server may be called `postgres`. In S3 mode `storage` additionally carries `bucket` (when one is configured) and `s3Available` (re-probed, throttled, while false; once true it stays true until a restart, so a later outage does not clear it); in local mode neither key is present. `engine.webVersion`/`engine.webVersionSource` (`pinned` / `auto` / `native`) appear only on `whatsapp-web.js`; `webVersion` is `null` until the auto-resolve first succeeds. `engine.browserArgs` is the effective launch argument list: `PUPPETEER_ARGS` (or the four defaults shown) with `--lang=en-US` appended unless a `--lang` flag is already present.
-`envPinned` lists which of `DATABASE_TYPE`, `REDIS_ENABLED`, `STORAGE_TYPE`, `STORAGE_LOCAL_PATH`, `ENGINE_TYPE`, `PUPPETEER_HEADLESS`, `SESSION_DATA_PATH` and `PUPPETEER_ARGS` the host environment or the project `.env` sets. Those layers win over `data/.env.generated`, so a value saved for one of these keys through `PUT /api/infra/config` cannot take effect until that layer is changed.
+`envPinned` lists which of `DATABASE_TYPE`, `DATABASE_HOST`, `REDIS_ENABLED`, `REDIS_HOST`, `STORAGE_TYPE`, `S3_ENDPOINT`, `STORAGE_LOCAL_PATH`, `ENGINE_TYPE`, `PUPPETEER_HEADLESS`, `SESSION_DATA_PATH` and `PUPPETEER_ARGS` the host environment or the project `.env` sets. Those layers win over `data/.env.generated`, so a value saved for one of these keys through `PUT /api/infra/config` cannot take effect until that layer is changed. A pinned host also decides whether the bundled container backs its service, whatever `builtIn` is saved.
**Errors:** `401` missing/invalid key · `403` key role < ADMIN, or key is session-scoped
@@ -5781,7 +5781,7 @@ Request a graceful server restart, optionally orchestrating Docker profiles (add
}
```
-`estimatedTime` (seconds, a typical healthy value rather than a bound; teardown is force-exited 67 s after the grace at the default `WEBHOOK_SHUTDOWN_DRAIN_MS`) = base 15 + 20/postgres + 13/redis + 15/minio + 5/removal. The echoed `profilesToRemove`, and the removal count, already omit any bundled service the environment pins the app to (for example `DATABASE_HOST=postgres` set in the host environment or the project `.env`); such a service is never stopped. `orchestration` is present only when Docker is available and at least one managed profile (`postgres`, `redis`, `minio`) remains in `profiles`; `removal` only when Docker is available and at least one managed profile remains in `profilesToRemove` after dropping pinned services and profiles that are also being started. Without Docker, a `data/.orchestration-request.json` signal file is written instead. After responding, `shutdownService.shutdown()` runs (default ~3s grace); readiness returns `503` during drain.
+`estimatedTime` (seconds, a typical healthy value rather than a bound; teardown is force-exited 67 s after the grace at the default `WEBHOOK_SHUTDOWN_DRAIN_MS`) = base 15 + 20/postgres + 13/redis + 15/minio + 5/removal. The echoed `profilesToRemove`, and the removal count, already omit any bundled service the environment pins the app to (for example `DATABASE_HOST=postgres` set in the host environment or the project `.env`); such a service is never stopped. Likewise the echoed `profiles` omit a bundled service whose host the environment pins to anything else (for example `DATABASE_HOST=db.example.com`): the next boot dials that host, so its container is not started. `orchestration` is present only when Docker is available and at least one managed profile (`postgres`, `redis`, `minio`) remains in `profiles`; `removal` only when Docker is available and at least one managed profile remains in `profilesToRemove` after dropping pinned services and profiles that are also being started. Without Docker, a `data/.orchestration-request.json` signal file is written instead. After responding, `shutdownService.shutdown()` runs (default ~3s grace); readiness returns `503` during drain.
**Errors:** `401` · `403`
diff --git a/src/modules/infra/infra-config.controller.spec.ts b/src/modules/infra/infra-config.controller.spec.ts
index a7fd216c5..538e1e833 100644
--- a/src/modules/infra/infra-config.controller.spec.ts
+++ b/src/modules/infra/infra-config.controller.spec.ts
@@ -1784,6 +1784,58 @@ describe('InfraConfigController.requestRestart constrains teardown to managed pr
});
});
+ // The start side of the same rule: the host the environment pins outranks the saved file, so a bundled container
+ // started for a host pinned elsewhere would run with nothing dialling it.
+ describe('a bundled service whose host the environment pins elsewhere is never started', () => {
+ const PROFILE_OF: Record<ServiceName, string> = { database: 'postgres', redis: 'redis', storage: 'minio' };
+ let pinnedKeys: string[] = [];
+
+ afterEach(() => {
+ for (const key of pinnedKeys) delete process.env[key];
+ pinnedKeys = [];
+ recordPinnedEnvKeys({});
+ });
+
+ describe.each(SERVICE_NAMES)('%s', service => {
+ it.each(PIN_STATES)('host pinned %s', async pin => {
+ const host = pinnedHost(service, pin);
+ const key = SERVICES[service].host;
+ if (host !== undefined) {
+ process.env[key] = host;
+ pinnedKeys.push(key);
+ }
+ recordPinnedEnvKeys(host === undefined ? {} : { [key]: host });
+ const orchestrateProfiles = jest.fn().mockResolvedValue({});
+ const controller = buildController({
+ isDockerAvailable: () => true,
+ stopManagedService: jest.fn().mockResolvedValue(true),
+ orchestrateProfiles,
+ });
+
+ const result = await controller.requestRestart({ profiles: [PROFILE_OF[service]] });
+
+ const starts = pin !== 'external';
+ expect(orchestrateProfiles).toHaveBeenCalledTimes(starts ? 1 : 0);
+ expect(result.profiles).toEqual(starts ? [PROFILE_OF[service]] : []);
+ });
+ });
+
+ it('leaves it out of the no-Docker signal file too', async () => {
+ process.env.DATABASE_HOST = 'db.external.example';
+ pinnedKeys.push('DATABASE_HOST');
+ recordPinnedEnvKeys({ DATABASE_HOST: 'db.external.example' });
+ const writeFileSync = fs.writeFileSync as jest.Mock;
+ writeFileSync.mockClear();
+
+ await buildController({ isDockerAvailable: () => false }).requestRestart({ profiles: ['postgres', 'redis'] });
+
+ const written = (writeFileSync.mock.calls as Array<[unknown, unknown]>).find(call =>
+ String(call[0]).endsWith('.orchestration-request.json'),
+ );
+ expect((JSON.parse(String(written![1])) as { profiles: string[] }).profiles).toEqual(['redis']);
+ });
+ });
+
it('starts only allowlisted profiles, never an unknown entry (symmetry with teardown)', async () => {
const orchestrateProfiles = jest.fn().mockResolvedValue({});
const controller = buildController({
diff --git a/src/modules/infra/infra-config.controller.ts b/src/modules/infra/infra-config.controller.ts
index 98de01cb7..d80f9befd 100644
--- a/src/modules/infra/infra-config.controller.ts
+++ b/src/modules/infra/infra-config.controller.ts
@@ -439,7 +439,17 @@ export class InfraConfigController {
orchestration?: object;
removal?: object;
}> {
- const profiles = body?.profiles || [];
+ // Never start a bundled service whose host the environment pins elsewhere: the pin outranks the saved file, so
+ // the next boot dials the pinned host and the container would run with nothing using it.
+ const requestedStart = body?.profiles || [];
+ const pinnedElsewhere = requestedStart.filter(p => {
+ const [key, value] = BUNDLED_SERVICE_ENV[p] ?? [];
+ return key !== undefined && isEnvPinned(key) && process.env[key] !== value;
+ });
+ const profiles = requestedStart.filter(p => !pinnedElsewhere.includes(p));
+ if (pinnedElsewhere.length > 0) {
+ this.logger.warn('Not starting profiles whose host the environment pins elsewhere', { pinnedElsewhere });
+ }
// Never stop a bundled service the NEXT boot still dials, whatever the page asked for: the restarted
// app would point at a stopped container and fail to boot, with the dashboard that could undo it. The
// host it dials is the one the environment pins (e.g. the documented manual built-in Postgres with
diff --git a/src/modules/infra/infra-status.controller.spec.ts b/src/modules/infra/infra-status.controller.spec.ts
index cd9a37da4..5d6c7f127 100644
--- a/src/modules/infra/infra-status.controller.spec.ts
+++ b/src/modules/infra/infra-status.controller.spec.ts
@@ -287,6 +287,17 @@ describe('InfraStatusController.getStatus envPinned', () => {
]);
});
+ // A pinned host decides the Use Built-in mode of its service whatever the page saves.
+ it('reports the three datastore hosts when a shadowing layer supplies them', async () => {
+ recordPinnedEnvKeys({
+ DATABASE_HOST: 'db.example',
+ REDIS_HOST: 'cache.example',
+ S3_ENDPOINT: 'https://s3.example',
+ });
+
+ expect((await buildController().getStatus()).envPinned).toEqual(['DATABASE_HOST', 'REDIS_HOST', 'S3_ENDPOINT']);
+ });
+
it('reports an empty list when nothing above data/.env.generated supplies a selection key', async () => {
recordPinnedEnvKeys({});
diff --git a/src/modules/infra/infra-status.controller.ts b/src/modules/infra/infra-status.controller.ts
index fb3a6a976..3e1521e84 100644
--- a/src/modules/infra/infra-status.controller.ts
+++ b/src/modules/infra/infra-status.controller.ts
@@ -60,12 +60,16 @@ interface InfraStatus {
* The keys behind the Infrastructure page's editable controls that a shipped compose file or an
* operator variable is known to pin. docker-compose.dev.yml pins the local storage path and the three
* whatsapp-web.js launch options with non-empty defaults. Only page controls are reported: naming
- * variables the page cannot edit would be noise.
+ * variables the page cannot edit would be noise. A pinned host decides the Use Built-in mode of its
+ * service, so the three host keys are reported too.
*/
const DASHBOARD_PINNABLE_ENV_KEYS = [
'DATABASE_TYPE',
+ 'DATABASE_HOST',
'REDIS_ENABLED',
+ 'REDIS_HOST',
'STORAGE_TYPE',
+ 'S3_ENDPOINT',
'STORAGE_LOCAL_PATH',
'ENGINE_TYPE',
'PUPPETEER_HEADLESS',