Setup & Deployment

Local installation

The following documentation will guide you through the installation of an erxes project using Docker.

Docker is an open platform that allows to develop, ship and run applications by using containers (i.e. packages containing all the parts an application needs to function, such as libraries and dependencies).

Preparing the installation

erxes installation requires at least four software prerequisites to be already installed on your machine:

✋ Caution

Erxes code takes approximately 12GB storage space, make sure you have enough space in your device before going forward.

Prerequisites

Git
Node.js: only LTS versions are supported v18.17.1 or higher. Other versions of Node.js may not be compatible with the latest release of erxes. The 18.17.x version is most recommended by erxes. The easier way to install nvm is here.
npm and yarn (latest version) to run the erxes.
Docker Latest version.

Installing erxes

Create an empty folder.

mkdir example

Navigate to your newly created folder where the new erxes project will be set up. This directory will define the database and erxes plugins to use.

cd example

Run the following command in the folder.

git clone https://github.com/erxes/erxes.git

Installing dependencies using docker

In the folder, create a dock directory using the following command.

mkdir dock

Go to the dock folder using the following command.

cd dock

✏️ Note

Run sudo nano or sudo vim command to create the .yml file.

Create a docker-compose.yml file, then copy the following script into the newly created file.

version: '3.6'
services:
  mongo:
    hostname: mongo
    image: mongo:4.0.10
    # container_name: mongo
    ports:
      - "27017:27017"
    networks:
      - erxes-net
    healthcheck:
      test: test $$(echo "rs.initiate().ok || rs.status().ok" | mongo --quiet) -eq 1
      interval: 2s
      timeout: 2s
      retries: 200
    command: ["--replSet", "rs0", "--bind_ip_all"]
    extra_hosts:
      - "mongo:127.0.0.1"
    volumes:
      - ./data/db:/data/db

  redis:
    image: 'redis'
    # container_name: redis
    # command: redis-server --requirepass pass
    ports:
      - "6379:6379"
    networks:
      - erxes-net

  rabbitmq:
    image: rabbitmq:3.7.17-management
    # container_name: rabbitmq
    restart: unless-stopped
    hostname: rabbitmq
    ports:
      - "15672:15672"
      - "5672:5672"
    networks:
      - erxes-net
    # RabbitMQ data will be saved into ./rabbitmq-data folder.
    volumes:
      - ./rabbitmq-data:/var/lib/rabbitmq
  
  elasticsearch:
    image: 'docker.elastic.co/elasticsearch/elasticsearch:7.13.0'
    container_name: 'elasticsearch'
    environment:
      - discovery.type=single-node
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 32768
        hard: 65536
    ports:
      - '127.0.0.1:9200:9200'
    networks:
      - erxes-net
    volumes:
      - ./elasticsearchData:/usr/share/elasticsearch/data

  essyncer:
    container_name: essyncer
    image: 'erxes/essyncer:dev'
    environment:
      DB_NAME: 'erxes'
      ELASTICSEARCH_URL: 'http://elasticsearch:9200'
      MONGO_URL: 'mongodb://mongo:27017/erxes?replicaSet=rs0'
    depends_on:
      - 'mongo'
      - 'elasticsearch'
    volumes:
      - './essyncerData:/data/essyncerData'
      - './mongoConnectorLog:/var/log/mongo-connector'
    tty: true
    networks:
      - 'erxes-net'

networks:
  erxes-net:
    driver: bridge

💡 Tip

Please find the useful commands when you're working on Docker

In the folder where the above file is located, run the following command:

sudo docker-compose up -d

Go back to the erxes folder using the following command.

cd ../erxes

Switch to the dev branch by using the following command.

git checkout dev

In erxes folder, Install node modules by using the following command.

yarn install

Install pm2 by using the following command.

sudo npm install -g pm2

Running erxes

✋ Caution

Run erxes in erxes/cli directory

Run the following command to change the folder.

cd cli

Install node modules in the erxes/cli directory.

yarn install

Copy configs.json.sample, then convert it to configs.json.

cp configs.json.sample configs.json

Add "ui": "local" under every plugin names like shown in below, in configs.json.

✋ Caution

You do not have to add it under logs plugin since it has no ui.

 {
    "name": "inbox",
    "ui": "local"
 },

Run the following command to start your erxes project.

./bin/erxes.js dev

If your browser doesn't automatically jump to localhost:3000, you should check logs by using these commands.

💡 Tip

Frequently used pm2 commands on erxes:

pm2 list - Displays all processes status
pm2 kill - Will remove all processes from pm2 list
pm2 logs -f - Displays all processes logs in streaming (gateway, plugin-name etc.)
pm2 restart all - Restarts all processes

