Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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.ts
index 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