# Deploy & Operate

Deployment, configuration, migrations, upgrades, and troubleshooting for self-hosted erxes


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](https://erxes.io/docs/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](https://erxes.io/docs/self-hosting) 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](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/.github/workflows/release.yml) 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

- [Deployment](https://erxes.io/docs/self-hosting): Deploy erxes on your own server with Docker Compose: requirements, images, and first run
- [Configuration](https://erxes.io/docs/self-hosting-configuration): Environment variables behind the deployment template
- [Database Migrations](https://erxes.io/docs/self-hosting-migrations): Back up and migrate MongoDB across versions
- [Upgrades](https://erxes.io/docs/self-hosting-upgrades): Choose compatible images and roll back safely
- [Logs & Troubleshooting](https://erxes.io/docs/self-hosting-troubleshooting): Diagnose health, composition, and plugin loading