If you see this screen, you have successfully installed erxes XOS. Congratulations 🎉🎉🎉

Server installation

The following documentation will guide you through the installation of an erxes project using Docker image via Dockerhub that can be used on Ubuntu/CentOS in order to use erxes. This the guideline will be dedicated to anyone who is about to use erxes for their businesses. If you want to customize or develop additional plugins on erxes, please go to the developer installation guideline.

Docker is an open source platform that allows to develop, ship and run applications by using containers (i.e. packages containing all the parts an application needs to function, such as libraries and dependencies).

Prerequisites

You will need following things before dive into erxes installation.

any type of server with 8 core cpu & atleast 16gb ram
basic knowledges to work on ubuntu/centos operating system such as execute commands in user directory
domain controller's A record must pointed to the instance you are going to install erxes on
ability to connect to your instance via ssh protocol

Installation steps

1. Create install.sh file using text editors such as nano or vim. Then copy the following content into install.sh. Following script will install nginx, certbot, docker, docker-compose and nodejs into your server.

 #!/bin/bash
  now=$(date +'%H:%M:%S')
  echo -e "\e[1mStep 1 $now : Updating \e[0m"
sudo apt-get update -y
  now=$(date +'%H:%M:%S')
  echo -e "\e[1mStep 2 $now : Installing nginx\e[0m"
sudo apt install nginx -y
sudo apt update -y
  now=$(date +'%H:%M:%S')
  echo -e "\e[1mStep 3 $now : Installing docker\e[0m"
sudo apt install apt-transport-https ca-certificates curl software-properties-common -y
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"
apt-cache policy docker-ce
sudo apt install docker-ce -y
  now=$(date +'%H:%M:%S')
  echo -e "\e[1mStep 5 $now : Installing docker compose\e[0m"
sudo apt-get update -y
sudo curl -L "https://github.com/docker/compose/releases/download/1.27.4/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
  now=$(date +'%H:%M:%S')
  echo -e "\e[1mStep 6 $now : Installing ndoejs\e[0m"
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
curl -s https://deb.nodesource.com/setup_18.x | sudo bash
sudo apt-get install nodejs -y
  now=$(date +'%H:%M:%S')
  echo -e "\e[1mStep 7 $now : Installing awscli \e[0m"
sudo apt-get install awscli -y
  now=$(date +'%H:%M:%S')
  echo -e "\e[1mStep 8 $now : Installing npm\e[0m"
sudo apt install npm -y
  now=$(date +'%H:%M:%S')
  echo -e "\e[1mStep 9 $now : Enter your domain address to configure erxes\e[0m"
sudo npm install -g create-erxes-app -y

2. Before executing the script use the below command to make the install.sh file executable.

sudo chmod +x install.sh

3. Execute install.sh file.

./install.sh

Create an erxes user on the instance

Assuming you have connected to your instance and ready to execute following steps. First you need to create erxes user because all erxes related installation scripts are made for an erxes user. Why? You don't want to use root user to administer your server. So everything will be done by a user called, erxes. To accomplish this, run the following command:

adduser erxes

When prompted, enter unique & strong password. (Finish adding the user simply by pressing the enter or return key through the questions)

Grant sudo and docker rights to erxes user by following command::

usermod -aG sudo erxes

usermod -aG docker erxes

su - erxes

All prerequisites are completed and now you can proceed to the installation steps.

Starting erxes project

1. Below command will trigger the erxes installation process.

create-erxes-app erxes

After the execution it will ask for your erxes domain name

https://example.com

✏️ Note

Please use a full domain or subdomain names including http socket like below

2. After the above command erxes directory will be created. That includes following files in it docker-compose.yml, configs.json, package.json, package-lock.json. In order to change to erxes directory use below command.

cd /home/erxes/erxes

3. Change erxes package version of /home/erxes/erxes/package.json file to latest version.

{
  "name": "erxes",
  "private": true,
  "version": "0.1.0",
  "scripts": {
    "erxes": "erxes"
  },
  "dependencies": {
    "amqplib": "^0.8.0",
    "create-erxes-app": "0.0.28",
    "dup": "^1.0.0",
    #Change here
    "erxes": "change me",
    "ip": "^1.1.5",
    "up": "^1.0.2"
  }
}

If the erxes version has been changed in the package.json file, run the command below to install the necessary modules for erxes.

npm install

4. Now you need to initiate docker swarm mode in order to do that use following command.

docker swarm init

✏️ Note

If you get a permission denied warning when you run this command, you haven't run the usermod -aG docker erxes command.

