Environment Variables

Environment Variables

Source of truth: infra/.env.production.template. Copy that file to /opt/ecommus/.env on the VPS, fill in placeholders, and chmod 600. The API refuses to boot in NODE_ENV=production when any R (“required-in-prod”) variable below is missing or set to a dev-* placeholder — see validateProductionConfig() at apps/api/src/config.ts:48.

Legend:

• R = required in production (boot fails fast if missing)
• R* = required only when the matching feature is enabled (ANAF, S3, etc.)
• empty = optional (uses default)

Core

Variable	R	Default	Description
NODE_ENV		development	development / test / production. Production triggers validateProductionConfig().
APP_NAME		Ecommus	Human-readable app name (used in emails, OpenAPI title, etc.)
API_PORT		4000	Fastify HTTP listener port.
API_HOST		0.0.0.0	Bind address. Use 127.0.0.1 if proxying through Caddy/Nginx on same host.
APP_URL	R	http://ecommus.local	Public storefront URL. Used by emails, CORS, and OG tags.
ADMIN_URL	R	http://admin.ecommus.local	Public admin URL. CORS allowlist + email links.
API_URL	R	http://api.ecommus.local	Public API URL. CORS + storefront SSR fetches.
SUPER_ADMIN_URL		—	Super-admin URL (Enterprise + MediaDesign-internal).
LOG_LEVEL		info	trace/debug/info/warn/error. Pino structured logs.
TZ		Europe/Bucharest	Server timezone (date math, cron, fiscal reports).

Database

Variable	R	Default	Description
DATABASE_MODE	R	pglite	pglite (dev only) or postgres. Production fail-fast if not postgres.
DATABASE_URL	R	—	PostgreSQL DSN. e.g. postgres://ecommus:pass@host:5432/ecommus_prod
DATABASE_DIR		./data/db	pglite data directory (dev only).
LICENSE_DATABASE_URL	R*	—	Separate DSN for the license-server (only when self-hosting apps/license-server).
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB		—	Used by Docker Compose to bootstrap the Postgres container. Code reads DATABASE_URL.

Caution

Never use DATABASE_MODE=pglite in production. pglite is single-process and cannot survive a real load.

Auth (JWT)

Variable	R	Default	Description
JWT_ACCESS_SECRET	R	dev-access-secret	32+ chars, random. Boot fails if dev-* in production.
JWT_REFRESH_SECRET	R	dev-refresh-secret	32+ chars, random, different from JWT_ACCESS_SECRET. Pair correctness depends on independence.
JWT_ACCESS_TTL		15m	Access token lifetime (15m, 1h, etc.).
JWT_REFRESH_TTL		30d	Refresh token lifetime.
JWT_KEY_ID		v1	kid claim. Bump when rotating signing keys; old tokens stay valid during the transition (validator accepts multiple kids).

Generate strong secrets:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
# or
openssl rand -hex 32

License (customer install)

Variable	R	Default	Description
ECOMMUS_LICENSE_JWT	R	—	The customer license JWT (Ed25519). Pasted from the activation email. See License for the shape.
ECOMMUS_LICENSE_SERVER_URL		https://license.ecommus.ro	Where the customer install heartbeats and re-fetches tokens. Override to http://127.0.0.1:4500 for self-hosted server.
ECOMMUS_LICENSE_VERIFY_URL		https://license.ecommus.ro/verify	Verification endpoint (used by the Verdaccio plugin to gate npm install).
ECOMMUS_NPM_REGISTRY_URL		https://npm.ecommus.ro	Private registry for premium plugins/themes.

License server (MediaDesign-internal only)

These keys are used by apps/license-server. Customer installs leave them empty.

Variable	R	Default	Description
ECOMMUS_LICENSE_PRIVATE_KEY_FILE	R	/opt/ecommus/keys/license-private.pem	Ed25519 PEM. Generated by provision.sh.
ECOMMUS_LICENSE_PUBLIC_KEY_FILE	R	/opt/ecommus/keys/license-public.pem	Ed25519 PEM (counterpart). Distributed with each customer copy.
LICENSE_SERVER_ADMIN_TOKEN	R	—	Bearer for /licenses/issue, /licenses/refund. Boot fails if dev-* or change-me.
LICENSE_DEFAULT_PERIOD		3mo	Default subscription period when issuing a license without an explicit value.
STRIPE_LICENSE_WEBHOOK_SECRET	R*	—	Verifies invoice.paid from Stripe. Required when Stripe issues licenses for SaaS / source customers.

