Self-Hosting Configuration

Environment variables behind the Self-Hosting deployment.

For source development, use Local Setup and the repository's .env.sample. Many values can embed the literal string <subdomain>, which getEnv (utils.ts) replaces with the request tenant at runtime; useful for per-tenant URLs and keys.

Runtime vs build-time

Backend services read everything below from the container environment at startup; restart to apply changes. The Core UI container is different: its entrypoint writes every REACT_APP_* variable into a browser-readable js/env.js at startup, so REACT_APP_* values behave as runtime configuration for erxes/erxes-next-ui even though the same names are baked into the bundle as fallbacks. The standalone apps (client-portal-template, help-center, posclient-front) read NEXT_PUBLIC_* values at their own build or entrypoint time; see their app pages.

Core runtime

Variable	Read by	Required	Default	Notes
`NODE_ENV`	All backend + UI	Yes	none	`production` in deployment; `development` enables dev remotes, router download, and CORS extras
`PORT`	Each service	No	`4000` gateway, `3300` core-api, `3301` logs, `3302` automations, `3303`+ plugins	Per-container override
`VERSION`	core-api, gateway, service discovery	No	`os`	`os` or `saas`; switches `/initial-setup`, plugin discovery, and charge checks
`RELEASE_VERSION`	Plugin APIs on registration	No	none	Values starting with `3.` become the `releaseVersion` used in plugin UI asset URLs; anything else becomes `latest`
`LOAD_BALANCER_ADDRESS`	Every backend service	Recommended in production	derived	Address registered in Redis; defaults to `http://plugin-<name>-api:<port>` in production, `http://localhost:<port>` in dev
`GET_CP_TOKEN`	core-api	Only to enable the route	none	Shared secret for `GET /get-client-portal-token?GET_CP_TOKEN=`
`TEMPLATE_EXPORT_KEY`	core-api	For template export	none	Passphrase hashed to the AES-256-GCM key that encrypts template exports

Database

Variable	Read by	Required	Default	Notes
`MONGO_URL`	All backend services	Yes	`mongodb://127.0.0.1:27017/erxes?directConnection=true`	Must reach all replica-set members from the containers; the logs service derives `<db>_logs` from it
`DB_NAME`	`erxes-api-shared` (saas)	saas only	`erxes_<organizationId>`	Tenant database name template
`CORE_MONGO_URL`	`backend/saas-migrations` scripts	For those migrations	none	Some scripts accept a domain-specific override instead of `MONGO_URL`

Redis

Variable	Read by	Required	Default	Notes
`REDIS_HOST`	All backend services	Yes	none	Shared ioredis client, BullMQ queues, GraphQL pubsub
`REDIS_PORT`	All backend services	No	`6379`	none
`REDIS_PASSWORD`	All backend services	When Redis requires auth	none	Must match the Redis container's `requirepass`; there is no `REDIS_URL`
`SKIP_REDIS`	posclient sync utils	No	none	When set, POS config sync throws `token not found` instead of creating a config for an unknown token

Redis holds service discovery (erxes-service-*, erxesservice:config:*), session tokens (user_token_*), plugin lists (erxes-active-plugins), and every BullMQ queue. Persist it (--appendonly yes) and use noeviction.

URLs, domains, and CORS

Variable	Read by	Required	Default	Notes
`DOMAIN`	gateway, core-api, services	Yes	`http://localhost:3000`	Public UI origin; also the CORS allow-list anchor and the stored `hostname` fallback
`GATEWAY_URL`	core-api email links	No	`${DOMAIN}/gateway`	Public gateway prefix used in emails, unsubscribe links, webhooks
`WIDGETS_DOMAIN`	gateway, core-api	No	`http://localhost:3200`	Widgets origin added to CORS
`ALLOWED_DOMAINS`	gateway, core-api, services	No	none	Extra comma-separated CORS origins
`ALLOWED_ORIGINS`	gateway, core-api, services	No	none	Comma-separated regexes appended to the CORS origin list
`CLIENT_PORTAL_DOMAINS`	logs, automations services	No	none	Extra origins for the background services' CORS
`TRUST_PROXY`	All backend services	No	`loopback, linklocal, uniquelocal`	Express `trust proxy`; widen only if your LB appends client IPs

Auth and sessions

Variable	Read by	Required	Default	Notes
`JWT_TOKEN_SECRET`	gateway, core-api, plugins	Yes	`SECRET`	Signs and verifies user, portal, and app JWTs. Change it and keep it identical on every backend service
`SAME_SITE`	core-api	No	none	Set to `none` to emit cross-site auth cookies where the code supports it
`WORKOS_API_KEY`, `WORKOS_PROJECT_ID`	core-api	For WorkOS SSO	none	SSO login mutations
`OAUTH_DEVICE_VERIFICATION_URI`	core-api	No	built-in	OAuth device-flow verification page override

Plugin and service selection

Variable	Read by	Required	Default	Notes
`ENABLED_PLUGINS`	gateway, core-api, dev scripts	For plugins	none	Comma-separated base names (`sales,operation`); controls gateway waits and `/get-frontend-plugins`
`ENABLED_PLUGINS_ONLY_API`	gateway, dev scripts	No	none	Backend-only plugins without frontend remotes
`ENABLED_SERVICES`	`scripts/start-api-dev.js`	Dev only	none	`automations,logs` → `-service` Nx projects; not* read by Docker images
`MAX_PLUGIN_RETRY`	gateway	No	unlimited	Bounds plugin-join and `/graphql` readiness retries at startup

Gateway tuning