docker network create --driver=overlay --attachable erxes

✏️ Note

In erxes directory we have docker-compose.yml file even with that we do not use docker-compose up, docker-compose down, docker-compose restart commands further

5. Before starting the application services we need to start the databases. The following command will start database services.

openssl rand -base64 756 > mongo-key
sudo chmod 400 mongo-key && sudo chown 999:999 mongo-key
openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem --batch
cat key.pem certificate.pem > mongo.pem

Running elasticsearch

If your server is bigger than our required size you can use erxes with elasticsearch. To do that the following steps need to be taken.

Add the following lines to configs.json, positions do not matter.

"essyncer": {},
"elasticsearch" : {},

Then run and deploy dbs with following command.

npm run erxes deploy-dbs

6. To check database services up use following command it will shows you all the running docker services id, name and state etc.

docker ps -a | grep mongo

wait until all services' state become up.

7. Now we need to make our mongo have a replica set. First we need to enter the mongo container then enter the mongo instance then execute the 3 following commands.

docker exec -it <mongo container name> bash
mongo -u erxes -p <auto generated in configs.json>
rs.initiate();

✏️ Note

You may want to hit return or enter button a few times, if we have done it correctly mongo shell will changes into "RS0: primary"

To quit mongo instance and container run exit command twice.

8. Now we need to create locales directory in our working directory /home/erxes/erxes to do that use the following command.

mkdir locales

9. Change erxes version of /home/erxes/erxes/configs.json file to latest version. It is the latest version that has undergone further development.

To start the application services like erxes core uis and gateway services we need to run the following command.

npm run erxes up -- --uis

After this step the ui will be downloaded from AWS:s3 so make sure your server can communicate AWS instances without a problem.

✏️ Note

Containers are generated one by one, so wait until they finish reading. Meanwhile check for the status using

docker ps -a

To check docker services use

docker service ls

all erxes services needs to be up state Wait until the gateway container status becomes healthy. Additionally, ensure that the gateway container is the last one to start.

10. Now we need to configure our web server, we need to configure our nginx first. To do this, we create an nginx config file named erxes.conf in /etc/nginx/sites-enabled. To do this, use the following command.

sudo nano /etc/nginx/sites-enabled/erxes.conf

Copy the nginx configuration below

server {
        server_name example.com;
        index index.html;
        client_max_body_size 50M;
        client_header_buffer_size 32k;

        location / {
                access_log /var/log/nginx/erxes-front.access.log;
                error_log /var/log/nginx/erxes-front.error.log;
                proxy_pass http://127.0.0.1:3000;
                proxy_http_version 1.1;
                proxy_redirect off;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-Host $host;
                proxy_set_header X-Forwarded-Server $host;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
        }

        location /widgets/ {
                access_log /var/log/nginx/erxes-widgets.access.log;
                error_log /var/log/nginx/erxes-widgets.error.log;
                proxy_pass http://127.0.0.1:3200/;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection 'upgrade';
                proxy_set_header Host $host;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_http_version 1.1;
        }

        location /gateway/ {
                access_log /var/log/nginx/erxes-api.access.log;
                error_log /var/log/nginx/erxes-api.error.log;
                proxy_pass http://127.0.0.1:3300/;
                proxy_http_version 1.1;
                proxy_buffering off;
                proxy_redirect off;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-Server $host;
                proxy_set_header X-Forwarded-Host $host;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "Upgrade";
        }

        location /mobile-app/ {
                access_log /var/log/nginx/erxes-mobile-app.access.log;
                error_log /var/log/nginx/erxes-mobile-app.error.log;
                proxy_pass http://127.0.0.1:4100/;
                proxy_http_version 1.1;
                proxy_buffering off;
                proxy_redirect off;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-Server $host;
                proxy_set_header X-Forwarded-Host $host;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "Upgrade";
        }

        location /integrations/ {
                access_log /var/log/nginx/erxes-integrations.access.log;
                error_log /var/log/nginx/erxes-integrations.error.log;
                proxy_pass http://127.0.0.1:3400/;
                proxy_http_version 1.1;
                proxy_redirect off;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-Host $host;
                proxy_set_header X-Forwarded-Server $host;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
        }
        location /dashboard/front {
                access_log /var/log/nginx/erxes-integrations.access.log;
                error_log /var/log/nginx/erxes-integrations.error.log;
                proxy_pass http://127.0.0.1:4200;
                proxy_http_version 1.1;
                proxy_redirect off;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-Host $host;
                proxy_set_header X-Forwarded-Server $host;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
        }

        location /dashboard/api/ {
                access_log /var/log/nginx/erxes-integrations.access.log;
                error_log /var/log/nginx/erxes-integrations.error.log;
                proxy_pass http://127.0.0.1:4300/;
                proxy_http_version 1.1;
                proxy_redirect off;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-Host $host;
                proxy_set_header X-Forwarded-Server $host;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
        }
    }

