What Is Rocket.Chat?

Rocket.Chat is a self-hosted team messaging platform with channels, threads, direct messages, video conferencing, end-to-end encryption, and a massive integrations ecosystem. It replaces Slack, Microsoft Teams, and Discord for organizations that want full control over their communication data. The Community Edition is open source and free to self-host. Rocket.Chat supports omnichannel features (live chat for customer support), over 200 marketplace apps, and federation between instances. GitHub

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
2 GB of free RAM (minimum — 4 GB+ recommended for 50+ users)
10 GB of free disk space (plus storage for file uploads)
A domain name (required for production use and mobile app connectivity)

Docker Compose Configuration

Rocket.Chat 8.x requires MongoDB running as a replica set — even for single-node deployments. This is a hard requirement from MongoDB’s change streams feature that Rocket.Chat depends on for real-time updates. The configuration below handles replica set initialization automatically.

Create a docker-compose.yml file:

services:
  rocketchat:
    image: registry.rocket.chat/rocketchat/rocket.chat:8.1.1
    container_name: rocketchat
    restart: unless-stopped
    ports:
      - "3000:3000"              # Web UI and API
    environment:
      ROOT_URL: "https://chat.example.com"           # CHANGE: your public URL
      MONGO_URL: "mongodb://mongodb:27017/rocketchat?replicaSet=rs0"
      MONGO_OPLOG_URL: "mongodb://mongodb:27017/local?replicaSet=rs0"
      PORT: "3000"
      DEPLOY_METHOD: "docker"
    volumes:
      - rocketchat_uploads:/app/uploads
    depends_on:
      mongodb:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/v1/info"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 120s

  mongodb:
    image: mongodb/mongodb-community-server:8.2-ubi8
    container_name: rocketchat_mongodb
    restart: unless-stopped
    command: ["--replSet", "rs0", "--oplogSize", "128"]
    volumes:
      - rocketchat_mongodb:/data/db
    healthcheck:
      test: >
        mongosh --quiet --eval "
          try {
            var status = rs.status();
            if (status.ok === 1) quit(0);
            else quit(1);
          } catch(e) {
            rs.initiate({ _id: 'rs0', members: [{ _id: 0, host: 'mongodb:27017' }] });
            quit(1);
          }
        "
      interval: 10s
      timeout: 10s
      retries: 30
      start_period: 30s

volumes:
  rocketchat_uploads:
  rocketchat_mongodb:

The MongoDB health check does double duty: it initializes the replica set on first boot and then confirms the replica set is healthy on subsequent checks. Rocket.Chat waits for MongoDB to be healthy before starting.

Start the stack:

docker compose up -d

First startup takes 1-2 minutes. MongoDB needs to initialize the replica set, then Rocket.Chat runs its database migrations. Watch the logs:

docker compose logs -f rocketchat

Wait until you see SERVER RUNNING before accessing the web UI.

Initial Setup

Open http://your-server-ip:3000 in your browser
The Setup Wizard walks you through:
- Admin account — create your first admin user with a strong password
- Organization info — name, type, size (used for telemetry, can be skipped)
- Server info — server name and default language
- Register server — optional registration with Rocket.Chat cloud for push notifications and marketplace access. You can skip this and configure it later
After completing the wizard, you land in the #general channel

The first account created becomes the server administrator with full privileges. Do not lose these credentials.

Configuration

SMTP for Email Notifications

Rocket.Chat needs SMTP for email invitations, password resets, and message notifications. Go to Administration → Settings → Email → SMTP:

SMTP Host: smtp.example.com
SMTP Port: 587
Username: [email protected]
Password: your SMTP password
Security: STARTTLS
From Email: [email protected]

Or set via environment variables in your docker-compose.yml:

environment:
  OVERWRITE_SETTING_SMTP_Host: "smtp.example.com"
  OVERWRITE_SETTING_SMTP_Port: "587"
  OVERWRITE_SETTING_SMTP_Username: "[email protected]"
  OVERWRITE_SETTING_SMTP_Password: "your-smtp-password"
  OVERWRITE_SETTING_From_Email: "[email protected]"

Use the OVERWRITE_SETTING_ prefix to force settings via environment variables. This overrides any values set through the admin UI.

LDAP / Active Directory

For centralized user management, go to Administration → Settings → LDAP:

