Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(infra): clarify when pinned flags start containers
Yudhi Armyndharisde2ae98199af
diff --git a/docs/05-database-design.md b/docs/05-database-design.mdindex 3733133cd..d33ed31db 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`. 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. A flag decides only that start: whether the app uses the container follows its host. A `*_BUILTIN=true` the environment pins starts the bundled container at every boot whatever host the saved file gives the app, so after the dashboard switched that datastore to an external server the container runs unused until the variable is unset.+With `DATABASE_TYPE=postgres` and `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. A flag decides only that start: whether the app uses the container follows its host. A `*_BUILTIN=true` the environment pins starts the bundled container at every boot whatever host the saved file gives the app, so after the dashboard switched that datastore to an external server the container runs unused until the variable is unset.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/docs/14-migration-guide.md b/docs/14-migration-guide.mdindex 8c5979218..da79b02d5 100644--- a/docs/14-migration-guide.md+++ b/docs/14-migration-guide.md@@ -322,7 +322,7 @@ Redis in OpenWA holds only **ephemeral** state: BullMQ jobs (see below), and —```bash# Switch from built-in to external RedisREDIS_ENABLED=true-REDIS_BUILTIN=false # false = external Redis+REDIS_BUILTIN=false # Do not start the bundled containerREDIS_HOST=your-redis-host.comREDIS_PORT=6379REDIS_USERNAME=optional@@ -331,8 +331,9 @@ REDIS_TLS=false # true for a managed Redis that requires TLS```> Setting `REDIS_BUILTIN` in `.env` **pins** it: the env value wins, and it decides only whether-> OpenWA starts the bundled container at boot. `true` starts it at every boot, even after the-> dashboard switched Redis to an external host, and `false` never does; which Redis the app uses+> OpenWA starts the bundled container at boot. `true` starts it at every boot while Redis is in use+> and `REDIS_HOST` is not pinned elsewhere, even after the dashboard saved an external host;+> `false` never starts it. Which Redis the app uses> follows `REDIS_HOST`, as the dashboard writes it. That is the right trade for a deployment> whose configuration lives in `.env` — but if you manage datastores from the dashboard, leave the> key unset (as the shipped templates do) and set only the connection details above. The same holds