Rocket.Chat is an open-source team communication platform with channels, direct messages, threads, file sharing and integrations, which you can host on your own server. Its supported deployment method is Docker, with MongoDB running as a replica set. In this tutorial you will run Rocket.Chat and MongoDB with Docker Compose on Ubuntu 24.04, publish Rocket.Chat over HTTPS through Nginx with a Let's Encrypt certificate, complete the setup wizard and schedule database backups.

Prerequisites

To follow this guide you need:

  • A server running Ubuntu 24.04 LTS, for example a CubePath VPS, with at least 2 vCPUs, 4 GB of RAM and 30 GB of disk.
  • A non-root user with sudo privileges.
  • A domain or subdomain, such as chat.your_domain, with a DNS A record pointing to your server's public IP. This guide uses your_domain as a placeholder.
  • Docker Engine and the Docker Compose plugin installed from Docker's official repository. Step 1 shows the commands.

Step 1 - Installing Docker Engine

Skip this step if docker compose version already works on your server. Otherwise, add Docker's signing key and repository:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine and the Compose plugin:

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Check both:

sudo docker version --format '{{.Server.Version}}'
docker compose version

The first command prints the Docker Engine version and the second one a line such as Docker Compose version v2.x.x.

Step 2 - Opening the firewall

Allow SSH, HTTP and HTTPS in UFW:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Step 3 - Writing the Docker Compose file

Create a directory for the deployment:

sudo mkdir -p /opt/rocketchat
cd /opt/rocketchat

Create an environment file with the values that change between installations:

sudo nano /opt/rocketchat/.env

RELEASE=latest
ROOT_URL=https://your_domain

Create the Compose file:

sudo nano /opt/rocketchat/compose.yml

services:
  mongodb:
    image: mongo:7.0
    restart: unless-stopped
    command: ["--replSet", "rs0", "--bind_ip_all"]
    volumes:
      - mongodb_data:/data/db

  rocketchat:
    image: registry.rocket.chat/rocketchat/rocket.chat:${RELEASE}
    restart: unless-stopped
    depends_on:
      - mongodb
    environment:
      ROOT_URL: ${ROOT_URL}
      PORT: 3000
      MONGO_URL: mongodb://mongodb:27017/rocketchat?replicaSet=rs0
      DEPLOY_METHOD: docker
    ports:
      - "127.0.0.1:3000:3000"

volumes:
  mongodb_data:

A few details of this file:

  • Rocket.Chat requires MongoDB to run as a replica set, even with a single node, because it relies on MongoDB change streams for real-time updates. The --replSet rs0 option enables that.
  • MongoDB has no published port, so only containers on this Compose network can reach it.
  • Uploaded files are stored in MongoDB (GridFS) by default, so the mongodb_data volume holds all your workspace data.

Validate the file:

sudo docker compose config --quiet && echo OK

OK

Step 4 - Starting MongoDB and initializing the replica set

Start only MongoDB first:

sudo docker compose up -d mongodb

Initialize the single-node replica set. The member host name must be mongodb:27017, the service name that Rocket.Chat uses to connect:

sudo docker compose exec mongodb mongosh --quiet --eval 'rs.initiate({_id: "rs0", members: [{_id: 0, host: "mongodb:27017"}]})'

{ ok: 1 }

Wait a few seconds and confirm that this node became the primary:

sudo docker compose exec mongodb mongosh --quiet --eval 'rs.status().members[0].stateStr'

PRIMARY

You only need to initialize the replica set once; the configuration is stored in the data volume.

Step 5 - Starting Rocket.Chat

Pull the image and start the whole stack:

sudo docker compose up -d

The first start creates the database and takes one to two minutes. Follow the logs until you see the server banner:

sudo docker compose logs -f rocketchat

rocketchat-1  | +----------------------------------------------+
rocketchat-1  | |                SERVER RUNNING                |
rocketchat-1  | +----------------------------------------------+
rocketchat-1  | |  Rocket.Chat Version: x.y.z                  |
rocketchat-1  | |       MongoDB Version: 7.0.x                 |
rocketchat-1  | |               Site URL: https://your_domain  |
...

Press Ctrl+C to stop following the logs. Confirm that Rocket.Chat answers on the loopback address:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000

