Configuration

1. Environment Variables

Core keys from EnvironmentKeys (@nx/core + @venizia/ignis); commerce adds BullMQ Redis keys in src/common/environments.ts. Read via applicationEnvironment.get<T>(key).

Core runtime

Name	Type	Default	Required	Description
APP_ENV_PORT	number	3000		HTTP listen port (container)
APP_ENV_HOST	string	0.0.0.0		Bind address
APP_ENV_BASE_PATH	string	/v1/api/commerce		Route prefix
APP_ENV_NODE_ID	number	—	✓	Snowflake worker ID — must be 2
APP_ENV_WORKERS	csv|ALL	—		Enables SyncProductWorker (+ CDC consumer in WORKER role)
RUN_MODE	migrate|server	—		migrate switches to migration entry

Database

Name	Type	Default	Required	Description
APP_ENV_DB_URL	string	—	✓	PostgreSQL connection URL

Cache / authorization Redis

Name	Type	Default	Required	Description
APP_ENV_REDIS_*	—	—		Cache Redis (useCacheRedis); also authorization Redis (getAuthorizationRedisConnection) and footer-summary cache

BullMQ Redis (separate connection)

Name	Type	Default	Required	Description
APP_ENV_BULLMQ_REDIS_MODE	single|cluster	single		Connection mode
APP_ENV_BULLMQ_REDIS_HOST	string	localhost		Single-mode host
APP_ENV_BULLMQ_REDIS_PORT	number	6379		—
APP_ENV_BULLMQ_REDIS_PASSWORD	string	—		—
APP_ENV_BULLMQ_REDIS_DATABASE	number	0		—
APP_ENV_BULLMQ_REDIS_MAX_RETRY	number	5		—
APP_ENV_BULLMQ_REDIS_CLUSTER_NODES	string	—	cluster	Required when mode=cluster
APP_ENV_BULLMQ_WORKER_CONCURRENCY	number	1		SyncProductWorker concurrency

WebSocket Redis

Name	Type	Default	Required	Description
APP_ENV_WEBSOCKET_REDIS_MODE	single|cluster	single		—
APP_ENV_WEBSOCKET_REDIS_HOST/PORT/PASSWORD/DB/MAX_RETRY	—	host localhost, port 6379, db 0, retry 5		Single-mode WebSocketEmitter connection
APP_ENV_WEBSOCKET_REDIS_CLUSTER_NODES	string	—	cluster	Required when mode=cluster

Kafka (producer-only)

Name	Type	Default	Required	Description
APP_ENV_KAFKA_BROKERS	csv	—		Comma-separated broker list (empty ⇒ no brokers)
APP_ENV_KAFKA_CLIENT_ID	string	SVC-00020-COMMERCE_PRODUCER		Producer client id
APP_ENV_KAFKA_SASL_ENABLE	'true'|'false'	false		Toggle SASL
APP_ENV_KAFKA_SASL_MECHANISM/USERNAME/PASSWORD	string	NA		When SASL enabled

Producer config: requestTimeout 60_000ms, connectTimeout 30_000ms, JSON value serializer. The producer is bound but not invoked in src/.

Security / integrations

Name	Type	Default	Required	Description
APP_ENV_APPLICATION_SECRET	string	—	✓ (for provider integrations)	AES-256-GCM key for EncryptService
APP_ENV_JWKS_URL	url	—	✓	Identity JWKS endpoint
APP_ENV_BASIC_AUTH_*	string	—		Service-to-service basic creds

Search/asset components (@nx/search, @nx/asset) read their own env (Typesense nodes, Minio endpoint/keys, embedding config) — see those packages.

2. Feature Flags

No global feature flags. Runtime behavior is gated by:

Gate	Mechanism
Worker / CDC enablement	APP_ENV_WORKERS (SyncProductWorker; CDC consumer in WORKER role)
Per-merchant strictCategoryDeletion / cascade flags	DeletionPolicyService (per-merchant policy)
Product sync to extra merchants	presence of merchantIds[] / syncMerchantIds in aggregate request

3. Seeded Data

Migration processes in src/migrations/processes/. Run on bootstrap (prestart → bun run rebuild → migrate.ts); per-dev via bun run migrate:dev.

Process	Seeds / backfills
commerce-0002-seed-permissions	RBAC permission catalogue
commerce-0003-seed-typesense-embedding-configs	Semantic-search embedding configs
commerce-0005-seed-default-finance-accounts	System default finance accounts config
commerce-0006-seed-merchant-fnb-sectors	FnB sector taxonomy
commerce-0007-seed-category-templates	SYSTEM category templates
commerce-0008-seed-search-pipeline-config	Search pipeline config
commerce-0009-seed-role-permissions	Role→permission grants
commerce-0010-seed-guest-permissions	Guest-role permissions
commerce-0011-backfill-merchant-onboarding	Backfill metadata.onboarding flags

4. Configuration Storage (Configuration table)

Kind	Encryption	Scope key
Provider-integration credentials	AES-256-GCM (EncryptService)	(group, code, principalId, principalType, environment)
System configs (finance accounts, category templates, search pipeline)	—	group=SYSTEM, principalId/Type=null

Credential code format: {type}:{provider}:{credentialAction}:{credentialType}. Responses return a masked display value; getDecryptedCredential is internal-only (never exposed via controller).

5. Related Pages

• Operations — deployment + observability
• API Events — CDC / BullMQ / WebSocket
• Decisions