CE Step by Step Installation
#
Installing the Community EditionThe following instructions take you through step by step and have you install erxes in the same way as the Quickstart installation instructions. For most developers, the Quick Start Installation is better.
#
First steps: Setting up a server with Ubuntu 18.04You must have an account with your hosting provider prior to doing these steps.
- Choose a server size that corresponds with the minimum requirements for these Step by Step instructions:
- Ubuntu 18.04 installed and running
- 1 CPU
- minimum 1GB RAM
- ability to to SSH into the server
- If you're using a subdomain, then the subdomain must be created with your hosting provider hosting your main domain's website or app. The DNS needs to be pointed to your server. (See below)
#
Configure your DNS Records to point at your serverYour server will have an ip address. You will need to point your domain name to your new server.
- If you are using a subdomain, you will need to follow the instructions of updating the `A Records' of the hosting company for your website.
- If you are NOT using a subdomain, then you will need to follow the instructions of your domain name registrar.
Example with a domain called, example.com
If your domain name is example.com, and the ip address assigned to your server is 44.123.32.12, then you will have two A records
that look like this:
Type | Name | Value |
---|---|---|
A | www.example.com | points to 44.123.32.12 |
A | example.com | points to 44.123.32.12 |
Example with a subdomain called, erxes.example.com
You first need to create a subdomain. For example, "erxes.example.com". Then you need to edit the DNS.
If your domain name is erxes.example.com, and the ip address assigned to your server is 44.123.32.12, then you will have a two A records
that look like this:
Type | Name | Value |
---|---|---|
A | erxes.example.com | points to 44.123.32.12 |
A | www.erxes.example.com | points to 44.123.32.12 |
Note: You do not need to create a subdomain called "erxes.example.com", you can use another name of your choice such as "admin.example.com".
#
Log into server as root and create erxes userOpen the terminal or command prompt on your computer. You will need your IP address. (In this example, 44.123.32.12). Type yes
, when asked if you want to continue connecting.
(Note: Some people get an error, WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!, please see the solution here.)
You don't want to use the root user to administer your server. So everything will be done by a user called, erxes. To accomplish this, run the following commands:
Add a user called "erxes". When prompted, enter in a unique password. You will need to keep this password available, as later operations will require using it.
(Finish adding the user simply by pressing the enter
or return
key through the questions.)
Grant the erxes user adminstrative rights.
Your next step, still as root user, is to set-up a basic firewall for your server.
#
Set-up a basic firewall for SSH, nginx 80 and port 443#
Basic Firewall - Port 22Allow OpenSSH with ufw. OpenSSH will use port 22.
Enable ufw
- Type
y
when asked, "Command may disrupt existing ssh connections. Proceed with operation (y|n)?"
Check the ufw status
You should have an output like below:
#
HTTP & HTTPS - Port 80 & Port 443Allow HTTP (port 80) and HTTPS (port 443) with ufw
Check the ufw status
You should have an output like below:
#
Allow the "erxes" user to SSH into serveropen the sshd_config
file to edit
Scroll down until you see
PasswordAuthentication
. Change it fromPasswordAuthentication no
toPasswordAuthentication yes
. NOTE: Some servers have this line commented out with a#
, like# PasswordAuthentication no
. You will need to uncomment it by deleting the#
.The line should look like this:
- Save and exit with
ctrl + x
and theny
to accept the changes.
Reload the SSH config file
Exit from server, so that you can log back in as the erxes user
You have created a new user called, erxes and you set-up a basic firewall to protect your server against malicious attacks.
Please continue with the following steps to log in to your server as the erxes user.
#
Log in to your server as the "erxes" user.Before you can log into your new server, we need to add the SSH key to your local computer.
NOTE: You need to use the IP address of your server.
- Run the following command and create a new password.
Now you can log into your server as the erxes user.
- Log back into the server as the erxes user. You will need your IP address. (In this example, 44.123.32.12). Enter your previously created password, if prompted.
In the following sections, you will install software dependencies that are needed to run erxes.
#
Nvm installNode Version Manage (nvm) is a tool that allows you to download and install Node.js. You can read more about the installation process here: How to install NVM
Install nvm and initialize by reloading the shell configuration. (Run the following commands separately.)
Verify nvm is installed by running:
You should get a similar output as below:
You are ready to continue with installing Node.js.
#
Install Node.js with nvmYou can read more about installing Node.js with nvm here: How to install Node.js with NVM
Install Node.js
Check to see if Node.js is installed correctly.
You should get a similar output as below:
With Node.js installed, you can continue with installing Yarn.
#
Yarn installYarn is a package manager. The alternative is npm. We recommend yarn. For additional yarn installation instructions, read this.
Install yarn. (Run the following commands separately.)
Check to see if yarn is installed correctly
You should get a similar output as below:
As long as you received a version response to yarn --version
, then you can continue and install MongoDB.
#
Install MongoDBMongoDB is a robust and general purpose document-based database. For additional MongoDB installation instructions, read this.
Erxes supports MongoDB version 3.6+ is supported. Previous versions are not supported.
Install MongoDB. (Run the following commands separately.)
Start and enable MongoDB. (Run the following commands separately.)
- Check to see if MongoDB is installed correctly
As long as you received a version response to mongod --version
, then you can continue below.
#
Deploy a MongoDB Replica SetMongoDB replica sets add an extra layer of redundancy and help with load balancing. They are a group of mongod processes that maintain matching data sets. You can read about replication here.
Stop the mongod processes
Open mongod.conf
Enable the replicaset settings, by searching for #replication
. Remove the #
to activate it and edit to include the set name, as follows:
- Save and Exit with
ctrl + x
and theny
to accept the changes.
Restart mongob
Connect to mongo shell
Initialize replicaSet
- You should have an output similar to below. Verify SECONDARY changes to Primary by pressing enter several times.
- press
ctrl-c
to quit mongo
If you were able to return to the command line prompt. Then you may continue with installing and configuring NGINX.
#
Install and configure NGINXNGINX is a very powerful web server. It is often used as a proxy server for emails. For additional NGINX installation instructions, read this.
NGINX is installed from the stable repo https://launchpad.net/~nginx/+archive/ubuntu/stable.
Add the PPA for NGINX. Press enter
when prompted to continue. (Run the following commands separately.)
- Press Enter to continue with the installation. You should be using Ubuntu 18.04.
Install NGINX with the following commands.
NGINX started by default when you installed it. But it is recommended to enable
and start
anyway.
Enable and start NGINX
#
Configure NGINXThe next step is to configure NGINX so that it allows traffic through Ports 80 and 443
.
Ensure the ufw
firewall knows about the available applications.
You are expecting the following output:
The output should look something like the Available applications
output above. Nginx Full
should be listed.
Enable Port 80 and Port 443 to allow traffic.
Verify that ufw
has been updated.
You are expecting the following output.
Your output should match the above output. Providing your output matches the above, you may continue to configuring NGINX.
#
Configure NGINXThe next step is to create a server block with the correct directives to work with the erxes installation.
- Create a new file in the correct directory, and name it your domain name. For example, if your domain name is
erxes.example.com
, name the file,erxes.example.com
.
- Copy the below NGINX server block into the open file. DO NOT SAVE THE FILE until you replace the
YOUR_DOMAIN_COM
with your actualdomain name
.
- After replacing
YOUR_DOMAIN_COM
with your actual domain name. Save withctrl + x
and theny
to accept the changes. - Enable the file by creating a link form it to sites-enabled. Make sure to use your domain name exactly as you created the file above. Replace
YOUR_DOMAIN_COM
with your actual domain name.
- Open the nginx.conf
- Uncomment the following line
server_names_hash_bucket_size 64;
It should look like this:
Save with
ctrl + x
and theny
to accept the changes.Test the NGINX configuration to make sure you don't have any errors
You should see the following output:
If you got no errors, reload nginx service.
Now you are ready to install the SSL Certificates using Let's Encrypt and Certbot.
#
Install Let's Encrypt using CertbotLet's Encrypt enables you to use HTTPS on your website. It will issue you a certificate which shows that you control your domain. Let's Encrypt additional information.
You will follow the installation instructions as covered here, with Certbot
- You will need to add a Certbot PPA to the list of repositories on the server. (Run the following commands separately.)
- Install Certbot
Execute Certbot.
You will asked several questions, you can answer as follows:
Enter your email address
Agree with the Terms of Service
Answer
Yes
orNo
, if you want to share your email address with the Electronic Frontier FoundationSelect the corresponding number associated with your domain name, usually
1
Choose
2
to redirect all your traffic to a secure HTTPSNow run the following to test and set-up automatic renewal of your 90 day certbot. This needs to succeed so that your renewals are automatic.
Check your website in the browser. You should see the Secure Padlock next to your URL. You are now ready to move onto the final steps to install erxes itself.
#
Install erxesAll the dependencies for erxes are now installed. You have also configured your server. Follow these remaining steps to complete the installation of erxes.
#
Download, extract and install each of the erxes components- Create the empty folder directories for the installation of erxes.
NOTE: COPY THE ENTIRE CODE BLOCK AS ONE COMMAND.
- Individually download and extract each of these 8 packages. (These commands place them in the proper installation directories.)
NOTE: COPY THE ENTIRE CODE BLOCK AS ONE COMMAND.
- Install package dependencies (using
yarn install
) required for the packages that make up erxes.
NOTE: COPY THE ENTIRE CODE BLOCK AS ONE COMMAND.
NOTE: This step can take a few minutes to complete.
After successfully each of the above packages, you may continue and install PM2.
#
Install PM2PM2 is a tool that helps you manage and keep erxes online. It is a process manager. You can read more about the installation process here: How to install PM2
- Install PM2
- Check to see if PM2 is installed correctly.
You should get a similar output as below:
You should receive a response from pm2 --version
. The version should show as last line. You will need PM2 later in the installation process. For now, continue on with the next steps to install Yarn.
ecosystem.config.js
#
Configure PM2 In the following steps, you will copy and create an ecosystem.config.js
file that PM2 uses to manage the processes behind erxes. Before it will work, you need to provide your exact URL and a password to encrypt all the communication between your front-end and your server.
- Create and open a new
ecosystem.config.js
file.
- Copy the following content into the file. SAVE THE FILE AS-IS WITHOUT ANY CHANGES*.
The next step is to set environment variables so that we can easily populate the ecosystem.config.js file.
- Run the following command, but replace
YOUR_ACTUAL_DOMAIN_COM
with your actual domain name.
- Run the following command to create a secret token.
- Run each script below, to update your DOMAIN_NAME_COM* in the ecosystem.config.js
- Run each script below, to update your SECRET_PASSWORD_TOKEN* in the ecosystem.config.js
- Start PM2
- Generate a startup script. Copy/paste the script in the terminal and run it.
The above will generate a script like this: DO NOT USE THIS EXAMPLE - USE YOURS GENERATED IN THE TERMINAL
- Now copy your output. Similar to the below.
- Save all the applications that PM2 is managing.
- Verify all process are running.
The status of all the processes should say online.
#
Configure frontend environment variablesIn the previous step, you set environment variables using PM2, but PM2 does not have access to the bundled front-end static code. Therefore, you need to set the environment variables needed from the front-end differently.
- Open the appropriate
env.js
file in the nano editor.
- Copy the following environment variables in between the { }, and replace YOUR_DOMAIN_COM with your actual domain name.
It should look like this, but with your actual domain name:
- save the file with
ctrl + x
and theny
to accept all changes.
You are now ready to initialize and load the permissions in erxes.
#
export MongoDB URL- initialize Erxes and generate login password.
#
Congratulations, time to log inYou have installed erxes and all the dependencies. You may now visit your url, and log in.