Code signing

Variable	R	Default	Description
ECOMMUS_CODE_SIGNING_PUBLIC_KEY_FILE	R	/opt/ecommus/keys/code-signing-public.pem	Ed25519 PEM. Used to verify plugin/theme bundle signatures.
ECOMMUS_CODE_SIGNING_PRIVATE_KEY_FILE	R*	/opt/ecommus/keys/code-signing-private.pem	Used by MediaDesign to sign new bundles before publishing.
ECOMMUS_REQUIRE_SIGNED_PLUGINS		true in prod	Refuse to load unsigned plugins. Production loader auto-promotes if not set.
ECOMMUS_PERMISSION_ENFORCEMENT		strict in prod	Plugin permission mode. strict rejects, warn logs but allows. Production auto-promotes.

Redis (cache + queues)

Variable	R	Default	Description
REDIS_URL	R	redis://redis:6379	BullMQ + cache. In dev, an in-memory fallback works; production needs a real Redis.

Email

Variable	R	Default	Description
RESEND_API_KEY	R*	—	Preferred email path. Required if you want transactional emails to actually go out.
RESEND_FROM		Ecommus <hello@ecommus.ro>	Verified sender address (only set after Resend domain verification completes).
SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS		—	Fallback SMTP. Used only when RESEND_API_KEY is empty.
SMTP_FROM		noreply@ecommus.local	SMTP From: header.

Storage

Variable	R	Default	Description
STORAGE_DRIVER		local	local or s3.
STORAGE_LOCAL_DIR		/opt/ecommus/uploads	Filesystem path when local. Persistent volume in production.
S3_BUCKET	R*	—	Required when STORAGE_DRIVER=s3.
AWS_REGION	R*	eu-central-1	Canonical name (was S3_REGION historically — code reads AWS_REGION via the AWS SDK).
AWS_ACCESS_KEY_ID	R*	—	Leave empty when running on EC2 with an IAM role.
AWS_SECRET_ACCESS_KEY	R*	—	Same.
S3_ENDPOINT		—	Set only for non-AWS S3-compatible providers (Wasabi, Backblaze B2, Cloudflare R2).
ASSET_CDN_URL		—	Public CDN base for served assets (CloudFront, Cloudflare). Replaces direct bucket URLs.

Payments

Variable	R	Default	Description
PAYMENT_DRIVER	R	mock	stripe / netopia / euplatesc / mock. Must be explicit in production (Phase A.0 Bug-C2).
STRIPE_SECRET_KEY	R*	—	sk_live_... (or sk_test_... while staging).
STRIPE_PUBLISHABLE_KEY	R*	—	pk_live_.... Stripe canonical name; legacy STRIPE_PUBLIC_KEY is no longer read.
STRIPE_WEBHOOK_SECRET	R*	—	Verifies storefront-order events. Required when Stripe is the storefront payment driver.
NETOPIA_POS_SIGNATURE	R*	—	Netopia merchant signature.
NETOPIA_MODE		sandbox	sandbox / live.
EUPLATESC_MID	R*	—	EuPlatesc merchant ID.

ANAF e-Factura RO (mandatory for every RO ecommerce customer)

Code in apps/api/src/services/efactura.service.ts requires these. Without ANAF_OAUTH_TOKEN, every order silently fails e-Factura submission.

Variable	R	Default	Description
ANAF_CIF	R	—	Firmă’s CIF/CUI without the RO prefix.
ANAF_OAUTH_TOKEN	R	—	Bearer token from ANAF SPV.
ANAF_CLIENT_ID		—	OAuth client_id (used by the token-refresh flow).
ANAF_CLIENT_SECRET		—	OAuth client_secret.
ANAF_MODE	R	test	test / prod. Stay on test until KYC complete and ready to submit live e-Facturas.

Shipping providers RO

Required for fulfilment if the customer ships physical goods. Paste from each carrier’s portal.

Variable	R	Description
SAMEDAY_USERNAME / SAMEDAY_PASSWORD	R*	Sameday Courier API credentials.
FAN_USERNAME / FAN_PASSWORD / FAN_CLIENT_ID	R*	FAN Courier API.
DPD_USERNAME / DPD_PASSWORD	R*	DPD RO.

