Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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 Selection
diff --git a/src/main.ts b/src/main.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 tests
jest.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.ts
index 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);
+ }
+}