Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { Injectable, OnModuleInit } from '@nestjs/common';
import { createLogger } from '../../common/services/logger.service';
import Docker from 'dockerode';
import { isEnvPinned, isOsProvidedEnv } from '../../config/env-precedence';
import { readGeneratedEnv } from '../infra/generated-env';
import { BUNDLED_SERVICE_ENV, namesBundledContainer } from './bundled-host';
/**
* The only Docker profiles OpenWA manages (and may start/stop). Used to bound teardown so a
* caller-supplied profile name can never reach stopManagedService for an unrelated container.
*/
export const MANAGED_DOCKER_PROFILES: readonly string[] = ['postgres', 'redis', 'minio'];
/**
* Whether the configuration `read` describes uses the datastore a managed profile runs. Redis is reached by the
* queue and the cache as well as by REDIS_ENABLED, each of which connects on its own.
*/
export function datastoreInUse(profile: string, read: (key: string) => string | undefined): boolean {
if (profile === 'postgres') return read('DATABASE_TYPE') === 'postgres';
if (profile === 'minio') return read('STORAGE_TYPE') === 's3';
return ['REDIS_ENABLED', 'QUEUE_ENABLED', 'CACHE_ENABLED'].some(key => read(key) === 'true');
}
/**
* Whether the environment (or the project .env) pins the profile's host to anything but its bundled container, in
* any spelling namesBundledContainer accepts. 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] = BUNDLED_SERVICE_ENV[profile] ?? [];
return key !== undefined && isEnvPinned(key) && !namesBundledContainer(profile, env[key]);
}
interface ContainerInfo {
id: string;
name: string;
state: string;
status: string;
labels: Record<string, string>;
}
interface OrchestrationResult {
success: boolean;
message: string;
containersStarted: string[];
containersStopped: string[];
errors: string[];
estimatedTime: number; // Estimated restart time in seconds
}
/** How long a reachability or listing call may take before the daemon is read as unavailable. */
const DOCKER_CALL_TIMEOUT_MS = 10_000;
@Injectable()
export class DockerService implements OnModuleInit {
private readonly logger = createLogger(DockerService.name);
private docker: Docker | null = null;
private isAvailable = false;
/** Whether a daemon has ever answered, so a later loss is a reconnect and not a deployment without Docker. */
private hasConnected = false;
private reinitInFlight = false;
/** Visible for testing. */
callTimeoutMs = DOCKER_CALL_TIMEOUT_MS;
/**
* dockerode sets no timeout, so a daemon or socket proxy that accepts the connection and never
* answers (a dropped SYN, a wedged upstream) would hold the caller, boot included, until the OS or
* the proxy gave up. Short calls are bounded here; image pulls and container starts are not.
*
* The call is aborted when the deadline passes, not only raced: a call left running keeps its request
* and its socket open, and every later availability check would add one more.
*/
private async answered<T>(call: (signal: AbortSignal) => Promise<T>, what: string): Promise<T> {
const controller = new AbortController();
let timer: NodeJS.Timeout | undefined;
const deadline = new Promise<never>((_, reject) => {
timer = setTimeout(() => {
reject(new Error(`Docker did not answer ${what} within ${this.callTimeoutMs}ms`));
controller.abort();
}, this.callTimeoutMs);
});
try {
return await Promise.race([call(controller.signal), deadline]);
} finally {
clearTimeout(timer);
}
}
/**
* dockerode's runtime takes an options object with `abortSignal` on every call, which its typings
* declare only for some of them.
*/
private abortable<T>(method: 'ping', abortSignal: AbortSignal): Promise<T> {
const call = this.docker![method].bind(this.docker) as unknown as (options: {
abortSignal: AbortSignal;
}) => Promise<T>;
return call({ abortSignal });
}
async onModuleInit() {
await this.initializeDocker();
// Bootstrap orchestration: start containers based on saved config
await this.bootstrapOrchestration();
}
/**
* 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. A flag set
* 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) {
this.logger.log('[Bootstrap Orchestration] Docker not available, skipping');
return;
}
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
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');
return;
}
this.logger.log(`[Bootstrap Orchestration] Starting built-in services: ${profiles.join(', ')}`);
const result = await this.orchestrateProfiles(profiles);
if (result.success) {
this.logger.log(`[Bootstrap Orchestration] Started ${result.containersStarted.length} container(s)`);
} else {
this.logger.warn(`[Bootstrap Orchestration] Issues: ${result.errors.join('; ')}`);
}
}
/** 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());
await this.answered(abortSignal => this.abortable<unknown>('ping', abortSignal), 'a ping');
this.isAvailable = true;
this.hasConnected = true;
this.logger.log('Docker API connected successfully');
} catch (error) {
this.logger.warn('Docker not available. Container orchestration disabled.', {
error: error instanceof Error ? error.message : String(error),
});
this.isAvailable = false;
}
}
// Visible for testing
buildDockerOptions(): Docker.DockerOptions {
const dockerHost = process.env.DOCKER_HOST;
if (dockerHost) {
const match = /^tcp:\/\/([^:]+):(\d+)$/.exec(dockerHost);
if (match) {
return { host: match[1], port: parseInt(match[2], 10), protocol: 'http' };
}
}
return { socketPath: '/var/run/docker.sock' };
}
/**
* Check if Docker is available.
*
* Startup-race recovery: when the API talks to the Docker socket-proxy over TCP
* (DOCKER_HOST=tcp://...), the proxy container may not be accepting connections at
* the moment onModuleInit runs (compose `service_started` doesn't wait for readiness).
* If the first connect failed, retry it once in the background here so orchestration
* recovers without a process restart. Only for the DOCKER_HOST (proxy/tcp) case or a daemon
* that answered before: a docker-less deployment has no such race. Built-in services the boot
* skipped while Docker was unreachable are started once it answers.
*/
isDockerAvailable(): boolean {
if (!this.isAvailable && !this.reinitInFlight && (process.env.DOCKER_HOST || this.hasConnected)) {
this.reinitInFlight = true;
void this.initializeDocker()
.then(() => this.bootstrapOrchestration())
.catch(error => this.logger.warn('Could not start built-in services after Docker recovery', String(error)))
.finally(() => {
this.reinitInFlight = false;
});
}
return this.isAvailable;
}
/**
* List all OpenWA-related containers, or null when the daemon could not be asked: an empty list
* means it was asked and none exist, which callers act on.
*/
async listContainers(): Promise<ContainerInfo[] | null> {
if (!this.docker || !this.isAvailable) {
return null;
}
try {
const containers = await this.answered(
abortSignal => this.docker!.listContainers({ all: true, abortSignal }),
'a container list',
);
return containers
.filter(c => {
// Filter by OpenWA labels or name prefix
const labels = c.Labels || {};
return labels['com.openwa.service'] || c.Names?.some(n => n.startsWith('/openwa-'));
})
.map(c => ({
id: c.Id.substring(0, 12),
name: c.Names?.[0]?.replace(/^\//, '') || 'unknown',
state: c.State || 'unknown',
status: c.Status || 'unknown',
labels: c.Labels || {},
}));
} catch (error) {
this.logger.error('Failed to list containers', error);
this.isAvailable = false;
return null;
}
}
/**
* Which bundled (OpenWA-managed) service containers are currently RUNNING, keyed by the
* `com.openwa.service` label (`database` | `cache` | `storage`), and who created each: `'compose'` for one
* Docker Compose created (it carries Compose's project label and belongs to the deployment), `'openwa'` for
* one createService made. Lets the dashboard show the real built-in state instead of the saved intent. All
* false when none run; null when Docker could not be observed.
*/
async getRunningBuiltinServices(): Promise<Record<
'database' | 'cache' | 'storage',
false | 'compose' | 'openwa'
> | null> {
const containers = await this.listContainers();
if (containers === null) return null;
const creator = (svc: string): false | 'compose' | 'openwa' => {
const running = containers.find(
c =>
c.labels['com.openwa.service'] === svc && c.labels['com.openwa.builtin'] === 'true' && c.state === 'running',
);
if (!running) return false;
return running.labels['com.docker.compose.project'] ? 'compose' : 'openwa';
};
return { database: creator('database'), cache: creator('cache'), storage: creator('storage') };
}
/**
* Get container by service name or label
*/
async getContainerByService(service: string): Promise<Docker.Container | null> {
if (!this.docker || !this.isAvailable) {
return null;
}
try {
const containers = await this.answered(
abortSignal =>
this.docker!.listContainers({
all: true,
filters: {
label: [`com.openwa.service=${service}`],
},
abortSignal,
}),
'a container list',
);
if (containers.length > 0) {
return this.docker.getContainer(containers[0].Id);
}
// Fallback: try by EXACT name (never a substring — a substring, and especially the empty
// string, would resolve an arbitrary container). OpenWA-managed containers are `openwa-<service>`.
const target = `openwa-${service}`;
const allContainers = await this.answered(
abortSignal => this.docker!.listContainers({ all: true, abortSignal }),
'a container list',
);
const match = allContainers.find(c => c.Names?.some(n => n === target || n === `/${target}`));
if (match) {
return this.docker.getContainer(match.Id);
}
return null;
} catch (error) {
this.logger.error(`Failed to get container for service: ${service}`, error);
return null;
}
}
/**
* Container specifications for the three managed profiles, kept in parity with the matching
* services in docker-compose.yml (same image pin, container/volume/network names, command,
* healthcheck, labels, restart policy, no-new-privileges). compose-parity.spec.ts is the
* regression lock: it reads docker-compose.yml and fails when either side drifts.
*
* Deliberate differences from the compose services — do not "fix" these:
* - Credentials: the compose services are the MANUAL operator path and deliberately ship no
* default secret (an empty POSTGRES_PASSWORD fails when the volume is first initialized; a
* MINIO_ROOT_PASSWORD left on its sub-minimum placeholder fails at every start). The specs below
* are the dashboard built-in path: they provision the built-in credentials, by default
* (openwa/openwa, minioadmin/minioadmin), that infra-config.controller writes to data/.env.generated
* and that the production boot guard (bootstrap-security.ts) exempts only while the
* *_BUILTIN flag is set AND the datastore host resolves to the internal-only container.
* - Postgres init script: compose bind-mounts scripts/postgres-init-schema.sh from the host
* checkout to support a custom POSTGRES_SCHEMA. The Docker-API path cannot know a host path
* to mount, and the built-in flow always pins POSTGRES_SCHEMA=public, so no init script (or
* POSTGRES_SCHEMA env) is set here.
* - Host ports: compose's minio (the manual path, operator-set credentials) publishes
* 127.0.0.1:9000/9001. The specs below publish nothing, like postgres and redis: they run the
* fixed built-in credentials, which the boot guard exempts only because the container is
* reachable on the internal network alone. The app reaches it by its `minio` alias.
* - Resource limits: neither path sets CPU/memory/PID limits on the datastore containers;
* only openwa-api carries mem_limit/pids_limit (in compose).
*/
private getContainerSpec(profile: string): {
image: string;
name: string;
alias: string; // DNS alias for network resolution
env?: string[];
cmd?: string[];
volumes?: { name: string; path: string }[];
healthcheck?: { test: string[]; interval: number; timeout: number; retries: number };
labels: Record<string, string>;
securityOpt: string[];
} | null {
// A container outlives the process that creates it, and after a dashboard save the restart that
// creates it runs in the OLD process, whose env still holds the values the save just replaced.
// Resolve what the next boot reads instead: a host or project .env value pins, the saved file
// supplies the rest. With no boot snapshot (unit tests) process.env is the only source there is.
let saved: Record<string, string> | undefined;
const nextBoot = (key: string): string | undefined =>
isEnvPinned(key) || isOsProvidedEnv(key) ? process.env[key] : (saved ??= readGeneratedEnv())[key];
const specs: Record<string, ReturnType<typeof this.getContainerSpec>> = {
redis: {
image: 'redis:7-alpine',
name: 'openwa-redis',
alias: 'redis', // DNS alias for resolution
// noeviction mirrors docker-compose.yml: BullMQ requires it, or Redis may evict queue keys
// once maxmemory is reached and silently drop queued jobs.
cmd: ['redis-server', '--appendonly', 'yes', '--maxmemory-policy', 'noeviction'],
volumes: [{ name: 'openwa_redis-data', path: '/data' }],
healthcheck: {
test: ['CMD', 'redis-cli', 'ping'],
interval: 5000000000, // 5s in nanoseconds
timeout: 3000000000,
retries: 5,
},
labels: {
'com.openwa.service': 'cache',
'com.openwa.builtin': 'true',
},
securityOpt: ['no-new-privileges:true'],
},
postgres: {
image: 'postgres:16-alpine',
name: 'openwa-postgres',
alias: 'postgres',
// The built-in credentials — the dashboard saves them to data/.env.generated
// (infra-config.controller) and the production boot guard exempts the default pair only for the
// built-in, internal-host deployment (see the getContainerSpec docblock). The password is the
// one the next boot dials with, like the MinIO keys below: a custom one saved with the built-in
// database would otherwise never match the role this container initializes, and the app would
// exit on its first connection.
env: [
'POSTGRES_USER=openwa',
`POSTGRES_PASSWORD=${nextBoot('DATABASE_PASSWORD') || 'openwa'}`,
'POSTGRES_DB=openwa',
],
volumes: [{ name: 'openwa_postgres-data', path: '/var/lib/postgresql/data' }],
healthcheck: {
test: ['CMD-SHELL', 'pg_isready -U openwa'],
interval: 5000000000,
timeout: 3000000000,
retries: 5,
},
labels: {
'com.openwa.service': 'database',
'com.openwa.builtin': 'true',
},
securityOpt: ['no-new-privileges:true'],
},
minio: {
// Same pin (release tag and digest) as the compose minio service; never a floating tag.
image:
'pgsty/silo:RELEASE.2026-09-16T00-00-00Z@sha256:635197cb9f36d01bee221d34d1c7d7960f6a95c48b0b6c01d99cd13bdae51a46',
name: 'openwa-minio',
alias: 'minio',
cmd: ['server', '/data', '--console-address', ':9001'],
env: [
// Prefer the canonical names the app/dashboard use; fall back to the legacy ones, then the
// built-in default, so the bundled MinIO and the app share credentials.
`MINIO_ROOT_USER=${nextBoot('S3_ACCESS_KEY_ID') || nextBoot('S3_ACCESS_KEY') || 'minioadmin'}`,
`MINIO_ROOT_PASSWORD=${nextBoot('S3_SECRET_ACCESS_KEY') || nextBoot('S3_SECRET_KEY') || 'minioadmin'}`,
],
volumes: [{ name: 'openwa_minio-data', path: '/data' }],
healthcheck: {
test: ['CMD', 'curl', '-f', 'http://localhost:9000/minio/health/live'],
interval: 10000000000,
timeout: 5000000000,
retries: 3,
},
labels: {
'com.openwa.service': 'storage',
'com.openwa.builtin': 'true',
},
securityOpt: ['no-new-privileges:true'],
},
};
return specs[profile] || null;
}
/**
* Create and start a service using Docker API directly
*/
async createService(profile: string): Promise<boolean> {
if (!this.docker || !this.isAvailable) {
this.logger.error('Docker not available for creating service');
return false;
}
const spec = this.getContainerSpec(profile);
if (!spec) {
this.logger.error(`Unknown profile: ${profile}`);
return false;
}
this.logger.log(`Creating service: ${profile} (image: ${spec.image})`);
try {
// Check if container already exists
const existing = await this.getContainerByService(profile);
if (existing) {
const info = await this.answered(abortSignal => existing.inspect({ abortSignal }), 'a container inspection');
this.warnOnImageDrift(profile, spec.name, info);
if (info.State.Running) {
this.logger.log(`Container ${spec.name} already running`);
return true;
}
// Start existing container
await existing.start();
this.logger.log(`Started existing container: ${spec.name}`);
return true;
}
// Pull only when the image is not already on the host, as compose's default
// `pull_policy: missing` does: a host that has the image keeps working when the registry is
// unreachable or has withdrawn it. As with compose, a cached floating tag is not refreshed
// here. Only an answer that the image is absent pulls: a daemon that fails or does not answer the
// inspection could not complete a pull either, and the pull itself is not bounded.
const cached = await this.answered(abortSignal => {
const image = Object.create(this.docker!.getImage(spec.image)) as Docker.Image;
const modem = this.docker!.modem;
// Dockerode 5 leaves the signal out of an image inspection; forward it without changing the shared modem.
const imageModem = Object.create(modem) as Docker['modem'];
image.modem = imageModem;
imageModem.dial = (
options: Parameters<Docker['modem']['dial']>[0],
callback: Parameters<Docker['modem']['dial']>[1],
) => modem.dial({ ...options, abortSignal }, callback);
return image.inspect({ abortSignal } as Docker.ImageInspectOptions);
}, 'an image inspection').then(
() => true,
(error: unknown) => {
if ((error as { statusCode?: number } | null)?.statusCode !== 404) throw error;
return false;
},
);
if (!cached) {
this.logger.log(`Pulling image: ${spec.image}`);
await new Promise<void>((resolve, reject) => {
void this.docker!.pull(spec.image, (err: Error | null, stream: NodeJS.ReadableStream) => {
if (err) return reject(err);
this.docker!.modem.followProgress(stream, (err2: Error | null) => {
if (err2) return reject(err2);
resolve();
});
});
});
}
// Create volume if needed
if (spec.volumes) {
for (const vol of spec.volumes) {
try {
await this.docker.createVolume({ Name: vol.name });
this.logger.log(`Created volume: ${vol.name}`);
} catch (error) {
this.logger.debug(`Volume ${vol.name} creation skipped (may already exist)`, { error: String(error) });
}
}
}
// Create container
const containerConfig: Docker.ContainerCreateOptions = {
name: spec.name,
Image: spec.image,
Cmd: spec.cmd,
Env: spec.env,
Labels: spec.labels,
HostConfig: {
NetworkMode: 'openwa-network',
RestartPolicy: { Name: 'unless-stopped' },
Binds: spec.volumes?.map(v => `${v.name}:${v.path}`),
SecurityOpt: spec.securityOpt,
},
Healthcheck: spec.healthcheck
? {
Test: spec.healthcheck.test,
Interval: spec.healthcheck.interval,
Timeout: spec.healthcheck.timeout,
Retries: spec.healthcheck.retries,
}
: undefined,
NetworkingConfig: {
EndpointsConfig: {
'openwa-network': {
Aliases: [spec.alias, profile], // Add DNS aliases for network resolution
},
},
},
};
const container = await this.docker.createContainer(containerConfig);
await container.start();
this.logger.log(`Created and started container: ${spec.name}`);
return true;
} catch (error) {
this.logger.error(
`Failed to create service ${profile}: ${error instanceof Error ? error.message : String(error)}`,
);
return false;
}
}
/**
* Start a container by service name - creates if not exists
*/
async startService(service: string): Promise<boolean> {
const container = await this.getContainerByService(service);
// Map service names to docker-compose profiles
const serviceToProfile: Record<string, string> = {
database: 'postgres',
cache: 'redis',
storage: 'minio',
postgres: 'postgres',
redis: 'redis',
minio: 'minio',
};
const profile = serviceToProfile[service] || service;
if (!container) {
// Container doesn't exist - create it from the managed spec
this.logger.log(`Container for service '${service}' not found, creating...`);
return this.createService(profile);
}
try {
const info = await this.answered(abortSignal => container.inspect({ abortSignal }), 'a container inspection');
this.warnOnImageDrift(profile, info.Name?.replace(/^\//, '') || service, info);
if (info.State.Running) {
this.logger.log(`Service '${service}' is already running`);
return true;
}
await container.start();
this.logger.log(`Started service: ${service}`);
return true;
} catch (error) {
this.logger.error(`Failed to start service: ${service}`, error);
return false;
}
}
/**
* A retained container is only ever restarted, never recreated (see stopManagedService), so it
* keeps the image it was created from after the pin moves. Warn with the way out; start and stop
* behaviour stay as they are.
*/
private warnOnImageDrift(profile: string, name: string, info: Docker.ContainerInspectInfo): void {
const pinned = this.getContainerSpec(profile)?.image;
const running = info.Config?.Image;
if (!pinned || !running || running === pinned) return;
this.logger.warn(
`Container ${name} runs image ${running}, but this release pins ${pinned}. Remove it with ` +
`\`docker rm -f ${name}\` (its named data volume is kept) and restart OpenWA or re-enable the ` +
`service so it is recreated from the pin.` +
(profile === 'postgres' ? ' A PostgreSQL major version change needs a data migration first.' : ''),
);
}
/**
* Stop a managed profile's container and RETAIN it for a later re-enable.
*
* Deliberately stop-only — no `container.remove()`. The bundled docker-socket-proxy
* (tecnativa/docker-socket-proxy, pinned v0.5.0) never reads its `DELETE` env flag: its
* haproxy.cfg method gate is `deny unless METH_GET || env(POST)`, so container deletion is
* admitted only as an undocumented side effect of POST being enabled — a contract any proxy
* upgrade may withdraw. Stopping needs nothing beyond POST /containers/{id}/stop, which the
* orchestration feature already requires, and retention is what the disable→re-enable flow
* wants anyway: the named data volume and container config survive, and
* startService()/createService() simply restart the retained container. Stop-only is also
* strictly less destructive (a remove with `v: true` discards anonymous volumes).
*
* Caveat: a retained container keeps its original env, and recreating it applies new credentials
* only to a service that reads them at every start. MinIO does: after they change, remove the
* container (`docker rm <name>`) before re-enabling. PostgreSQL does not: POSTGRES_PASSWORD seeds
* the role only when the data volume is first initialized, so a recreated container still
* authenticates with the password stored in the volume. Change it with `ALTER ROLE openwa
* PASSWORD '...'` in the running container, or re-initialize the volume (which discards the data).
* Redis runs without credentials. To reclaim disk space, remove the container manually.
*/
async stopManagedService(profile: string): Promise<boolean> {
this.logger.log(`Stopping service with profile: ${profile} (container retained, not removed)`);
const serviceMap: Record<string, string> = {
postgres: 'database',
redis: 'cache',
minio: 'storage',
};
return this.stopService(serviceMap[profile] || profile);
}
/**
* Stop a container by service name (without removing)
*/
async stopService(service: string): Promise<boolean> {
const container = await this.getContainerByService(service);
if (!container) {
this.logger.warn(`Container for service '${service}' not found`);
return true; // Already doesn't exist
}
try {
const info = await this.answered(abortSignal => container.inspect({ abortSignal }), 'a container inspection');
if (!info.State.Running) {
this.logger.log(`Service '${service}' is already stopped`);
return true;
}
await container.stop();
this.logger.log(`Stopped service: ${service}`);
return true;
} catch (error) {
this.logger.error(`Failed to stop service: ${service}`, error);
return false;
}
}
/**
* Orchestrate services based on required profiles
* This will start containers that match the profiles
*/
async orchestrateProfiles(profiles: string[]): Promise<OrchestrationResult> {
// Calculate estimated time based on profiles
// Base: 15 seconds for core restart (increased for reliability)
let estimatedTime = 15;
if (profiles.includes('postgres')) estimatedTime += 20; // PostgreSQL takes longer
if (profiles.includes('redis')) estimatedTime += 13;
if (profiles.includes('minio')) estimatedTime += 15;
const result: OrchestrationResult = {
success: true,
message: '',
containersStarted: [],
containersStopped: [],
errors: [],
estimatedTime,
};
if (!this.docker || !this.isAvailable) {
result.success = false;
result.message = 'Docker is not available';
return result;
}
this.logger.log(`Orchestrating profiles: ${profiles.join(', ')}`);
// Map profiles to service names
const profileToService: Record<string, string> = {
postgres: 'database',
redis: 'cache',
minio: 'storage',
};
for (const profile of profiles) {
const service = profileToService[profile] || profile;
try {
const started = await this.startService(service);
if (started) {
result.containersStarted.push(profile);
} else {
// startService creates a missing container, so false means the pull, create or start failed.
result.errors.push(
`Failed to create or start the '${profile}' container; see the server log for the Docker error.`,
);
}
} catch (error) {
result.errors.push(`Failed to start ${profile}: ${error instanceof Error ? error.message : 'Unknown error'}`);
}
}
if (result.errors.length > 0) {
result.success = profiles.length > 0 && result.containersStarted.length > 0;
result.message = result.errors.join('; ');
} else {
result.message = `Successfully orchestrated ${result.containersStarted.length} service(s)`;
}
return result;
}
}
/**
* 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' || hostPinnedElsewhere('postgres', env))
return;
const logger = createLogger('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);
}
}