11. After that we need to test the nginx config. To do that use following command.

sudo nginx -t

12. If nginx test shows successful message we need to restart Nginx. To do that use the following command.

sudo service nginx restart

13. Erxes only works in secure connection to generate free ssl certificate we use Certbot. To configure that use the following command.

sudo certbot --nginx

✏️ Note

you have to point your domain's A record to your erxes host machine in order to get certificate without that certbot will not generate certificate order.

After entering this command, provide your email and subscription information, and accept the terms. Following that, you will be prompted about the 'redirect' option. We highly recommend enabling this option for security reasons. Once these steps are completed, open your browser and enjoy our product.

Adding new plugins to erxes

Adding new plugins to erxes is an easy task, all you need to do is add a plugin name under "plugins:"[{}] in /home/erxes/erxes/configs.json file then run npm run erxes up -- --uis command. But for some plugins like dashboard, it require some extra service we will discuss that in another section. Below we have the ideal configs.json file content that includes every nessacery configuration lines for all plugins. Please read the following contents carefully some lines may need a replacement.

{
    "jwt_token_secret": "will be generated in configs.json",
    "db_server_address": "ip address of your machine",
    "secondary_server_address": "",
    "image_tag": "dev",
    "domain": "https://example.com",
    "widgets": {
        "domain": "https://example.com/widgets"
    },
    "elasticsearch": {},
    "essyncer": {},
    "redis": {
        "password": "will be generated in configs.json"
    },

    "mongo": {
        "username": "erxes",
        "password": "will be generated in configs.json",
    },
    "rabbitmq": {
        "cookie": "",
        "user": "erxes",
        "pass": "will be generated in configs.json",
        "vhost": ""
    },

    "plugins": [
        {
            "name": "inbox",
            "extra_env": {
                "INTEGRATIONS_MONGO_URL": "will be generated in docker-compose-dbs.yml",
                "FB_MONGO_URL": "will be generated in docker-compose-dbs.yml"
            }
        },
        {
            "name": "cards"
        },
        {
            "name": "contacts"
        },
        {
            "name": "internalnotes"
        },
        {
            "name": "notifications"
        },
        {
            "name": "automations",
            "db_name": "erxes_automations"
        },
        {
            "name": "products"
        },
        {
            "name": "forms"
        },
        {
            "name": "inventories"
        },
        {
            "name": "segments"
        },
        {
            "name": "tags"
        },
        {
            "name": "engages"
        },
        {
            "name": "logs",
            "db_name": "erxes_logger"
        },
        {
            "name": "clientportal",
            "extra_env": {
                "JWT_TOKEN_SECRET": ""
                    }
        },
        {
            "name": "webbuilder"
        },
        {
            "name": "knowledgebase"
        },
        {
            "name": "emailtemplates"
        },
        {
            "name": "integrations",
            "db_name": "erxes_integrations",
            "extra_env": {
                "ENDPOINT_URL": "https://enterprise.erxes.io"
            }
        },
        {
            "name": "dashboard"
        },
        {
            "name": "documents"
        },
        {
            "name": "filemanager"
        },
        {
            "name": "facebook",
            "extra_env": {
                "ENDPOINT_URL": "https://enterprise.erxes.io",
                "MONGO_URL": "will be generated in docker-compose-dbs.yml"
            }
        }
    ]
}

Removing erxes

1. First, it is unfortunate, but every server needs to be kept tidy. The following commands will help remove the Docker stack and any dangling containers in the swarm.

docker stack ls

will show you stack informations. To leave that use the following command.

docker stack rm erxes
docker stack rm erxes-dbs

2. To remove all dangling containers use the following commands.

List and remove all dangling images.

docker images -f dangling=true
docker rmi $(docker images -q -f dangling=true)

List and remove all dangling containers.

docker ps -a -f status=exited
docker rm $(docker ps -a -q -f status=exited)

List and remove all dangling volumes

✏️ Note

volumes might have data in it so do it with your responsibility

docker volume ls -f dangling=true
docker volume rm $(docker volume ls -q -f dangling=true)

Installation video

Joining erxes community

Join the erxes community today! If you encounter any difficulties during the installation process, don't hesitate to reach out for assistance. You can create issues on our Github repository or seek help from our friendly community on Discord. We're here to support you every step of the way!