Deploy with CentOS

The recommended deployment methods are Docker, AWS, and Kubernetes.

This document guides you through the process of deploying a Rocket.Chat workspace on CentOS.

Prerequisites

Depending on the version of Rocket.Chat you want to install, check the releases to see the supported engine versions for MongoDB and NodeJs, and install as recommended.

Install Node.js: Download Node.js for Linux systems using the package manager.
Install Deno: Only Deno versions >=1.37.1 and <2.0.0 are supported. Follow the Deno installation guide to install the correct version.
For example, to install the 1.38.5 version with Shell, use the following command:
```
curl -fsSL https://deno.land/install.sh | sh -s v1.38.5
```
Make sure you export the Deno path according to your installation, for instance:
```
export DENO_INSTALL="/home/ec2-user/.deno"
export PATH="$DENO_INSTALL/bin:$PATH"
```
Install MongoDB: Refer to the MongoDB documentation on installing MongoDB on CentOS.
When deploying MongoDB, it is crucial to secure MongoDB instances and close all MongoDB ports from public access. Unsecured instances can lead to significant security vulnerabilities. Your vigilance in these practices is essential for maintaining the integrity and safety of your systems.

Step 1: Set up MongoDB

Once MongoDB is installed, you must enable replication and specify the name of the replica set. To do this, enter the command below:
```
sudo sed -i "s/^#replication:/replication:\n  replSetName: rs01/" /etc/mongod.conf
```
In this case, we named the replica set as rs01. The MongoDB replica set is mandatory for Rocket.Chat > 1.0.0.

Open the MongoDB configuration file (/etc/mongod.conf) by running:

sudo nano /etc/mongod.conf

The MongoDB configuration file should look something like this:

# mongod.conf

# Where and how to store data.
storage:
  dbPath: /var/lib/mongodb
  journal:
    enabled: true

# where to write logging data.
systemLog:
  destination: file
  logAppend: true
  path: /var/log/mongodb/mongod.log

# network interfaces
net:
  port: 27017
  bindIp: <bind-ip> # Replace with your IP address


# how the process runs
processManagement:
  timeZoneInfo: /usr/share/zoneinfo

# Replication settings
replication:
  replSetName: rs01

Refer to the MongoDB configuration documentation for additional details.

Enable and start MongoDB with the following command:

sudo systemctl enable --now mongod  
sudo systemctl restart mongod

Next, initialize the replica set:

mongosh --eval "printjson(rs.initiate())"

To ensure that MongoDB is running successfully, enter the following command:
```
sudo systemctl status mongod
```

Step 2: Install Rocket.Chat on CentOS

Start by installing the required dependency packages:

sudo dnf install epel-release
sudo dnf install GraphicsMagick
sudo yum groupinstall "Development Tools"

Check the Rocket.Chat releases to deploy the version you need. For stability and compatibility, we recommend downloading a specific version. For example, to download version 6.13.0, run this command:
```
curl -L https://releases.rocket.chat/6.13.0/download -o /tmp/rocket.chat.tgz
```
Alternatively, if you prefer to download the latest version, you can use the following command (note that using latest is not recommended for production purposes):
```
curl -L https://releases.rocket.chat/latest/download -o /tmp/rocket.chat.tgz
```
Extract the Rocket.Chat server files using the following command:
```
tar -xzf /tmp/rocket.chat.tgz -C /tmp
```
This command extracts the contents of the downloaded rocket.chat.tgz compressed tar archive located in the /tmp directory and places the extracted files into the same /tmp directory.
Next, run the following command to change the current directory and install the necessary production dependencies.
```
cd /tmp/bundle/programs/server && npm install
```
When executing npm install, it is recommended to operate using a non-root account. Alternatively, you can utilize the npm install --unsafe-perm command. This approach eliminates the necessity for building libc or upgrading the host system.
Move the extracted files to the /opt directory:
```
sudo mv /tmp/bundle /opt/Rocket.Chat
```
This guide uses the /opt directory. However, you can choose your preferred directory.

