Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: stop the dev and architecture env profiles pinning dashboard keys
Yudhi Armyndharis8bb1d0bcc002
diff --git a/docs/03-system-architecture.md b/docs/03-system-architecture.mdindex 3b6622b1d..f02915238 100644--- a/docs/03-system-architecture.md+++ b/docs/03-system-architecture.md@@ -1042,7 +1042,10 @@ export class WhatsAppWebJsAdapter implements IWhatsAppEngine {this.client = new Client({authStrategy: new LocalAuth({ clientId: this.sessionId, dataPath: this.sessionDataPath }),- puppeteer: { headless: true, args: ['--no-sandbox', '--disable-setuid-sandbox'] },+ puppeteer: {+ headless: true,+ args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage', '--disable-gpu'],+ },});this.setupEventHandlers();@@ -1529,68 +1532,72 @@ flowchart LR### Configuration Examples+Every key below is managed in Dashboard > Infrastructure, so the blocks show them commented out: an+uncommented key in `.env` pins its value over the one the dashboard saves (see the header of+`.env.example`). Uncomment only what you intend to manage by hand.+#### Minimal Profile (.env)```bash# Database-DATABASE_TYPE=sqlite-DATABASE_NAME=./data/openwa.sqlite+# DATABASE_TYPE=sqlite+# DATABASE_NAME=./data/openwa.sqlite# Storage-STORAGE_TYPE=local-STORAGE_LOCAL_PATH=./data/media+# STORAGE_TYPE=local+# STORAGE_LOCAL_PATH=./data/media# Cache: omit / leave Redis disabled -> the cache layer no-ops (no in-memory cache)-REDIS_ENABLED=false+# REDIS_ENABLED=false```#### Standard Profile (.env)```bash# Database (Postgres uses discrete host/port/credentials, not a single URL)-DATABASE_TYPE=postgres-DATABASE_HOST=localhost-DATABASE_PORT=5432-DATABASE_NAME=openwa-DATABASE_USERNAME=openwa-DATABASE_PASSWORD=password+# DATABASE_TYPE=postgres+# DATABASE_HOST=localhost+# DATABASE_PORT=5432+# DATABASE_NAME=openwa+# DATABASE_USERNAME=openwa+# DATABASE_PASSWORD=<set-a-strong-password># Storage-STORAGE_TYPE=local-STORAGE_LOCAL_PATH=./data/media+# STORAGE_TYPE=local+# STORAGE_LOCAL_PATH=./data/media# Cache-REDIS_ENABLED=true-REDIS_HOST=localhost-REDIS_PORT=6379+# REDIS_ENABLED=true+# REDIS_HOST=localhost+# REDIS_PORT=6379```#### Enterprise Profile (.env)```bash# Database-DATABASE_TYPE=postgres-DATABASE_HOST=db-cluster-DATABASE_PORT=5432-DATABASE_NAME=openwa-DATABASE_USERNAME=openwa-DATABASE_PASSWORD=password-DATABASE_POOL_SIZE=50+# DATABASE_TYPE=postgres+# DATABASE_HOST=db-cluster+# DATABASE_PORT=5432+# DATABASE_NAME=openwa+# DATABASE_USERNAME=openwa+# DATABASE_PASSWORD=<set-a-strong-password>+# DATABASE_POOL_SIZE=50# Storage (S3 or any S3-compatible endpoint; MinIO uses the same vars)-STORAGE_TYPE=s3-S3_BUCKET=openwa-media-S3_REGION=ap-southeast-1-S3_ACCESS_KEY_ID=xxx-S3_SECRET_ACCESS_KEY=xxx+# STORAGE_TYPE=s3+# S3_BUCKET=openwa-media+# S3_REGION=ap-southeast-1+# S3_ACCESS_KEY_ID=<access-key-id>+# S3_SECRET_ACCESS_KEY=<secret-access-key># AWS S3 needs NO endpoint (one is derived from the region) — leave S3_ENDPOINT unset for it. An# endpoint is only for S3-compatible stores (MinIO, R2, …), where setting it also enables path-style:# S3_ENDPOINT=http://minio:9000# Cache-REDIS_ENABLED=true-REDIS_HOST=redis-cluster-REDIS_PORT=6379+# REDIS_ENABLED=true+# REDIS_HOST=redis-cluster+# REDIS_PORT=6379```> OpenWA runs as a single API instance per session-data volume; there is no cluster-mode flag.diff --git a/docs/08-development-guidelines.md b/docs/08-development-guidelines.mdindex fd3161917..dc5c19677 100644--- a/docs/08-development-guidelines.md+++ b/docs/08-development-guidelines.md@@ -680,33 +680,39 @@ OpenWA supports multiple infrastructure configurations. Choose based on your nee#### Minimal Profile (Development / Single Session)```bash+# Keys the dashboard manages (Dashboard > Infrastructure) are commented out with their defaults:+# an uncommented key in .env pins that value over the one the dashboard saves (see the header of+# `.env.example`). Uncomment only what you intend to manage by hand.+# ApplicationNODE_ENV=developmentPORT=2785LOG_LEVEL=debug# Database: SQLite (zero config)-DATABASE_TYPE=sqlite-DATABASE_NAME=./data/openwa.sqlite-DATABASE_SYNCHRONIZE=true+# DATABASE_TYPE=sqlite+# DATABASE_NAME=./data/openwa.sqlite+# SQLite runs migrations by default. DATABASE_SYNCHRONIZE=true is SQLite-only: PostgreSQL refuses it+# at boot, so an uncommented true here stops a later switch to PostgreSQL in the dashboard from booting.+# DATABASE_SYNCHRONIZE=false# Storage: Local filesystem-STORAGE_TYPE=local-STORAGE_LOCAL_PATH=./data/media+# STORAGE_TYPE=local+# STORAGE_LOCAL_PATH=./data/media# Redis and queue disabled by default-REDIS_ENABLED=false-QUEUE_ENABLED=false+# REDIS_ENABLED=false+# QUEUE_ENABLED=false# Optional: seed a known admin key. If omitted, OpenWA generates a random key and writes data/.api-key.API_MASTER_KEY=# Session-SESSION_DATA_PATH=./data/sessions+# SESSION_DATA_PATH=./data/sessions# Engine: whatsapp-web.js = Chromium-based; baileys = browser-free WebSocket-ENGINE_TYPE=whatsapp-web.js-PUPPETEER_HEADLESS=true+# ENGINE_TYPE=whatsapp-web.js+# PUPPETEER_HEADLESS=true# Swagger defaults ON outside production and OFF under NODE_ENV=production.# Set it explicitly to force either way.@@ -716,43 +722,52 @@ ENABLE_SWAGGER=true#### Standard Profile (Production / Multi-Session)```bash+# Keys the dashboard manages (Dashboard > Infrastructure) are commented out with the values this+# profile uses; set the ones that differ from the defaults (PostgreSQL, Redis, the queue, /app/data+# paths) there. An uncommented key in .env pins that value over the one the dashboard saves (see the+# header of `.env.example`). Uncomment only what you intend to manage by hand.+# ApplicationNODE_ENV=productionPORT=2785LOG_LEVEL=info# Database: PostgreSQL-DATABASE_TYPE=postgres-DATABASE_HOST=postgres-DATABASE_PORT=5432-DATABASE_USERNAME=openwa-DATABASE_PASSWORD=<set-a-strong-password>-DATABASE_NAME=openwa+# DATABASE_TYPE=postgres+# DATABASE_HOST=postgres+# DATABASE_PORT=5432+# DATABASE_USERNAME=openwa+# DATABASE_PASSWORD=<set-a-strong-password>+# DATABASE_NAME=openwaDATABASE_SYNCHRONIZE=false-DATABASE_POOL_SIZE=10+# DATABASE_POOL_SIZE=10# Storage: Local filesystem-STORAGE_TYPE=local-STORAGE_LOCAL_PATH=/app/data/media+# STORAGE_TYPE=local+# STORAGE_LOCAL_PATH=/app/data/media# Cache: Redis-REDIS_ENABLED=true-REDIS_HOST=redis-REDIS_PORT=6379-QUEUE_ENABLED=true+# REDIS_ENABLED=true+# REDIS_HOST=redis+# REDIS_PORT=6379+# QUEUE_ENABLED=true# Security-API_MASTER_KEY=<set-a-strong-initial-admin-key>-API_KEY_PEPPER=<optional-hash-pepper>+# First-boot seed for the initial ADMIN key, ignored once any key exists. Leave it unset to+# generate a random key into data/.api-key, or set one generated with: openssl rand -base64 32+# API_MASTER_KEY=+# Optional HMAC pepper so a DB leak alone can't precompute key hashes. Generate a random value+# (openssl rand -base64 32); setting or changing it invalidates every API key issued before.+# API_KEY_PEPPER=CORS_ORIGINS=https://dashboard.example.com# Session-SESSION_DATA_PATH=/app/data/sessions+# SESSION_DATA_PATH=/app/data/sessions# Engine-ENGINE_TYPE=whatsapp-web.js-PUPPETEER_HEADLESS=true-PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox,--disable-dev-shm-usage,--disable-gpu+# ENGINE_TYPE=whatsapp-web.js+# PUPPETEER_HEADLESS=true+# PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox,--disable-dev-shm-usage,--disable-gpuENABLE_SWAGGER=false```@@ -973,7 +988,7 @@ export class EngineTeardownService {1. **Chrome/Puppeteer issue**- Ensure Chrome for Testing is installed: `ls /usr/local/bin/puppeteer-chrome`- - Check Puppeteer args: `--no-sandbox --disable-setuid-sandbox`+ - Check Puppeteer args (`PUPPETEER_ARGS`); the default is `--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage --disable-gpu`2. **Previous session data corrupted**- Clear the stored auth/session data for the session under `data/sessions`diff --git a/src/common/docs-governance.spec.ts b/src/common/docs-governance.spec.tsindex 2ec28904c..143c2c15f 100644--- a/src/common/docs-governance.spec.ts+++ b/src/common/docs-governance.spec.ts@@ -99,6 +99,13 @@ describe('governance docs match the repository', () => {expect(note).toContain('`docker compose up -d --no-build`');});+ // Most values in the Standard profile are the defaults; only some groups differ.+ it('does not call every commented Standard profile value a non-default', () => {+ const header = between(read('docs/08-development-guidelines.md'), '#### Standard Profile', '# Application');+ expect(header).not.toMatch(/which are not the defaults/);+ expect(header).toMatch(/set the ones that differ from the defaults/);+ });+// Registries show the package description on its own in search results, away from the README.it('keeps the non-affiliation notice in every SDK registry description', () => {const descriptions = [diff --git a/src/config/env-precedence.spec.ts b/src/config/env-precedence.spec.tsindex 40e6412e2..785cfc426 100644--- a/src/config/env-precedence.spec.ts+++ b/src/config/env-precedence.spec.ts@@ -266,11 +266,13 @@ describe.each(['docker-compose.yml', 'docker-compose.dev.yml'])('every blank for* past the compose-derived check and shipped uncommented, pinning the matching Infrastructure control* for anyone who ran the documented `cp .env.example .env`.*- * Derived from the appliers that write data/.env.generated, so a key added to a section is covered- * without anyone remembering this file exists.+ * Derived from the appliers that write data/.env.generated, plus the controller's own queue write, so+ * a key added to a section is covered without anyone remembering this file exists.*/describe('every key the dashboard writes is commented out in .env.example', () => {- const sectionsSource = fs.readFileSync(path.join(__dirname, '../modules/infra/config-sections.ts'), 'utf8');+ const sectionsSource = ['config-sections.ts', 'infra-config.controller.ts']+ .map(file => fs.readFileSync(path.join(__dirname, '../modules/infra', file), 'utf8'))+ .join('\n');/** `updates.KEY = …` */const directlyAssigned = (): string[] => [...sectionsSource.matchAll(/updates\.([A-Z0-9_]+)\s*=/g)].map(m => m[1]);@@ -280,11 +282,12 @@ describe('every key the dashboard writes is commented out in .env.example', () =const dashboardOwned = (): string[] => [...new Set([...directlyAssigned(), ...viaSecretHelper()])].sort();- // Guard both extractors independently. The direct form alone finds 27 keys and silently misses+ // Guard both extractors independently. The direct form alone finds 28 keys and silently misses// every key routed through setSecret, so a single combined count would look healthy while the// secret keys went unchecked.it('extracts keys from both write forms', () => {expect(directlyAssigned()).toContain('DATABASE_SSL');+ expect(directlyAssigned()).toContain('QUEUE_ENABLED'); // written by the controller, not a section applierexpect(viaSecretHelper()).toContain('REDIS_PASSWORD');});@@ -313,6 +316,22 @@ describe('every key the dashboard writes is commented out in .env.example', () =expect(uncommented).not.toContain('API_KEY_PEPPER');});+ // The docs/08 and docs/03 env profiles are pasted into .env the same way.+ it.each([+ ['docs/08-development-guidelines.md', '### Environment Variables', '## 8.9', 2],+ ['docs/03-system-architecture.md', '### Configuration Examples', '### Choosing a Profile', 3],+ ])('ships none of them uncommented in the %s profiles', (file, from, to, blocks) => {+ const docs = fs.readFileSync(path.join(__dirname, '../..', file), 'utf8');+ const start = docs.indexOf(from);+ const section = docs.slice(start, docs.indexOf(to, start));+ const bodies = [...section.matchAll(/```bash\n([\s\S]*?)```/g)].map(match => match[1]);+ expect(start).toBeGreaterThanOrEqual(0);+ expect(bodies).toHaveLength(blocks); // the profiles were found+ const uncommented = bodies.flatMap(assignedKeys);+ expect(uncommented.filter(key => dashboardOwned().includes(key))).toEqual([]);+ expect(uncommented).not.toContain('API_KEY_PEPPER');+ });+/*** `.env.minimal` is also copied to `.env` by the docs (docs/README.md), but its rule is NARROWER on* purpose: it describes itself as a development/personal config and deliberately pins the choices an