Deploy on Debian

The recommended deployment methods are Docker, AWS, and Kubernetes. Using other deployment methods may result in unexpected challenges or compatibility issues.

Rocket.Chat offers several deployment options, one of which is on Debian. Whether you’re new to server administration or an experienced professional, this document will provide a step-by-step walkthrough to set up a secure and efficient Rocket.Chat environment on Debian.

Prerequisites

For any Rocket.Chat version you want to install, check the release notes to see the supported engine versions for MongoDB and NodeJs, and install as recommended.

Install Node.js

Follow the official guide to install NodeJS on Debian, or use third-party tools like nvm or n for easier version management.

Install Deno

Deploying Rocket.Chat requires Deno.

Only Deno versions >=1.37.1 and <2.0.0 are supported.

Follow the official Deno installation guide to install the correct version.

Set up MongoDB

When deploying MongoDB, it is crucial to secure MongoDB instances by restricting public access to all MongoDB ports. Unsecured instances can create serious security vulnerabilities, so taking these precautions is critical to ensuring the integrity and safety of your systems.

Start by installing MongoDB on Debian. Refer to the official MongoDB documentation for the latest installation instructions
Once MongoDB is installed, open the MongoDB configuration file (/etc/mongod.conf) by running:
```
nano /etc/mongod.conf
```

In this file, enable replication and specify the replica set name as rs01

The MongoDB replica set is mandatory for Rocket.Chat > 1.0.0.

Your MongoDB configuration file should look something like the below:

# mongod.conf

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

# 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 official MongoDB configuration documentation for additional configuration options.

Start MongoDB with this command:

sudo systemctl enable --now mongod  
sudo systemctl restart mongod

Next, initialize the replica set:

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

To ensure MongoDB is running successfully, run this:
```
sudo systemctl status mongod
```

With all the prerequisites in place, you're ready to install Rocket.Chat.

Step 1: Install Rocket.Chat on Debian

Update your system by running this command:
```
sudo apt -y update
sudo apt -y upgrade
```

Install the required packages and dependencies

sudo apt install -y curl build-essential graphicsmagick

Check the Rocket.Chat release document to choose 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 this 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 command below 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 2: Configure the Rocket.Chat service

Start by adding the Rocketchat user and setting the right permissions on the Rocket.Chat folder.

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

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

Depending on how you install NodeJS, the binary path may be different. Save the path to a variable.
```
NODE_PATH=$(which node)
```

Now, save the systemd service file.

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

The command above will create a barebone service file, which the system will use to start your Rocket.Chat daemon/process.

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.

Step 3: Pass environment variables

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

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

Next, update the file with the information below 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

npm run postinstall  # skip this command if error arises

chown -R rocketchat:rocketchat /home/rocketchat

Now, start your Rocket.Chat workspace using this 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 4: Configure your Rocket.Chat server

To access your Rocket.Chat workspace, open a web browser, and navigate to the "ROOT URL" you specified in the Rocket.Chat configuration file. This is typically accessible at http://your-host-name.com:3000.
Follow the on-screen prompts to configure your workspace

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 apt update
sudo apt install nginx
```

Create a new Nginx configuration file:

sudo nano /etc/nginx/sites-available/rocketchat

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 configuration:
```
sudo ln -s /etc/nginx/sites-available/rocketchat /etc/nginx/sites-enabled/
```
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 apt update
sudo apt install certbot python3-certbot-nginx
```
Run Certbot to obtain and configure the SSL certificate:
```
sudo certbot --nginx -d 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 apt update && sudo apt install -y wget
wget https://github.com/traefik/traefik/releases/download/v2.10.4/traefik_v2.10.4_linux_amd64.tar.gz
tar -zxvf traefik_v2.10.4_linux_amd64.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

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:

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

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
```
Inspect Traefik’s logs for routing issues:
```
sudo cat /var/log/traefik.log | tail -n 50
```

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.