Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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.md
index 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.
+
# Application
NODE_ENV=development
PORT=2785
LOG_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.
+
# Application
NODE_ENV=production
PORT=2785
LOG_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=openwa
DATABASE_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-gpu
ENABLE_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.ts
index 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.ts
index 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 applier
expect(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