Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(docker): start the built-in PostgreSQL container before Nest boots
Yudhi Armyndharis389084e7918c
diff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex f02ef339c..aba3202a2 100644--- a/docs/05-database-design.md+++ b/docs/05-database-design.md@@ -79,12 +79,12 @@ The main DB is unconditionally SQLite, but its _path_ is not fixed: `MAIN_DATABA#### Built-in PostgreSQL Orchestration-When using PostgreSQL Built-in mode (`POSTGRES_BUILTIN=true`), `DockerService.onModuleInit()` runs a bootstrap orchestration that starts the managed `postgres` container (alongside `redis` / `minio` when their own `REDIS_BUILTIN` / `MINIO_BUILTIN` flags are set). This happens **during** Nest module initialization, not before it — there is no pre-bootstrap step in `main.ts`.+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.-Because the container can therefore still be coming up when the `data` connection first dials it, that connection is configured with `retryAttempts: 10` and `retryDelay: 3000` (`src/app.module.ts`), giving the database roughly 30 seconds to become reachable.+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.> [!NOTE]-> If the Docker API is unreachable, orchestration logs a warning and is skipped — no container is started, and the `data` connection then fails its retries against whatever `DATABASE_HOST` points at.+> If the Docker API is unreachable, the start is skipped with a warning: no container is started, and the `data` connection then fails its retries against whatever `DATABASE_HOST` points at. Start the container by hand (`docker start openwa-postgres`) and restart OpenWA.#### PostgreSQL Schema Selectiondiff --git a/src/main.ts b/src/main.tsindex 495dfde47..ecb1c6248 100644--- a/src/main.ts+++ b/src/main.ts@@ -28,6 +28,7 @@ import { AuthService } from './modules/auth/auth.service';import { AuditService } from './modules/audit/audit.service';import { Request, Response, NextFunction } from 'express';import { RedisIoAdapter } from './modules/events/redis-io.adapter';+import { prestartBuiltinDatabase } from './modules/docker/docker.service';// The created app, exposed at module scope so the fatal handler below can run a best-effort teardown// (engine sessions, Redis/pg) when bootstrap fails AFTER NestFactory.create succeeded — notably a@@ -102,6 +103,10 @@ async function bootstrap() {logger: bootstrapLogger,});+ // The data connection dials PostgreSQL inside NestFactory.create, so a stopped built-in container+ // must be started before it, not from DockerService.onModuleInit (see the helper).+ await prestartBuiltinDatabase();+// Disable Nest's default body parser so we can set an explicit size cap below.const app = await NestFactory.create(AppModule, { bodyParser: false });appInstance = app;diff --git a/src/modules/docker/builtin-database-prestart-order.spec.ts b/src/modules/docker/builtin-database-prestart-order.spec.tsnew file mode 100644index 000000000..c46f4d5ec--- /dev/null+++ b/src/modules/docker/builtin-database-prestart-order.spec.ts@@ -0,0 +1,32 @@+import * as fs from 'fs';+import * as path from 'path';++/**+ * The data connection dials PostgreSQL inside NestFactory.create, so a stopped built-in database has+ * to be started before that call or the boot crash-loops. The helper's own tests cannot see where+ * main.ts calls it: deleting the call, dropping its `await`, or moving it after NestFactory.create+ * would leave them green. This spec pins the order in main.ts.+ */++function prestartPrecedesCreate(mainSrc: string): boolean {+ const prestart = mainSrc.search(/^\s*await prestartBuiltinDatabase\(\);/m);+ const create = mainSrc.search(/await NestFactory\.create\(/);+ return prestart !== -1 && create !== -1 && prestart < create;+}++describe('built-in database prestart order in main.ts', () => {+ const mainSrc = fs.readFileSync(path.join(__dirname, '..', '..', 'main.ts'), 'utf8');++ it('awaits prestartBuiltinDatabase before NestFactory.create', () => {+ expect(prestartPrecedesCreate(mainSrc)).toBe(true);+ });++ it('the check fails when the call is missing, not awaited, or after create', () => {+ const create = 'const app = await NestFactory.create(AppModule);';+ expect(prestartPrecedesCreate(` await prestartBuiltinDatabase();\n ${create}`)).toBe(true);+ expect(prestartPrecedesCreate(` ${create}`)).toBe(false);+ expect(prestartPrecedesCreate(` void prestartBuiltinDatabase();\n ${create}`)).toBe(false);+ expect(prestartPrecedesCreate(` // await prestartBuiltinDatabase();\n ${create}`)).toBe(false);+ expect(prestartPrecedesCreate(` ${create}\n await prestartBuiltinDatabase();`)).toBe(false);+ });+});diff --git a/src/modules/docker/docker.service.spec.ts b/src/modules/docker/docker.service.spec.tsindex 88011a2da..0d5225e4e 100644--- a/src/modules/docker/docker.service.spec.ts+++ b/src/modules/docker/docker.service.spec.ts@@ -1,5 +1,5 @@import Docker from 'dockerode';-import { DockerService } from './docker.service';+import { DockerService, prestartBuiltinDatabase } from './docker.service';// Prevent actual Docker connections on module init during testsjest.mock('dockerode');@@ -243,6 +243,53 @@ describe('DockerService.onModuleInit', () => {});});+describe('prestartBuiltinDatabase', () => {+ const builtin = { DATABASE_TYPE: 'postgres', POSTGRES_BUILTIN: 'true' };++ afterEach(() => DockerMock.mockReset());++ it('starts a stopped built-in postgres container through a real DockerService', async () => {+ const container = {+ inspect: jest.fn().mockResolvedValue({ State: { Running: false } }),+ start: jest.fn().mockResolvedValue(undefined),+ };+ const docker = {+ ping: jest.fn().mockResolvedValue(undefined),+ listContainers: jest.fn().mockResolvedValue([{ Id: 'pg' }]),+ getContainer: jest.fn().mockReturnValue(container),+ };+ DockerMock.mockImplementation(() => docker);++ await prestartBuiltinDatabase(builtin, new DockerService());++ expect(docker.listContainers).toHaveBeenCalledWith({+ all: true,+ filters: { label: ['com.openwa.service=database'] },+ });+ expect(container.start).toHaveBeenCalledTimes(1);+ });++ it.each([+ ['an sqlite deployment', { DATABASE_TYPE: 'sqlite', POSTGRES_BUILTIN: 'true' }],+ ['an external postgres', { DATABASE_TYPE: 'postgres', POSTGRES_BUILTIN: 'false' }],+ ['no built-in flag', { DATABASE_TYPE: 'postgres' }],+ ])('does nothing for %s', async (_label, env) => {+ const service = { startBuiltinDatabase: jest.fn().mockResolvedValue(undefined) };+ await prestartBuiltinDatabase(env, service);+ expect(service.startBuiltinDatabase).not.toHaveBeenCalled();+ });++ 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();+ });++ it('never throws, so boot proceeds to the data connection as before', async () => {+ const service = { startBuiltinDatabase: jest.fn().mockRejectedValue(new Error('boom')) };+ await expect(prestartBuiltinDatabase(builtin, service)).resolves.toBeUndefined();+ });+});+describe('DockerService.isDockerAvailable', () => {const originalDockerHost = process.env.DOCKER_HOST;diff --git a/src/modules/docker/docker.service.ts b/src/modules/docker/docker.service.tsindex 8640d72de..d65dc0e6e 100644--- a/src/modules/docker/docker.service.ts+++ b/src/modules/docker/docker.service.ts@@ -38,8 +38,11 @@ export class DockerService implements OnModuleInit {}/**- * Bootstrap orchestration: start built-in containers based on saved config- * This runs on application startup to ensure containers match saved configuration+ * Bootstrap orchestration: start built-in containers based on saved config.+ * 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. With+ * POSTGRES_BUILTIN=true on any other DATABASE_TYPE, this is what starts or creates it.*/private async bootstrapOrchestration(): Promise<void> {if (!this.isAvailable) {@@ -75,6 +78,12 @@ export class DockerService implements OnModuleInit {}}+ /** Start the built-in PostgreSQL container, creating it if absent. Never throws. */+ async startBuiltinDatabase(): Promise<void> {+ await this.initializeDocker();+ if (this.isAvailable) await this.startService('database');+ }+private async initializeDocker(): Promise<void> {try {this.docker = new Docker(this.buildDockerOptions());@@ -608,3 +617,33 @@ export class DockerService implements OnModuleInit {}}}++/**+ * Start the built-in PostgreSQL container before Nest builds the module graph. The data connection+ * dials the database while providers are instantiated, before any onModuleInit runs, so a stopped+ * openwa-postgres would otherwise fail every boot before DockerService could start it. Bounded+ * because dockerode sets no connect timeout; never throws, so on any failure boot proceeds as it+ * would without it and the data connection's retries decide.+ */+export async function prestartBuiltinDatabase(+ env: NodeJS.ProcessEnv = process.env,+ service: Pick<DockerService, 'startBuiltinDatabase'> = new DockerService(),+ timeoutMs = 15_000,+): Promise<void> {+ if (env.DATABASE_TYPE !== 'postgres' || env.POSTGRES_BUILTIN !== 'true') return;+ const logger = new Logger('DockerService');+ let timer: NodeJS.Timeout | undefined;+ const deadline = new Promise<void>(resolve => {+ timer = setTimeout(() => {+ logger.warn(`Built-in PostgreSQL start did not finish within ${timeoutMs}ms; continuing boot`);+ resolve();+ }, timeoutMs);+ });+ try {+ await Promise.race([service.startBuiltinDatabase(), deadline]);+ } catch (error) {+ logger.warn(`Could not start built-in PostgreSQL: ${error instanceof Error ? error.message : String(error)}`);+ } finally {+ clearTimeout(timer);+ }+}