Step 3: Configure the Rocket.Chat service

Add the Rocket.Chat user and set the proper permissions on the Rocket.Chat folder:

sudo useradd -M rocketchat && sudo usermod -L rocketchat

sudo chown -R rocketchat:rocketchat /opt/Rocket.Chat

We need the NodeJS binary path to create the Rocket.Chat service file. Depending on how you install NodeJS, the binary path may be different. Save the path to a variable as follows:
```
NODE_PATH=$(which node)
```

Now create a barebone service file, which the system will use to start your Rocket.Chat daemon/process. Create the Rocket.Chat service file as follows:
```
cat << EOF |sudo tee -a /lib/systemd/system/rocketchat.service
[Unit]
Description=The Rocket.Chat server
After=network.target remote-fs.target nss-lookup.target nginx.service mongod.service
[Service]
ExecStart=$NODE_PATH /opt/Rocket.Chat/main.js
StandardOutput=journal
StandardError=journal
SyslogIdentifier=rocketchat
User=rocketchat
[Install]
WantedBy=multi-user.target
EOF
```
You may need to replace User=rocketchat with your current user (e.g., User=ubuntu) if Rocket.Chat or any pre-requisite software is running under a different user on your system.
Alternatively, if you don’t want to use the NODE_PATH variable in the service file, save the path to the variable, and then print it to find the path as follows:
```
NODE_PATH=$(which node)
echo NODE_PATH=$(which node)
```
Now replace the ExecStart variable in the service file with the path you see in your terminal, for example :
```
ExecStart=/usr/bin/node /opt/Rocket.Chat/main.js
```
If you use nvm to manage Node.js versions, update the ExecStart variable as follows:
```
ExecStart=/bin/bash -c 'source /home/<user>/.nvm/nvm.sh && /home/<user>/.nvm/versions/node/<node_version>/bin/node /opt/Rocket.Chat/main.js'
```
Be sure to replace <user> and <node_version> with your actual system user and installed Node.js version.

Step 4: Pass environment variables

Running the Rocket.Chat daemon requires passing some environment variables. See Rocket.Chat environment variables for more details.

Update the Rocket.Chat file by running:
```
sudo systemctl edit rocketchat
```

Update the file with the following information according to your configuration and save it:

[Service]
Environment=ROOT_URL=http://localhost:3000
Environment=PORT=3000
Environment=MONGO_URL=mongodb://localhost:27017/rocketchat?replicaSet=rs01
Environment=MONGO_OPLOG_URL=mongodb://localhost:27017/local?replicaSet=rs01

Additional steps for installing 6.10 release

If you’re installing version 6.10, run these additional commands:

mkdir -p /home/rocketchat/.cache

cd PATH_TO_ROCKETCHAT_INSTALLATION/programs/server/npm/node_modules/@rocket.chat/apps-engine

export DENO_DIR=/home/rocketchat/.cache/deno

npm install --production # if "npm" does not work, try using "yarn"

npm run postinstall # if you are facing errors here, skip this command

chown -R rocketchat:rocketchat /home/rocketchat

Now start the Rocket.Chat service using the following command:
```
sudo systemctl enable --now rocketchat
```

Check the status of the Rocket.Chat process with this command:
```
sudo systemctl status rocketchat
```
If you edit your Rocket.Chat configuration file, make sure to reload the daemon and restart the Rocket.Chat process by running the following commands:
```
sudo systemctl daemon-reload
sudo systemctl restart rocketchat
```

Step 5: Configure your Rocket.Chat workspace