SMS provider RO (smslink)

Variable	R	Description
SMSLINK_USERNAME	R*	smslink API account.
SMSLINK_PASSWORD	R*	smslink API password.
SMSLINK_FROM	R*	Display sender (≤ 11 chars).

Tenant + workers

Variable	R	Default	Description
TENANT_MODE		multi	single (one row in tenants table, auto-resolve) or multi (subdomain or header).
AUTO_SETUP		false	Never auto-create demo data in production. Dev-only convenience.
ECOMMUS_WORKERS		true	Enables background workers (low-stock alerter, reservation sweeper, license heartbeat, expiry warnings, etc.). Disable for split deploys.

Rate limits

Variable	Default	Description
RATE_LIMIT_MAX_REQUESTS	200	Per-IP per-window cap on the Fastify rate limiter.
RATE_LIMIT_WINDOW_MS	60000	Window size in ms.

Localisation

Variable	R	Default	Description
DEFAULT_CURRENCY		RON (prod template) / EUR (code default)	RO market default; override per-tenant via admin UI.
DEFAULT_LOCALE		ro	ro / en / hu / bg. Per-tenant override available.

Encryption-at-rest

Phase 0 §1.6 — column-level envelope encryption for payment_methods.config and settings.value (ANAF tokens).

Variable	R	Description
ECOMMUS_DATA_KEY	R	Master KEK that wraps per-row DEKs. openssl rand -hex 32. Rotating re-keys every encrypted row (see ADR-028).

Observability

Variable	R	Description
SENTRY_DSN		Sentry SaaS or self-hosted GlitchTip (recommended — €0, EU-hosted, GDPR-friendly, Sentry-DSN-compatible). Leave empty until stack lands.
OTEL_EXPORTER_OTLP_ENDPOINT		OpenTelemetry exporter (Tempo / Jaeger). No-op when unset.
METRICS_TOKEN	R	Bearer for /metrics (Prometheus scrape). Must be set; the endpoint is auth-gated.

Analytics / pixels (optional, per-tenant configurable in admin too)

Variable	Description
GA4_MEASUREMENT_ID	G-XXXXXXXXXX — GA4 client-side.
GA4_API_SECRET	Server-side Measurement Protocol (Phase A.0 Bug-S4).
META_PIXEL_ID / META_CAPI_TOKEN	Meta Conversions API.
TIKTOK_PIXEL_ID / TIKTOK_ACCESS_TOKEN	TikTok pixel + Events API.
TAWKTO_WIDGET_ID	Tawk.to live chat widget.

AI features (optional, all behind feature flags)

Variable	Description
ANTHROPIC_API_KEY	Claude API key — preferred for product description / SEO copy generation.
OPENAI_API_KEY	OpenAI alternative.

Frontend (admin / storefront SSR)

These are read by apps/admin and apps/storefront-astro at build / SSR time:

Variable	Default	Description
NEXT_PUBLIC_API_URL	/api	API base URL exposed to the browser (proxied via Next.js).
API_URL	http://localhost:4000	API URL used by storefront SSR (server-to-server, never reaches the browser).

Quick reference — minimum required for production

To pass validateProductionConfig():

NODE_ENV=production
DATABASE_MODE=postgres
DATABASE_URL=postgres://...

JWT_ACCESS_SECRET=<32+ random chars>
JWT_REFRESH_SECRET=<different 32+ random chars>

# If self-hosting license server, also:
LICENSE_SERVER_ADMIN_TOKEN=<32+ random chars>   # not "dev-*" / "change-me"

Plus, depending on what features the customer enables: payment driver creds (STRIPE_* / NETOPIA_*), email (RESEND_API_KEY), ANAF (ANAF_*), storage (STORAGE_DRIVER + S3_*), shipping (SAMEDAY_* etc.), SMS (SMSLINK_*), encryption (ECOMMUS_DATA_KEY), metrics (METRICS_TOKEN).

See also

• Customer Onboarding — provisioning checklist
• Manual install (advanced) — step-by-step manual setup
• License — JWT shape + tier matrix
• infra/.env.production.template — canonical source of truth
• apps/api/src/config.ts — validateProductionConfig() boot-time enforcement