Enable: Yes
Host: ldap.example.com
Port: 389 (or 636 for LDAPS)
Base DN: ou=users,dc=example,dc=com
Authentication: enable and provide bind DN + password

LDAP sync runs on a schedule. Users authenticate against your directory and their profiles stay in sync. Group-to-channel mapping is available in the Enterprise Edition.

OAuth / SSO

Rocket.Chat supports OAuth2, SAML, and OpenID Connect. For Keycloak, Authentik, or similar:

Go to Administration → Settings → OAuth and add a custom OAuth provider:

URL: https://keycloak.example.com/realms/master
Token Path: /protocol/openid-connect/token
Identity Path: /protocol/openid-connect/userinfo
Authorize Path: /protocol/openid-connect/auth
Client ID / Secret: from your identity provider

Pre-built integrations exist for Google, GitHub, GitLab, Apple, and others under the same settings page.

File Storage

By default, uploads go to the local filesystem at /app/uploads (mapped to the rocketchat_uploads volume). For S3-compatible storage, go to Administration → Settings → File Upload:

Storage Type: AmazonS3
Bucket name: rocketchat-uploads
Access Key / Secret Key: your S3 credentials
Region: us-east-1
Bucket URL: https://s3.amazonaws.com (or your MinIO/Garage endpoint)

This works with MinIO, Garage, or any S3-compatible backend.

File Upload Size Limit

The default maximum upload size is 200 MB. Change it under Administration → Settings → File Upload → Maximum File Upload Size (in bytes). Set to 0 for unlimited (not recommended — set a reasonable limit based on your storage capacity).

Custom Emoji

Go to Administration → Custom Emoji to upload custom emoji. Supports PNG, GIF, and JPEG. Custom emoji are available to all users across all channels.

Mobile Apps