200

Step 6 - Configuring Nginx and HTTPS

Install Nginx and Certbot:

sudo apt install -y nginx certbot python3-certbot-nginx

Create a site for Rocket.Chat:

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

Paste the following, replacing your_domain. The Upgrade and Connection headers are required because Rocket.Chat delivers messages over WebSockets:

server {
    listen 80;
    listen [::]:80;
    server_name your_domain;

    client_max_body_size 100M;

    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_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Nginx-Proxy true;
        proxy_read_timeout 86400s;
    }
}

Enable the site, remove the default one and reload Nginx:

sudo ln -s /etc/nginx/sites-available/rocketchat /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

Request a certificate. Certbot adds the TLS settings and an HTTP to HTTPS redirect to the site:

sudo certbot --nginx -d your_domain

Check that automatic renewal works:

sudo certbot renew --dry-run

Congratulations, all simulated renewals succeeded:
  /etc/letsencrypt/live/your_domain/fullchain.pem (success)

Step 7 - Completing the setup wizard

Open https://your_domain in your browser. The setup wizard asks for:

  1. Admin info: your name, username, email and a strong password. This account becomes the workspace administrator.
  2. Organization info: organization name, type, industry, size and country.
  3. Register your workspace: Rocket.Chat asks you to register the workspace with its cloud service, which is needed for push notifications to the mobile apps and for the Marketplace. Follow the prompts, including the email confirmation.

After the wizard you land in the workspace with a #general channel. Open Administration > Workspace > Settings to review two areas:

  • Email > SMTP: enter your SMTP server, port, user and password so invitations and password resets are delivered.
  • Accounts > Registration: choose whether anyone can register, or only invited users.

Invite people from Administration > Workspace > Users > Invite, or create accounts directly with New user.

Step 8 - Backing up and updating

Because MongoDB holds both messages and uploaded files, a mongodump of the rocketchat database is a complete backup. Create a backup directory and take a first dump:

sudo mkdir -p /var/backups/rocketchat
sudo chmod 700 /var/backups/rocketchat
cd /opt/rocketchat
sudo docker compose exec -T mongodb mongodump --db rocketchat --archive --gzip | sudo tee "/var/backups/rocketchat/rocketchat-$(date +%F).archive.gz" > /dev/null
sudo ls -lh /var/backups/rocketchat

To run it nightly and keep 14 days of dumps, create a cron file:

sudo nano /etc/cron.d/rocketchat-backup

30 2 * * * root cd /opt/rocketchat && docker compose exec -T mongodb mongodump --db rocketchat --archive --gzip > "/var/backups/rocketchat/rocketchat-$(date +\%F).archive.gz" 2>/dev/null
45 3 * * * root find /var/backups/rocketchat -name 'rocketchat-*.archive.gz' -mtime +14 -delete

To restore a dump into a running stack, use mongorestore --archive --gzip --drop with the file on standard input, in the same way.

To update Rocket.Chat, take a backup, change RELEASE in .env if you pinned a version, then pull the new image and recreate the container:

cd /opt/rocketchat
sudo docker compose pull
sudo docker compose up -d

Troubleshooting

  • Rocket.Chat restarts in a loop with a MongoDB error: the replica set was not initialized or the host name is wrong. Run rs.status() as in Step 4 and check that the member host is mongodb:27017.
  • The page loads but messages do not update: WebSockets are not passing through Nginx. Confirm the Upgrade and Connection headers are in the site configuration.
  • Links in emails point to the wrong address: ROOT_URL does not match your public URL. Fix it in .env, then run sudo docker compose up -d, and check Administration > Workspace > Settings > General > Site URL.
  • Uploads fail with "413 Request Entity Too Large": raise client_max_body_size in Nginx and the maximum file size under Settings > File Upload.

Conclusion

Rocket.Chat now runs on Ubuntu 24.04 in Docker, with MongoDB as a replica set, HTTPS through Nginx and nightly database backups. Next, you can connect the desktop and mobile apps to https://your_domain, add incoming webhooks under Administration > Workspace > Integrations to post alerts from your monitoring tools, and enable two-factor authentication for all users under Settings > Accounts > Two Factor Authentication.