Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(scaling): say what two instances on one daemon must not share
Yudhi Armyndharis278e8fc62406
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex b9a34b6b2..9c4965617 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -5541,7 +5541,7 @@ Aggregate infrastructure status (database, Redis, queue, storage, engine).The `queue.webhooks` counters are live BullMQ job counts (`pending` = waiting + active + delayed; plus `completed`/`failed`), degrading to zeros when the queue is disabled or Redis is unreachable. `redis.connected` is a live probe. `database.host` is the configured `DATABASE_HOST` (default `localhost`) and is reported on SQLite too, so read `type`, not `host`, to tell the database apart.-`builtIn` (on `database`/`redis`/`storage`) reports whether OpenWA's own bundled container is actually running _and_ backing this service, detected live from the labelled container; when Docker is unreachable it falls back to the saved `*_BUILTIN` flag (one pinned by the environment first, else the one in `data/.env.generated`), and a host name alone counts for nothing there, since an external server may be called `postgres`. `running` (on the same three) reports whether a bundled container OpenWA itself created is up, whether or not the service uses it: one Docker Compose created (it carries Compose's project label) reads `false`, so does one beside a configuration whose `POSTGRES_BUILTIN`, `REDIS_BUILTIN` or `MINIO_BUILTIN` (the environment's first, else the saved one) is not `true` (the container names are fixed per Docker daemon, so another OpenWA instance on the same daemon sees the same containers), and the key is absent while Docker is unreachable, since nothing can be seen or stopped then. In S3 mode `storage` additionally carries `bucket` and `endpoint` (each when one is configured; a bundled MinIO that is stopped still reports `http://minio:9000` here, with `builtIn` false) and `s3Available` (re-probed, throttled, while false; once true it stays true until a restart, so a later outage does not clear it); in local mode neither key is present. `engine.webVersion`/`engine.webVersionSource` (`pinned` / `auto` / `native`) appear only on `whatsapp-web.js`; `webVersion` is `null` until the auto-resolve first succeeds. `engine.browserArgs` is the effective launch argument list: `PUPPETEER_ARGS` (or the four defaults shown) with `--lang=en-US` appended unless a `--lang` flag is already present.+`builtIn` (on `database`/`redis`/`storage`) reports whether OpenWA's own bundled container is actually running _and_ backing this service, detected live from the labelled container (on a daemon another OpenWA instance shares, its container counts too while this instance's host is spelled like the bundled one, see [13 - Horizontal Scaling](./13-horizontal-scaling.md)); when Docker is unreachable it falls back to the saved `*_BUILTIN` flag (one pinned by the environment first, else the one in `data/.env.generated`), and a host name alone counts for nothing there, since an external server may be called `postgres`. `running` (on the same three) reports whether a bundled container OpenWA itself created is up, whether or not the service uses it: one Docker Compose created (it carries Compose's project label) reads `false`, so does one beside a configuration whose `POSTGRES_BUILTIN`, `REDIS_BUILTIN` or `MINIO_BUILTIN` (the environment's first, else the saved one) is not `true` (the container names are fixed per Docker daemon, so another OpenWA instance on the same daemon sees the same containers), and the key is absent while Docker is unreachable, since nothing can be seen or stopped then. In S3 mode `storage` additionally carries `bucket` and `endpoint` (each when one is configured; a bundled MinIO that is stopped still reports `http://minio:9000` here, with `builtIn` false) and `s3Available` (re-probed, throttled, while false; once true it stays true until a restart, so a later outage does not clear it); in local mode neither key is present. `engine.webVersion`/`engine.webVersionSource` (`pinned` / `auto` / `native`) appear only on `whatsapp-web.js`; `webVersion` is `null` until the auto-resolve first succeeds. `engine.browserArgs` is the effective launch argument list: `PUPPETEER_ARGS` (or the four defaults shown) with `--lang=en-US` appended unless a `--lang` flag is already present.`envPinned` lists which of `DATABASE_TYPE`, `DATABASE_HOST`, `REDIS_ENABLED`, `REDIS_HOST`, `STORAGE_TYPE`, `S3_ENDPOINT`, `STORAGE_LOCAL_PATH`, `ENGINE_TYPE`, `PUPPETEER_HEADLESS`, `SESSION_DATA_PATH` and `PUPPETEER_ARGS` the host environment or the project `.env` sets. Those layers win over `data/.env.generated`, so a value saved for one of these keys through `PUT /api/infra/config` cannot take effect until that layer is changed. A pinned host also decides whether the bundled container backs its service, whatever `builtIn` is saved.diff --git a/docs/13-horizontal-scaling.md b/docs/13-horizontal-scaling.mdindex e88ea66b2..1746bbe2a 100644--- a/docs/13-horizontal-scaling.md+++ b/docs/13-horizontal-scaling.md@@ -748,10 +748,18 @@ On one Docker daemon, the built-in datastores Dashboard > Infrastructure startsinstance: their container names (`openwa-postgres`, `openwa-redis`, `openwa-minio`), their volumes andthe `openwa-network` network are fixed, so a second instance that turns on Use Built-in attaches to thefirst instance's container and data. Let at most one instance on a daemon use them, and point the-others at datastores of their own with their Use Built-in toggles off. A restart from the dashboard-stops a bundled container only when that instance's own configuration uses it or set it up (its-`*_BUILTIN` flag), so an instance that never chose the built-in and dials its own servers leaves the-other one's containers running.+others at datastores of their own with their Use Built-in toggles off.++Each instance finds a bundled container by its `com.openwa.service` label anywhere on the daemon. Its+status reads a running one as the datastore it uses whenever its own host for that datastore is spelled+like the bundled one: `postgres`, `redis`, `minio` or the container name, in any letter case, with or+without a trailing dot. A dashboard restart that then switches that datastore off or to another host+stops the first container on the daemon with that label, which can be the other instance's. So give the+other instances' datastores host names of their own and no `com.openwa.*` labels; a second copy of the+shipped compose file needs its own project name and container names, and its app must reach its+datastores under names other than `postgres`, `redis` and `minio`. An instance set up that way whose+`*_BUILTIN` flags are not `true` leaves the other instance's containers running: its dashboard counts+a container OpenWA created as its own only beside its own flag, and asks to stop none of them.| Metric | Threshold | Action || --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- |diff --git a/src/modules/infra/infra-status.controller.ts b/src/modules/infra/infra-status.controller.tsindex 6b339a144..df0c9497a 100644--- a/src/modules/infra/infra-status.controller.ts+++ b/src/modules/infra/infra-status.controller.ts@@ -197,7 +197,9 @@ export class InfraStatusController {// Built-in detection: prefer the actually-running bundled container as truth (so a stopped/missing// container, or a host-pinned external host, reads as NOT built-in), and require the app to be// pointed at the bundled service. Fall back to the saved *_BUILTIN flag (the environment's first) when- // Docker is unreachable (bare-npm / socket-less) so the toggles don't spuriously flip off. (#488)+ // Docker is unreachable (bare-npm / socket-less) so the toggles don't spuriously flip off. (#488) The labelled+ // container may be another instance's on the same daemon: it counts whenever this one's host is spelled like the+ // bundled one (docs/13, Scaling Guidelines).// `running` names a container OpenWA created beside this instance's own built-in flag only: the container names// are fixed per daemon, so a second instance there sees the first one's containers, which are not its to stop.const s3Endpoint = this.configService.get<string>('storage.s3.endpoint');