Rocket.Chat has official apps for iOS and Android. On first launch, enter your server URL (e.g., https://chat.example.com) to connect.

For push notifications on mobile, you need to either:

Register with Rocket.Chat Cloud (free for Community Edition, limited to 1,000 push notifications per month) — do this from Administration → Connectivity Services
Self-host a push gateway — more complex but removes the notification limit. See the Rocket.Chat push gateway documentation

Without push gateway registration, mobile apps still work but only show notifications when the app is in the foreground.

Reverse Proxy

Set ROOT_URL in your environment to match your public HTTPS URL:

ROOT_URL: "https://chat.example.com"

Nginx Proxy Manager configuration:

Scheme: http
Forward Hostname: rocketchat
Forward Port: 3000
Enable WebSocket Support: Yes (required — Rocket.Chat relies on WebSockets for real-time messaging)

For Nginx, ensure your configuration includes WebSocket headers:

location / {
    proxy_pass http://rocketchat: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;
}

See Reverse Proxy Setup for full configuration with SSL.

Backup

MongoDB Database

# Dump the database
docker compose exec mongodb mongodump \
  --archive=/data/db/rocketchat-backup-$(date +%Y%m%d).archive \
  --db=rocketchat

# Copy the dump to the host
docker compose cp mongodb:/data/db/rocketchat-backup-$(date +%Y%m%d).archive ./

File Uploads

# Back up the uploads volume
docker run --rm \
  -v rocketchat_uploads:/uploads \
  -v $(pwd):/backup \
  alpine tar czf /backup/rocketchat-uploads-$(date +%Y%m%d).tar.gz /uploads

Restore

# Restore MongoDB
docker compose cp ./rocketchat-backup-20260224.archive mongodb:/data/db/
docker compose exec mongodb mongorestore \
  --archive=/data/db/rocketchat-backup-20260224.archive \
  --db=rocketchat --drop

# Restore uploads
docker run --rm \
  -v rocketchat_uploads:/uploads \
  -v $(pwd):/backup \
  alpine sh -c "cd / && tar xzf /backup/rocketchat-uploads-20260224.tar.gz"

Critical data to back up:

MongoDB database (all messages, users, channels, settings, permissions)
/app/uploads volume (file attachments and avatars)

See Backup Strategy for a comprehensive approach.

Troubleshooting

MongoDB Replica Set Not Initialized

Symptom: Rocket.Chat fails to start with errors like MongoServerSelectionError: connection refused or not primary and secondaryOk=false. Fix: The replica set must be initialized before Rocket.Chat can connect. The health check in the Docker Compose config above handles this automatically. If you see this error, check MongoDB logs:

docker compose logs mongodb

If the replica set was never initialized, connect to MongoDB and do it manually:

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

Then restart Rocket.Chat:

docker compose restart rocketchat

WebSocket Errors Behind Reverse Proxy

Symptom: Chat loads but messages don’t appear in real-time. Browser console shows WebSocket connection failures or repeated reconnection attempts. Fix: Your reverse proxy must support WebSocket upgrades. In Nginx Proxy Manager, enable the “WebSockets Support” toggle. In a manual Nginx config, add proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade";. Also verify ROOT_URL matches your actual public URL — a mismatch causes WebSocket connection failures.

File Upload Size Limit Exceeded

Symptom: Users get errors uploading files, or uploads silently fail. Fix: Two limits can block uploads. First, Rocket.Chat’s internal limit: Administration → Settings → File Upload → Maximum File Upload Size (in bytes) — default is 200 MB. Second, your reverse proxy limit: in Nginx, set client_max_body_size 200m; (or higher). Both must allow the upload size.

SMTP Not Sending Emails

Symptom: Email invitations, password resets, or notifications never arrive. Fix: Go to Administration → Settings → Email → SMTP and click “Test email sending.” Check the error message. Common causes:

Wrong port — use 587 for STARTTLS, 465 for SSL
Missing credentials — both username and password are required for most SMTP providers
Firewall blocking outbound port 587 — check with docker compose exec rocketchat curl -v smtp.example.com:587
“From” email address not authorized by your SMTP provider

High Memory Usage

Symptom: Rocket.Chat container uses 1.5 GB+ of RAM even with few users. Server becomes unresponsive. Fix: Rocket.Chat runs on Node.js, which pre-allocates heap memory. For servers with limited RAM, set a Node.js memory limit:

environment:
  TOOL_NODE_FLAGS: "--max-old-space-size=1024"    # Limit to 1 GB

MongoDB also uses significant RAM for its WiredTiger cache. Limit it by adding to the MongoDB command:

command: ["--replSet", "rs0", "--oplogSize", "128", "--wiredTigerCacheSizeGB", "0.5"]

On a 2 GB server, set Node.js to 768 MB and WiredTiger to 512 MB. This is tight — 4 GB is strongly recommended.

Admin Account Locked Out

Symptom: Cannot log in as admin. Forgot password and SMTP is not configured. Fix: Reset the admin password directly in MongoDB:

docker compose exec mongodb mongosh rocketchat --eval "
  db.users.updateOne(
    { username: 'admin' },
    { \$set: { 'services.password.bcrypt': '\$2b\$10\$abcdefghijklmnopqrstuuABCDEFGHIJKLMNOPQRSTUVWXYZ01234' } }
  )
"

Then log in with the password password and immediately change it to something secure.

Resource Requirements

RAM: 1.5 GB idle (Rocket.Chat ~800 MB + MongoDB ~700 MB), 3-4 GB under moderate load with 50+ active users
CPU: 2 cores minimum, 4 cores recommended for 100+ concurrent users
Disk: ~1 GB for the application and database indexes, plus storage for file uploads and message history

Rocket.Chat is one of the heavier self-hosted chat platforms. A 2 GB server will run it, but expect sluggish performance under any real load. For production use with a team, allocate 4 GB minimum.

Verdict

Rocket.Chat is the most feature-complete self-hosted Slack alternative available. Channels, threads, video calls, screen sharing, E2E encryption, omnichannel customer support, 200+ marketplace apps, LDAP, OAuth, federation — it has everything. The problem is weight. It demands 2-4 GB of RAM for a handful of users, and MongoDB as a replica set adds operational complexity that simpler solutions avoid.

For teams that need the full feature set — especially omnichannel support or federation — Rocket.Chat is the right choice. For most teams that just need solid chat with channels and integrations, Mattermost is lighter, more polished, and easier to operate. If you need federation between servers (think: cross-organization communication), Matrix/Element is purpose-built for that and does it better.

Pick Rocket.Chat if you need its unique features. Pick Mattermost if you want the best balance of features and simplicity. Pick Matrix if federation is non-negotiable.