Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(devops): stop the env excerpt pinning dashboard-owned keys
Yudhi Armyndharisee4f87aed16d
diff --git a/docs/10-devops-infrastructure.md b/docs/10-devops-infrastructure.mdindex b82a6368e..6990ec737 100644--- a/docs/10-devops-infrastructure.md+++ b/docs/10-devops-infrastructure.md@@ -390,6 +390,9 @@ flowchart TB```bash# .env — excerpt of the commonly-tuned keys. The repo's `.env.example` is the canonical,# fully annotated list; add nothing here that does not appear there.+# 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@@ -405,8 +408,8 @@ LOG_FORMAT=json# ===========================================# Option 1: SQLite (for minimal deployments)# For SQLite, DATABASE_NAME is the database FILE PATH.-DATABASE_TYPE=sqlite-DATABASE_NAME=./data/openwa.sqlite+# DATABASE_TYPE=sqlite+# DATABASE_NAME=./data/openwa.sqlite# Option 2: PostgreSQL (for production) — DATABASE_NAME is the database NAME here# DATABASE_TYPE=postgres@@ -424,8 +427,8 @@ DATABASE_NAME=./data/openwa.sqlite# STORAGE_TYPE accepts only `local` or `s3` — env validation rejects anything else and the app# FAILS TO BOOT ("Invalid environment configuration"). There is no silent fallback to local disk.# Option 1: Local filesystem (default)-STORAGE_TYPE=local-STORAGE_LOCAL_PATH=./data/media+# STORAGE_TYPE=local+# STORAGE_LOCAL_PATH=./data/media# Option 2: S3 (AWS) — leave S3_ENDPOINT unset; the SDK derives it from the region# STORAGE_TYPE=s3@@ -448,9 +451,9 @@ STORAGE_LOCAL_PATH=./data/media# Both are opt-in and both need a reachable Redis, configured with the discrete host/port pair# (there is no REDIS_URL). Defaults: no cache at all (CacheService is a no-op and every read falls# through to the database — there is no in-memory tier) and inline (non-queued) dispatch.-REDIS_ENABLED=false-REDIS_HOST=localhost-REDIS_PORT=6379+# REDIS_ENABLED=false+# REDIS_HOST=localhost+# REDIS_PORT=6379# Redis-backed caching switches on when REDIS_ENABLED=true OR CACHE_ENABLED=true — enabling Redis# for the queue alone therefore also enables the cache.# CACHE_ENABLED=true@@ -462,12 +465,12 @@ REDIS_PORT=6379# ENGINE_TYPE=baileys # whatsapp-web.js (default) | baileys; omit to use the dashboard selection# Session-SESSION_DATA_PATH=./data/sessions+# SESSION_DATA_PATH=./data/sessions# Puppeteer (for whatsapp-web.js)PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-PUPPETEER_HEADLESS=true-PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox+# PUPPETEER_HEADLESS=true+# PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox,--disable-dev-shm-usage,--disable-gpu# Optional per-browser-command budget, ms. Unset = Puppeteer's own budget. Raise only after seeing# "Runtime.callFunctionOn timed out"; positive integer, max 2147483647 (cost: see docs/12).# PUPPETEER_PROTOCOL_TIMEOUT_MS=300000@@ -478,8 +481,9 @@ PUPPETEER_ARGS=--no-sandbox,--disable-setuid-sandbox# 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-API_KEY_PEPPER=optional-key-hashing-pepper+# 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=# ===========================================# WEBHOOK@@ -542,12 +546,15 @@ export default () => ({puppeteer: {executablePath: process.env.PUPPETEER_EXECUTABLE_PATH || undefined,headless: process.env.PUPPETEER_HEADLESS !== 'false',- // Split on commas AND whitespace; the default is a four-flag string, not an empty list- args: (- process.env.PUPPETEER_ARGS || '--no-sandbox,--disable-setuid-sandbox,--disable-dev-shm-usage,--disable-gpu'- )- .split(/[\s,]+/)- .filter(Boolean),+ // Split on whitespace, and on a comma only before the next flag, so a flag value keeps its+ // commas (--disable-features=A,B). The default is a four-flag string, not an empty list, and+ // --lang=en-US is appended unless a --lang flag is already present.+ args: withPinnedBrowserLocale(+ (process.env.PUPPETEER_ARGS || '--no-sandbox,--disable-setuid-sandbox,--disable-dev-shm-usage,--disable-gpu')+ .split(/\s+|,+(?=-)/)+ .map(arg => arg.replace(/^,+|,+$/g, ''))+ .filter(Boolean),+ ),},},webhook: {diff --git a/src/config/env-precedence.spec.ts b/src/config/env-precedence.spec.tsindex 0abe1eb2b..c9f4c4581 100644--- a/src/config/env-precedence.spec.ts+++ b/src/config/env-precedence.spec.ts@@ -288,12 +288,13 @@ describe('every key the dashboard writes is commented out in .env.example', () =expect(viaSecretHelper()).toContain('REDIS_PASSWORD');});- const uncommentedKeys = (file: string): string[] =>- fs- .readFileSync(path.join(__dirname, '../..', file), 'utf8')+ const assignedKeys = (text: string): string[] =>+ text.split('\n').map(line => /^([A-Z0-9_]+)=/.exec(line)?.[1]).filter((key): key is string => key !== undefined);+ const uncommentedKeys = (file: string): string[] =>+ assignedKeys(fs.readFileSync(path.join(__dirname, '../..', file), 'utf8'));it('ships none of them uncommented in .env.example', () => {const uncommented = uncommentedKeys('.env.example');@@ -301,6 +302,17 @@ describe('every key the dashboard writes is commented out in .env.example', () =expect(uncommented.filter(key => dashboardOwned().includes(key))).toEqual([]);});+ // docs/10 section 10.5 presents its .env block as an excerpt of .env.example, so operators copy it+ // the same way and it has to follow the same rule. A published pepper is no secret either.+ it('ships none of them uncommented in the docs/10 environment excerpt', () => {+ const docs = fs.readFileSync(path.join(__dirname, '../../docs/10-devops-infrastructure.md'), 'utf8');+ const section = docs.slice(docs.indexOf('## 10.5 Environment Configuration'));+ const uncommented = assignedKeys(/```bash\n([\s\S]*?)```/.exec(section)?.[1] ?? '');+ expect(uncommented).toContain('NODE_ENV'); // the block was found and does ship some keys uncommented+ 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