Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(docker): start no bundled container for a host pinned elsewhere

Yudhi Armyndharis57f4927d4633
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index d3c69f712..cdde675a7 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -89,7 +89,7 @@ others.
#### Built-in PostgreSQL Orchestration
-When using PostgreSQL Built-in mode (`DATABASE_TYPE=postgres` with `POSTGRES_BUILTIN=true`), `main.ts` starts the managed `postgres` container (creating it if it does not exist) **before** `NestFactory.create`. It has to run that early: the `data` connection is opened while Nest instantiates providers, before any `onModuleInit` hook, so a stopped `openwa-postgres` would otherwise fail every boot. The step is bounded at 15 seconds and never fails boot on its own. `DockerService.onModuleInit()` later runs the same orchestration for `redis` / `minio` when their own `REDIS_BUILTIN` / `MINIO_BUILTIN` flags are set. A flag set for a datastore the configuration does not use starts nothing: `postgres` needs `DATABASE_TYPE=postgres`, `minio` needs `STORAGE_TYPE=s3`, and `redis` needs one of `REDIS_ENABLED`, `QUEUE_ENABLED` or `CACHE_ENABLED`.
+When using PostgreSQL Built-in mode (`DATABASE_TYPE=postgres` with `POSTGRES_BUILTIN=true`), `main.ts` starts the managed `postgres` container (creating it if it does not exist) **before** `NestFactory.create`. It has to run that early: the `data` connection is opened while Nest instantiates providers, before any `onModuleInit` hook, so a stopped `openwa-postgres` would otherwise fail every boot. The step is bounded at 15 seconds and never fails boot on its own. `DockerService.onModuleInit()` later runs the same orchestration for `redis` / `minio` when their own `REDIS_BUILTIN` / `MINIO_BUILTIN` flags are set. A flag set for a datastore the configuration does not use starts nothing: `postgres` needs `DATABASE_TYPE=postgres`, `minio` needs `STORAGE_TYPE=s3`, and `redis` needs one of `REDIS_ENABLED`, `QUEUE_ENABLED` or `CACHE_ENABLED`. Neither does one whose host the environment or the project `.env` pins to anything but the bundled container (`DATABASE_HOST`, `REDIS_HOST`, `S3_ENDPOINT`), the early PostgreSQL start included: the app dials the pinned host.
The container can still be coming up when the `data` connection first dials it, so that connection is configured with `retryAttempts: 10` and `retryDelay: 3000` (`src/app.module.ts`), giving the database roughly 30 seconds to become reachable.
diff --git a/src/modules/docker/docker.service.spec.ts b/src/modules/docker/docker.service.spec.ts
index 661763001..8c681e99c 100644
--- a/src/modules/docker/docker.service.spec.ts
+++ b/src/modules/docker/docker.service.spec.ts
@@ -1,5 +1,6 @@
import Docker from 'dockerode';
import { DockerService, prestartBuiltinDatabase } from './docker.service';
+import { recordPinnedEnvKeys } from '../../config/env-precedence';
// Prevent actual Docker connections on module init during tests
jest.mock('dockerode');
@@ -195,6 +196,9 @@ describe('DockerService.onModuleInit', () => {
'REDIS_ENABLED',
'QUEUE_ENABLED',
'CACHE_ENABLED',
+ 'DATABASE_HOST',
+ 'REDIS_HOST',
+ 'S3_ENDPOINT',
];
let savedEnv: Record<string, string | undefined> = {};
@@ -221,6 +225,7 @@ describe('DockerService.onModuleInit', () => {
if (savedEnv[k] === undefined) delete process.env[k];
else process.env[k] = savedEnv[k];
}
+ recordPinnedEnvKeys({});
DockerMock.mockReset();
});
@@ -295,6 +300,28 @@ describe('DockerService.onModuleInit', () => {
expect(await started(env)).toBe(false);
});
});
+
+ // The host the environment pins outranks the saved file at boot, so a bundled container started for a host pinned
+ // elsewhere would run with nothing dialling it. A pinned bundled host still starts it.
+ describe.each([
+ ['openwa-postgres', 'POSTGRES_BUILTIN', { DATABASE_TYPE: 'postgres' }, 'DATABASE_HOST', 'postgres'],
+ ['openwa-redis', 'REDIS_BUILTIN', { REDIS_ENABLED: 'true' }, 'REDIS_HOST', 'redis'],
+ ['openwa-minio', 'MINIO_BUILTIN', { STORAGE_TYPE: 's3' }, 'S3_ENDPOINT', 'http://minio:9000'],
+ ] as const)('%s with its host pinned', (container, flag, use, hostKey, bundled) => {
+ it.each([
+ [bundled, true],
+ ['external.example', false],
+ ])('to %s is started: %s', async (host, expected) => {
+ Object.assign(process.env, { [flag]: 'true', [hostKey]: host }, use);
+ recordPinnedEnvKeys({ [hostKey]: host });
+ const docker = happyDocker();
+ DockerMock.mockImplementation(() => docker);
+ await new DockerService().onModuleInit();
+
+ const names = docker.createContainer.mock.calls.map(([spec]) => (spec as { name: string }).name);
+ expect(names.includes(container)).toBe(expected);
+ });
+ });
});
describe('prestartBuiltinDatabase', () => {
@@ -334,6 +361,20 @@ describe('prestartBuiltinDatabase', () => {
expect(service.startBuiltinDatabase).not.toHaveBeenCalled();
});
+ it.each([
+ ['postgres', 1],
+ ['db.external.example', 0],
+ ])('with DATABASE_HOST pinned to %s starts the container %i times', async (host, calls) => {
+ recordPinnedEnvKeys({ DATABASE_HOST: host });
+ const service = { startBuiltinDatabase: jest.fn().mockResolvedValue(undefined) };
+ try {
+ await prestartBuiltinDatabase({ ...builtin, DATABASE_HOST: host }, service);
+ } finally {
+ recordPinnedEnvKeys({});
+ }
+ expect(service.startBuiltinDatabase).toHaveBeenCalledTimes(calls);
+ });
+
it('gives up after the timeout when the Docker endpoint never answers', async () => {
const service = { startBuiltinDatabase: () => new Promise<void>(() => undefined) };
await expect(prestartBuiltinDatabase(builtin, service, 10)).resolves.toBeUndefined();
diff --git a/src/modules/docker/docker.service.ts b/src/modules/docker/docker.service.ts
index 1dc9d8d56..a9825636d 100644
--- a/src/modules/docker/docker.service.ts
+++ b/src/modules/docker/docker.service.ts
@@ -20,6 +20,22 @@ export function datastoreInUse(profile: string, read: (key: string) => string |
return ['REDIS_ENABLED', 'QUEUE_ENABLED', 'CACHE_ENABLED'].some(key => read(key) === 'true');
}
+/** The env key and value that point the app at each managed profile's bundled container. */
+export const BUNDLED_SERVICE_ENV: Record<string, [string, string]> = {
+ postgres: ['DATABASE_HOST', 'postgres'],
+ redis: ['REDIS_HOST', 'redis'],
+ minio: ['S3_ENDPOINT', 'http://minio:9000'],
+};
+
+/**
+ * Whether the environment (or the project .env) pins the profile's host to anything but its bundled container. The
+ * pin outranks the saved file at every boot, so a container started for that profile would run with nothing using it.
+ */
+export function hostPinnedElsewhere(profile: string, env: NodeJS.ProcessEnv = process.env): boolean {
+ const [key, value] = BUNDLED_SERVICE_ENV[profile] ?? [];
+ return key !== undefined && isEnvPinned(key) && env[key] !== value;
+}
+
interface ContainerInfo {
id: string;
name: string;
@@ -95,7 +111,8 @@ export class DockerService implements OnModuleInit {
* Runs from onModuleInit, which Nest calls only after the data connection is up. When that
* connection is the built-in database (DATABASE_TYPE=postgres), the postgres profile is a no-op
* here: a stopped container was already started by prestartBuiltinDatabase in main.ts. A flag set
- * for a datastore this boot does not use (see datastoreInUse) starts nothing.
+ * for a datastore this boot does not use (see datastoreInUse), or whose host the environment pins
+ * elsewhere, starts nothing.
*/
private async bootstrapOrchestration(): Promise<void> {
if (!this.isAvailable) {
@@ -103,19 +120,16 @@ export class DockerService implements OnModuleInit {
return;
}
- const profiles: string[] = [];
const env = (key: string): string | undefined => process.env[key];
+ const wanted = (profile: string, flag: string | undefined): boolean =>
+ flag === 'true' && datastoreInUse(profile, env) && !hostPinnedElsewhere(profile);
// Check for built-in services from environment variables
- if (process.env.REDIS_BUILTIN === 'true' && datastoreInUse('redis', env)) {
- profiles.push('redis');
- }
- if (process.env.POSTGRES_BUILTIN === 'true' && datastoreInUse('postgres', env)) {
- profiles.push('postgres');
- }
- if (process.env.MINIO_BUILTIN === 'true' && datastoreInUse('minio', env)) {
- profiles.push('minio');
- }
+ const profiles = [
+ wanted('redis', process.env.REDIS_BUILTIN) && 'redis',
+ wanted('postgres', process.env.POSTGRES_BUILTIN) && 'postgres',
+ wanted('minio', process.env.MINIO_BUILTIN) && 'minio',
+ ].filter((p): p is string => typeof p === 'string');
if (profiles.length === 0) {
this.logger.log('[Bootstrap Orchestration] No built-in services configured');
@@ -701,7 +715,8 @@ export async function prestartBuiltinDatabase(
service: Pick<DockerService, 'startBuiltinDatabase'> = new DockerService(),
timeoutMs = 15_000,
): Promise<void> {
- if (env.DATABASE_TYPE !== 'postgres' || env.POSTGRES_BUILTIN !== 'true') return;
+ if (env.DATABASE_TYPE !== 'postgres' || env.POSTGRES_BUILTIN !== 'true' || hostPinnedElsewhere('postgres', env))
+ return;
const logger = createLogger('DockerService');
let timer: NodeJS.Timeout | undefined;
const deadline = new Promise<void>(resolve => {
diff --git a/src/modules/infra/infra-config.controller.ts b/src/modules/infra/infra-config.controller.ts
index d80f9befd..6025c4b8d 100644
--- a/src/modules/infra/infra-config.controller.ts
+++ b/src/modules/infra/infra-config.controller.ts
@@ -17,7 +17,7 @@ import { RequireRole, RequireUnscopedKey } from '../auth/decorators/auth.decorat
import { ApiKeyRole } from '../auth/entities/api-key.entity';
import { writeSecretFile } from '../../common/utils/secret-file';
import { EngineFactory } from '../../engine/engine.factory';
-import { DockerService, MANAGED_DOCKER_PROFILES } from '../docker';
+import { BUNDLED_SERVICE_ENV, DockerService, MANAGED_DOCKER_PROFILES, hostPinnedElsewhere } from '../docker';
import { ShutdownService } from '../../common/services/shutdown.service';
import { createLogger } from '../../common/services/logger.service';
import { AuditService } from '../audit/audit.service';
@@ -45,13 +45,6 @@ import {
// boolean/numeric fields carry the @ToStrictBoolean / @ToStrictNumber transforms that keep a form-encoded
// 'false' from being coerced to `true`.
-// The env key and value that point the app at each bundled service, as /infra/status detects them.
-const BUNDLED_SERVICE_ENV: Record<string, [string, string]> = {
- postgres: ['DATABASE_HOST', 'postgres'],
- redis: ['REDIS_HOST', 'redis'],
- minio: ['S3_ENDPOINT', 'http://minio:9000'],
-};
-
// Saved infrastructure config returned to the dashboard form for hydration. Secret
// values are never echoed back — a `*Set` boolean indicates whether one is stored.
interface SavedConfigResponse {
@@ -442,10 +435,7 @@ export class InfraConfigController {
// 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 pinnedElsewhere = requestedStart.filter(p => hostPinnedElsewhere(p));
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 });