Run erxes locally, from zero

erxes is an Nx + pnpm monorepo. The backend is a set of Node services that register with a gateway through Redis; the frontend is a React host that loads each plugin's UI over Module Federation. Locally, all of it runs from two terminals.

Git to clone the repo, build tools for native npm modules, and a higher file-watcher limit. Nx and Rspack watch tens of thousands of files, and Ubuntu's default limit runs out.

Apple's command line tools give you git and a compiler for native npm modules. Homebrew installs everything else, including MongoDB and Redis in step 05. Works the same on Apple Silicon and Intel Macs.

# Git, clang, make (a dialog opens; click Install)
xcode-select --install

# Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Apple Silicon only: put brew on your PATH (the installer prints this too)
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Raise the open-file limit for the dev servers, in every new terminal
echo 'ulimit -n 65536' >> ~/.zshrc
ulimit -n 65536

git --version && brew --version && ulimit -n

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl wget ca-certificates gnupg build-essential python3

# Let the dev servers watch the whole monorepo
echo "fs.inotify.max_user_watches=524288" | sudo tee /etc/sysctl.d/99-erxes-watchers.conf
echo "fs.inotify.max_user_instances=1024" | sudo tee -a /etc/sysctl.d/99-erxes-watchers.conf
sudo sysctl --system

git --version && gcc --version | head -1 && cat /proc/sys/fs/inotify/max_user_watches

erxes CI builds on Node 22. Install it through nvm rather than apt or brew so you never need sudo for global packages and can switch versions per project.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# Load nvm into this shell (new terminals load it automatically)
export NVM_DIR="$HOME/.nvm"
. "$NVM_DIR/nvm.sh"

nvm install 22
nvm alias default 22

node -v && npm -v

v22.x.x and 10.x.x

The repo pins "packageManager": "pnpm@9.12.3" and blocks npm and yarn. Use the same version so pnpm-lock.yaml resolves the same way.

npm install -g pnpm@9.12.3

pnpm -v

9.12.3

Pick one approach. Docker keeps your OS clean and makes it easy to wipe or upgrade the databases. Native packages (aptHomebrew) start faster and use less RAM.

# Docker Desktop (free for personal use and small companies)
brew install --cask docker
open -a Docker   # wait until the whale icon in the menu bar stops animating

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Run docker without sudo (log out and back in afterwards)
sudo usermod -aG docker $USER

mkdir -p ~/erxes-infra && cd ~/erxes-infra

cat > docker-compose.yml <<'EOF'
services:
  mongo:
    image: mongo:7
    container_name: erxes-mongo
    restart: unless-stopped
    ports:
      - "127.0.0.1:27017:27017"
    volumes:
      - mongo-data:/data/db

  redis:
    image: redis:7-alpine
    container_name: erxes-redis
    restart: unless-stopped
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - redis-data:/data

volumes:
  mongo-data:
  redis-data:
EOF

docker compose up -d

docker compose ps
docker exec erxes-mongo mongosh --quiet --eval 'db.runCommand({ ping: 1 })'
docker exec erxes-redis redis-cli ping

brew tap mongodb/brew
brew install mongodb-community@8.0 redis

brew services start mongodb-community@8.0
brew services start redis

brew services list
mongosh --quiet --eval 'db.runCommand({ ping: 1 })'
redis-cli ping

curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc \
  | sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg --dearmor

echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] \
https://repo.mongodb.org/apt/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME")/mongodb-org/8.0 multiverse" \
  | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list

sudo apt update
sudo apt install -y mongodb-org
sudo systemctl enable --now mongod

sudo apt install -y redis-server
sudo systemctl enable --now redis-server

systemctl is-active mongod redis-server
mongosh --quiet --eval 'db.runCommand({ ping: 1 })'
redis-cli ping

One pnpm install at the root installs every backend service, plugin and UI in the workspace. Expect 5–15 minutes and a few GB in node_modules the first time.

cd ~
git clone https://github.com/erxes/erxes.git
cd erxes
pnpm install

pnpm nx show projects | head -20

a list including core-api, gateway, core-ui, sales_api, sales_ui…

Every backend service and both dev scripts read the root .env. Start from the sample, then set the values below.

cp .env.sample .env

# Generate a JWT secret and paste it into .env
openssl rand -hex 32

NODE_ENV=development

# Data
MONGO_URL=mongodb://localhost:27017/erxes?directConnection=true
REDIS_HOST=localhost
REDIS_PORT=6379

# URLs
DOMAIN=http://localhost:3001
ALLOWED_DOMAINS=http://localhost:3001,http://localhost:4000
REACT_APP_API_URL=http://localhost:4000

# Plugins to boot: each name maps to backend/plugins/<name>_api and frontend/plugins/<name>_ui
ENABLED_PLUGINS=frontline,sales

# Paste the output of: openssl rand -hex 32
JWT_TOKEN_SECRET=replace-with-your-random-64-char-hex

# Give each Node process enough heap for the TypeScript build
NODE_OPTIONS=--max-old-space-size=1536

Use two terminals, both in ~/erxes. Start the backend first so the gateway is ready when the UI asks for its schema.

Terminal 1: backend

pnpm dev:apis

Starts core-api, gateway and every <plugin>_api listed in ENABLED_PLUGINS. The first boot compiles TypeScript, so give it 1–3 minutes. It's ready when each service has printed a line like:

🚀 core graphql api ready at http://localhost:3300/graphql
🚀 sales graphql api ready at http://localhost:3305/graphql
🚀 frontline graphql api ready at http://localhost:3304/graphql

Terminal 2: frontend

pnpm dev:uis

Generates the GraphQL types for the enabled plugin UIs, then serves core-ui on :3001 with each plugin UI as a dev remote. Wait for Rspack to print compiled successfully.

On an empty database erxes has no users, so the first visit sends you to the create-owner page.

1. Open http://localhost:3001.
2. Fill in your name, email and a password. This becomes the workspace owner with every permission.
3. Sign in with the same credentials. Each plugin in ENABLED_PLUGINS shows up in the left navigation.

Run these from a third terminal when something looks off. Work from the bottom layer up: if Redis fails, nothing above it will work.

# Data layer
redis-cli ping                                   # or: docker exec erxes-redis redis-cli ping
mongosh --quiet --eval 'db.runCommand({ping:1})' # or: docker exec erxes-mongo mongosh ...

# Services
curl -s http://localhost:3300/health; echo   # core-api
curl -s http://localhost:4000/health; echo   # gateway
curl -s http://localhost:3305/health; echo   # sales_api
curl -s http://localhost:3304/health; echo   # frontline_api

# What is listening on the erxes ports?
ss -tulpn | grep -E ':(3001|3300|3304|3305|4000|6379|27017)\b'lsof -nP -iTCP -sTCP:LISTEN | grep -E ':(3001|3300|3304|3305|4000|6379|27017) '

The failures people hit most on a first run, from the bottom of the stack up.

ss -tulpn | grep ':4000'        # shows pid=12345
kill 12345

lsof -nP -iTCP:4000 -sTCP:LISTEN   # PID is the second column
kill 12345

pnpm install
pnpm nx reset
pnpm nx build erxes-api-shared