To access your Rocket.Chat workspace, open a web browser, and navigate to the specified root URL (http://your-host-name.com:3000). Follow the configuration prompts to configure your workspace. During the configuration steps, your workspace and email are registered to the Rocket.Chat Cloud portal. You can manage your workspace and subscriptions from the cloud portal.

Next steps

Great! You’ve successfully created your Rocket.Chat workspace and logged in. Next, check out the following documents to get started:

User Guides: Learn the basics of your Rocket.Chat account, the types of rooms, and how to communicate with your workspace users.
Workspace Administration: Administrators and owners can set and manage various configurations.
Marketplace: Explore the available apps to enhance your workspace.

You can also apply the following additional configuration to your Rocket.Chat setup for enhanced security and performance:

Enable HTTPS for your Rocket.Chat workspace

For your workspace’s security, your domain should be accessible only via HTTPS. While there are various ways to set up a reverse proxy, this section provides a walkthrough on using Nginx or Traefik.

Nginx

Traefik

Prerequisite

You must set up a DNS record for your domain before configuring Nginx with Let's Encrypt. This domain must have A or AAAA records pointing to the IP address where Nginx is running

Using Nginx

Install Nginx
```
sudo yum update
sudo yum install nginx
```

Create a new Nginx configuration file:

sudo nano /etc/nginx/conf.d/rocketchat.conf

Add the following configuration, replacing your_domain.com with your actual domain:

server {
    listen 80;
    server_name your_domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_set_header X-Forwarded-Proto http;
        proxy_set_header X-Nginx-Proxy true;
        proxy_redirect off;
    }
}

Enable the necessary SELinux boolean to allow Nginx to connect to your backend:
```
sudo setsebool -P httpd_can_network_connect 1
```
Test and restart Nginx:
```
sudo nginx -t
sudo systemctl restart nginx
```
This proxies requests from port 80 to Rocket.Chat running on localhost:3000.
Enable SSL with Let's Encrypt and Certbot by installing the Certbot and the Nginx plugin:
```
sudo yum update
sudo yum install certbot python3-certbot-nginx
```
Run Certbot to obtain and configure the SSL certificate:
```
sudo certbot --nginx -d your_domain.com -d www.your_domain.com
```
Ensure your_domain.com is set correctly in your Nginx config.
Follow the prompts to provide an email, agree to terms, and enable HTTPS redirection. Certbot will automatically configure SSL and set up renewal.
After completion, verify HTTPS by visiting https://your_domain.com.

Prerequisite

You must set up a DNS record for your domain before configuring Traefik with Let's Encrypt. This domain must have A or AAAA records pointing to the IP address where Traefik is running.

Using Traefik

Install Traefik:

sudo curl -L https://github.com/traefik/traefik/releases/download/v2.9.6/traefik_v2.9.6_linux_amd64.tar.gz -o traefik.tar.gz
sudo tar -zxvf traefik.tar.gz
sudo mv traefik /usr/local/bin/

Create a Traefik configuration file:

sudo mkdir -p /etc/traefik
sudo nano /etc/traefik/traefik.toml

Add the following:

[entryPoints]
  [entryPoints.web]
    address = ":80"
  [entryPoints.websecure]
    address = ":443"

[certificatesResolvers.letsencrypt.acme]
  email = "your_email@your_domain.com"
  storage = "/etc/traefik/acme.json"
  [certificatesResolvers.letsencrypt.acme.tlsChallenge]

[providers.file]
  directory = "/etc/traefik/dynamic_conf"

[api]
  dashboard = true

Replace your_email@your_domain.com with your email address.

Create a dynamic configuration file for Rocket.Chat:

sudo mkdir -p /etc/traefik/dynamic_conf
sudo nano /etc/traefik/dynamic_conf/rocketchat.toml

Add the below:

[http.routers]
  [http.routers.rocketchat]
    rule = "Host(`your_domain.com`)"
    service = "rocketchat"
    entryPoints = ["websecure"]
    [http.routers.rocketchat.tls]
      certResolver = "letsencrypt"

[http.services]
  [http.services.rocketchat.loadBalancer]
    [[http.services.rocketchat.loadBalancer.servers]]
      url = "http://your_ip:3000"

Make sure your_domain.com and http://your_ip:3000 point to the appropriate domain and IP address respectively.

Create a systemd service file for Traefik:

sudo nano /etc/systemd/system/traefik.service

Add:

