Deploy & Operate

Deploy erxes on your own infrastructure and keep it running: installation, environment variables, database migrations, upgrades, and troubleshooting. For running the source on a laptop instead, use Local Setup.

The reference deployment is a single-server Docker Compose stack (Core UI, Core API, gateway, logs-service, and Redis) behind an Nginx HTTPS proxy, backed by a MongoDB replica set you provision yourself. The repository includes Dockerfiles and CI workflows but no Compose file or installer; Deployment derives a working template from them, and the remaining guides cover the lifecycle after first boot.

Before you deploy

• MongoDB replica set. Required, not optional: plugins use sessions and transactions (some wrap writes in startSession). Your MONGO_URL must resolve every advertised replica member from inside the containers and grant access to both the application database and its <db>_logs database, which the logs service writes to.
• Redis. A persistent redis:7 instance on the private network (the template enables AOF and noeviction). Redis holds service-discovery keys, user session tokens, and all BullMQ queues; losing it drops queued work and logs everyone out. There is no REDIS_URL; services read REDIS_HOST/REDIS_PORT/REDIS_PASSWORD.
• DOMAIN and GATEWAY_URL. Set to https://<host> and https://<host>/gateway. They set the gateway's CORS allow-list and the links the platform generates. The Core UI container needs REACT_APP_API_URL pointed at the same gateway URL.
• JWT_TOKEN_SECRET. One random value, identical on the gateway, Core API, every plugin API, and the background services; it signs team-member sessions, portal tokens, and app tokens. A mismatch silently invalidates logins.
• Pinned image tags. Prefer :<version> release tags or repository@sha256: digests over floating latest for the erxes/erxes-next-* images, so rollback is a config change. The release workflow re-tags the image matrix on each release tag. erxes/erxes-next-migrations is not in that matrix; pin it by latest or digest.
• LOAD_BALANCER_ADDRESS per service. Without it a production service registers http://plugin-<name>-api:<port> in Redis, which must resolve inside your Docker network.
• ENABLED_PLUGINS on both Core API and the gateway. Comma-separated base names (sales,operation). The gateway waits for every listed API to register and serve its subgraph before it listens. Deploy every listed plugin, or remove it from the list.

Guides