Variable	Read by	Required	Default	Notes
`APOLLO_ROUTER_PORT`	gateway	No	`50000`	Loopback port for the internal router
`INTROSPECTION`	gateway	No	off in production	`true` enables GraphQL introspection in production
`GRAPHQL_LIMITER`	gateway	No	off	When set, applies depth/alias/character limits to `/graphql`
`SUPERGRAPH_POLL_INTERVAL_MS`	gateway (dev)	No	`10000`	Dev-mode recompose interval
`DEBUG_GATEWAY_AUTH`	gateway	No	`false`	Verbose auth, proxy, and limiter request logs

Workers and retention

Variable	Read by	Required	Default	Notes
`LOG_RETENTION_DAYS`	`erxes-api-shared` logs schema	No	`365`	TTL index on the `_logs` database `logs` collection
`REVERT_AUTO_JOURNAL_MAX`	`erxes-api-shared`	No	`1000`	Max documents snapshotted per bulk write for the undo journal
`SEGMENT_CONCURRENCY_CHANGED` / `_FORGET` / `_REBUILD` / `_RECONCILE`	logs-service	No	`10` / `5` / `1` / `3`	BullMQ concurrency per segment queue
`SEGMENT_RECONCILE_CRON` / `_TZ` / `_BATCH` / `_STEPS`, `SEGMENT_REBUILD_PAGE`, `SEGMENT_PREVIEW_BUDGET_MS`, `SEGMENT_TIME_ZONE`	segment engine	No	built-in	Segment sweep tuning
`TIMEZONE`	sales board/POS report queries	No	`0` (hour offset) / `UTC`	Numeric hour offset in sales date math

Email

Variable	Read by	Required	Default	Notes
`SENDGRID_API_KEY`	core-api auth emails	For SendGrid	none	Throws `SENDGRID_API_KEY is missing in environment` when a SendGrid path runs without it
`SENDGRID_WEBHOOK_PUBLIC_KEY`	core-api broadcast trackers	For SendGrid event webhooks	none	Verifies inbound event signatures; a deployment-level key marks the webhook shared
`AWS_SES_ACCESS_KEY_ID`, `AWS_SES_SECRET_ACCESS_KEY`, `AWS_SES_CONFIG_SET`, `AWS_REGION`	broadcast transporter	For SES	none	SES sending path
`DEFAULT_FROM_EMAIL`	`erxes-api-shared` email	No	none	Fallback sender; `COMPANY_EMAIL_FROM` system config overrides per tenant
`EMAIL_DISPOSABLE_DOMAINS`	core-api intake	No	none	Extra disposable-domain list
`EMAIL_PROVEN_WINDOW_DAYS`	core-api	No	`180`	Proven-address window
`EMAIL_RAMP_TIERS`, `EMAIL_SOFT_BOUNCE_LIMIT`	core-api broadcast	No	built-in tiers / `3`	Sending ramp and bounce suppression
`MAIL_DOMAIN`, `MAIL_WORKER_URL`, `MAIL_WEBHOOK_SECRET`, `MAIL_TENANT`, `MAIL_SENDING_ACCOUNT_ID`, `MAIL_SENDING_API_TOKEN`, `MAIL_SENDING_DAILY_LIMIT`, `MAIL_INBOUND_RATE_LIMIT`, `MAIL_RECEIVE_URL`	frontline_api mail channel	For the mail integration	none	Cloudflare Email Routing → worker → `/mail/receive`; see `.env.sample` and the frontline plugin guide

Frontend runtime (`REACT_APP_*`)

Set on the core-ui container; injected into window.env at startup and falling back to build-time values:

Variable	Default	Notes
`REACT_APP_API_URL`	`<proto>//<host>/gateway` (prod), `http://localhost:4000` (dev)	Public gateway URL the browser calls; `<subdomain>` in the value is replaced by the hostname's first label
`REACT_APP_IMAGE_CDN_URL`	none	Image CDN base
`REACT_APP_GOOGLE_MAP_API_KEY`	none	Maps integration
`REACT_APP_HIDE_CORE_MODULES`	none	Hides built-in navigation modules
`REACT_APP_SENTRY_DSN`, `REACT_APP_SENTRY_ENVIRONMENT`	none	Frontend Sentry

Variables on the standalone apps include NEXT_PUBLIC_ERXES_API_URL (client-portal-template, help-center; the latter injects it into env.js via its own docker-entrypoint.sh), NEXT_PUBLIC_ERXES_CP_TOKEN (client-portal-template only), and NEXT_PUBLIC_MAIN_API_DOMAIN, NEXT_PUBLIC_APP_VERSION (posclient-front). Check each app's Dockerfile/entrypoint: a container env override only works where the app injects runtime env; otherwise rebuild after changing them.

Observability

Variable	Read by	Required	Default	Notes
`SENTRY_DSN`, `SENTRY_ENVIRONMENT`, `SENTRY_RELEASE`, `SENTRY_SERVER_NAME`, `SENTRY_TRACES_SAMPLE_RATE`	All backend services	No	off	Sentry error tracing; tag as `plugin`/`service`

Not env vars

Storage and upload settings are system configs stored in the database, read via configs.getConfigs: UPLOAD_SERVICE_TYPE, AWS_BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_COMPATIBLE_SERVICE_ENDPOINT, AWS_FORCE_PATH_STYLE, AWS_PREFIX, GOOGLE_CLOUD_STORAGE_BUCKET, GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_PROJECT_ID, CLOUDFLARE_*, AZURE_STORAGE_*, FILE_SYSTEM_PUBLIC. Set them in Settings → file upload, not in .env.