[Unit]
Description=Traefik
Documentation=https://doc.traefik.io/traefik/
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/traefik --configfile=/etc/traefik/traefik.toml
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable the necessary SELinux boolean for Traefik:

sudo yum install -y container-selinux
sudo yum update container-selinux
sudo setsebool -P container_manage_cgroup 1

Start and enable Traefik:

sudo systemctl daemon-reload
sudo systemctl enable --now traefik

Open your Rocket.Chat systemd service file to set the correct ROOT_URL:
```
sudo systemctl edit rocketchat
```
Update the Environment variable::
```
Environment=ROOT_URL=https://your_domain.com
```

Restart Rocket.Chat:

sudo systemctl daemon-reload
sudo systemctl restart rocketchat

Make sure ports 80 and 443 are open:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Now, you can access your Rocket.Chat workspace securely via HTTPS using https://your_domain.com.

If you're not using a reverse proxy and have a firewall enabled, you may need to allow traffic on port 3000. For more details, refer to the firewall rule documentation.

Here are other additional configuration options to consider when optimizing your Rocket.Chat server:

Monitor and log your deployment

This section provides a guide to monitoring your deployments' health and quickly diagnosing any issues.

Rocket.Chat logs

Check the latest Rocket.Chat logs:

sudo journalctl -u rocketchat --no-pager --lines=50

View logs in real-time:
```
sudo journalctl -u rocketchat -f
```
Check Rocket.Chat status:
```
sudo systemctl status rocketchat
```

MongoDB logs

Check MongoDB logs:

sudo journalctl -u mongod --no-pager --lines=50

View logs in real-time:
```
sudo journalctl -u mongod -f
```
Check MongoDB status:
```
sudo systemctl status mongod
```
Connect to MongoDB and verify the replica set:
```
mongosh --eval "rs.status()"
```

Check system-wide logs

If a service is failing and you need system-wide logs:
```
sudo journalctl -xe
```
For logs of a specific time range (e.g., last 30 minutes):
```
sudo journalctl --since "30 minutes ago"
```

Nginx logs

Check error logs:

Check access logs:

sudo tail -n 50 /var/log/nginx/access.log

Monitor logs in real-time:
```
sudo tail -f /var/log/nginx/error.log
```
Check if Nginx is running:
```
sudo systemctl status nginx
```
Test the Nginx configuration:
```
sudo nginx -t
```
If there are configuration issues, restart Nginx after fixing them:
```
sudo systemctl restart nginx
```

Traefik logs

Check Traefik logs with:

sudo journalctl -u traefik --no-pager --lines=50

View logs in real-time:
```
sudo journalctl -u traefik -f
```
Check Traefik’s status:
```
sudo systemctl status traefik
```

Update your workspace version

It’s important to keep your workspaces updated to enjoy the benefits of new features and fixes.

Follow these steps to update your workspace version:

Stop the Rocket.Chat service with this command:
```
sudo systemctl stop rocketchat
```

Remove the installation folder, usually in /opt:
```
sudo rm -rf /opt/Rocket.Chat
```
Ensure you have the supported node and MongoDB versions by checking the releases.
Download the version of Rocket.Chat that you need:
```
curl -L https://releases.rocket.chat/7.0.0/download -o /tmp/rocket.chat.tgz
```
Using latest instead of the version number is not recommended.
Extract the Rocket.Chat server files using the following command:
```
tar -xzf /tmp/rocket.chat.tgz -C /tmp
```

Next, run the following command to change the current directory and install the necessary production dependencies:
```
cd /tmp/bundle/programs/server && npm install
```

Move the extracted files to the /opt directory:
```
sudo mv /tmp/bundle /opt/Rocket.Chat
```

Start the Rocket.Chat service:
```
sudo systemctl start rocketchat
```
Check the status of the Rocket.Chat process with this command:
```
sudo systemctl status rocketchat
```

If you have any questions or issues when updating Rocket.Chat, refer to the Updating Rocket.Chat FAQ. For information on supported MongoDB versions, see the MongoDB version support document.