Rocket.Chat 7.6.0 Installation Guide on Debian 12

This document provides a comprehensive guide for installing and configuring Rocket.Chat 7.6.0 on Debian 12 (Bookworm), including dependencies, troubleshooting.

Table of Contents

• Environment Overview
• Prerequisites
• MongoDB Installation and Configuration
• Node.js Installation
• Rocket.Chat Installation
• Systemd Service Configuration
• Nginx Reverse Proxy Setup
• Common Issues and Troubleshooting
• Initial Rocket.Chat Setup

Environment Overview

• Operating System: Debian 12 (Bookworm)
• Rocket.Chat Version: 7.6.0
• Node.js Version: 22.15.0 (specifically required by Rocket.Chat 7.6.0)
• MongoDB Version: 7.0.x
• Nginx Version: 1.22.1
• Installation Path: /var/opt/Rocket.Chat

Prerequisites

• CPU with AVX support (required for MongoDB 7.0+)
• Sufficient disk space (particularly on partition where Rocket.Chat will be installed)
• Required packages:

  apt update
  apt install python3 build-essential graphicsmagick curl gnupg2 apt-transport-https ca-certificates
  

MongoDB Installation and Configuration

MongoDB 7.0.x must be configured as a replica set, even for a single instance deployment.

1. Install MongoDB

# Import MongoDB public GPG key
curl -fsSL https://pgp.mongodb.com/server-7.0.asc | \
    gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg \
   --dearmor

# Add MongoDB repository
echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/debian bookworm/mongodb-org/7.0 main" | \
   tee /etc/apt/sources.list.d/mongodb-org-7.0.list

# Update and install MongoDB
apt update
apt install -y mongodb-org

2. Configure MongoDB Replica Set

Edit the MongoDB configuration filea and add or uncomment the replication section:

replication:
  replSetName: "rs0"

Start and enable MongoDB:

systemctl start mongod
systemctl enable mongod

Initiate the replica set:

mongosh --eval "rs.initiate()"

Verify the replica set status:

mongosh --eval "rs.status()"

Node.js Installation

Rocket.Chat 7.6.0 specifically requires Node.js 22.x.

Install Node.js 22.x from NodeSource

# Download and run the NodeSource setup script
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Install Node.js
apt install -y nodejs

# Verify the installation
node --version  # Should display v22.15.0 or similar

Note

: If using nvm (Node Version Manager), it should be ensured that it's deactivated for the root user by running nvm deactivate and hash -r to allow the global Node.js installation to take precedence.

Rocket.Chat Installation

1. Create a dedicated user for Rocket.Chat

useradd -m -d /var/opt/Rocket.Chat -s /bin/bash rocketchat

2. Download and extract Rocket.Chat

cd /tmp
curl -L https://releases.rocket.chat/latest/download -o rocket.chat.tgz
mkdir -p /var/opt/Rocket.Chat
tar -xzf rocket.chat.tgz -C /var/opt/Rocket.Chat --strip-components=1
chown -R rocketchat:rocketchat /var/opt/Rocket.Chat

3. Install dependencies

cd /var/opt/Rocket.Chat/programs/server
npm install --production

Troubleshooting: If you encounter errors related to isolated-vm.node or NODE_MODULE_VERSION mismatches, ensure you're using Node.js 22.x and try cleaning and reinstalling dependencies:

rm -rf node_modules
npm install --production

Systemd Service Configuration

Systemd service file to manage the Rocket.Chat application:

Add the following configuration:

[Unit]
Description=Rocket.Chat server
After=network.target mongod.service
Requires=mongod.service

[Service]
Type=simple
User=rocketchat
WorkingDirectory=/var/opt/Rocket.Chat
ExecStart=/usr/bin/node main.js # Using Node.js v22 from /usr/bin/node

Restart=always
RestartSec=10
SyslogIdentifier=rocketchat

Environment=PORT=3000
Environment=ROOT_URL=https://rocketchat.b-net.cloud
Environment=MONGO_URL=mongodb://localhost:27017/rocketchat?replicaSet=rs0
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Enable and start the service:

systemctl daemon-reload
sudo systemctl enable rocketchat
sudo systemctl start rocketchat

Check the service status:

sudo systemctl status rocketchat
sudo journalctl -u rocketchat -f

Nginx Reverse Proxy Setup

1. Nginx configuration file

/etc/nginx/sites-available/rocketchat.b-net.cloud-access.log

Configuration:

server {
    server_name rocketchat.b-net.cloud;
    listen 443 ssl;
    listen [::]:443 ssl;
    ssl_certificate /etc/letsencrypt/live/rocketchat.b-net.cloud/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/rocketchat.b-net.cloud/privkey.pem; # managed by Certbot

    # HSTS (ngx_http_headers_module is required)
    add_header Strict-Transport-Security max-age=31536000;

    location / {
	proxy_pass http://127.0.0.1:3000/;
	proxy_http_version 1.1;
	proxy_set_header Upgrade $http_upgrade;
	proxy_set_header Connection 'upgrade';
	proxy_set_header Host $host;
	proxy_cache_bypass $http_upgrade;
    }

    access_log /var/log/nginx/rocketchat.b-net.cloud-access.log;
    error_log /var/log/nginx/rocketchat.b-net.cloud-error.log;

}

Note

: Replace your-domain.com with your actual domain and update SSL certificate paths.

2. Enable the configuration

ln -s /etc/nginx/sites-available/rocketchat /etc/nginx/sites-enabled/
nginx -t
systemctl restart nginx

Common Issues and Troubleshooting

MongoDB Issues

• "Illegal Instruction" error: Check if CPU supports AVX instructions (required for MongoDB 7.0+)
• Connection issues: Ensure MongoDB is running (systemctl status mongod) and properly configured as a replica set

Node.js Issues

• Version compatibility: Rocket.Chat 7.6.0 specifically requires Node.js 22.x
• Native module errors: If encountering isolated-vm errors, ensure you're using Node.js 22.x and rebuild dependencies:

  cd /var/opt/Rocket.Chat/programs/server
  rm -rf node_modules
  npm install --production
  

Rocket.Chat Service Issues

• Error 200/CHDIR: Check the WorkingDirectory path in the systemd service file
• Error 203/EXEC: Ensure the rocketchat user can access Node.js
• "The $changeStream stage is only supported on replica sets": MongoDB must be configured as a replica set

Nginx Issues

• 502 Bad Gateway: If using proxy_pass http://localhost:3000/, try changing to http://127.0.0.1:3000/ to force IPv4 communication

Initial Rocket.Chat Setup

1. Access your Rocket.Chat instance at https://your-domain.com
2. Follow the setup wizard to create the admin user and organization
3. If you encounter an email confirmation screen, ensure SMTP is properly configured in the systemd service file
4. Restart the Rocket.Chat service after updating SMTP configuration:

   systemctl restart rocketchat
   

Admin Access Troubleshooting

If the first user doesn't have admin access despite having the admin role in MongoDB:

1. Check if email verification is required:

   mongosh --eval "db.users.findOne({username: 'admin'}).emails[0].verified"
   

2. If needed, manually verify the email:

   mongosh
   > use rocketchat
   > db.users.update({username: 'admin'}, {$set: {'emails.0.verified': true}})
   

3. Restart the Rocket.Chat service:

   systemctl restart rocketchat