DEV Community

selfhosting.sh
selfhosting.sh

Posted on • Originally published at selfhosting.sh

How to Self-Host Rocket.Chat with Docker Compose

#docker #opensource #devops #tutorial

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

Updated March 2026: Verified with latest Docker images and configurations.

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.2.0
    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:
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Initial Setup

  1. Open http://your-server-ip:3000 in your browser
  2. 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
  3. 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: rocketchat@example.com
  • Password: your SMTP password
  • Security: STARTTLS
  • From Email: noreply@example.com

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: "rocketchat@example.com"
  OVERWRITE_SETTING_SMTP_Password: "your-smtp-password"
  OVERWRITE_SETTING_From_Email: "noreply@example.com"
Enter fullscreen mode Exit fullscreen mode

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:

  1. Register with Rocket.Chat Cloud (free for Community Edition, limited to 1,000 push notifications per month) — do this from Administration → Connectivity Services
  2. 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"
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

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 ./
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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' }] })"
Enter fullscreen mode Exit fullscreen mode

Then restart Rocket.Chat:

docker compose restart rocketchat
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"]
Enter fullscreen mode Exit fullscreen mode

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' } }
  )
"
Enter fullscreen mode Exit fullscreen mode

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

Migrating from Slack or Teams

From Slack

Rocket.Chat includes a built-in Slack import tool. Go to Administration → Import → Slack:

  1. Export from Slack: In Slack admin, go to Settings → Import/Export Data → Export to download a ZIP of your workspace (messages, channels, files). Slack's free tier only exports the last 90 days.
  2. Import into Rocket.Chat: Upload the ZIP file in the import tool. Rocket.Chat maps Slack channels to Rocket.Chat channels, preserves message history, and creates user accounts for each Slack user.
  3. What transfers: Channel names, message history, user profiles, pinned messages, and file references (files need to be re-uploaded or linked if they were hosted on Slack's CDN).
  4. What doesn't transfer: Slack apps/integrations (reconfigure these manually), custom emoji (export and re-upload), message reactions, and Slack Connect channels.

From Microsoft Teams

There's no official import tool. The practical approach:

  1. Export Teams data via the Microsoft 365 admin center (compliance export)
  2. The export is in JSON format — you'll need a script to transform it into Rocket.Chat's import format
  3. Community scripts exist on GitHub for Teams-to-Rocket.Chat migration, though none are officially maintained
  4. For most teams, it's easier to start fresh and use Rocket.Chat alongside Teams during a transition period

Webhook and Integration Migration

Rocket.Chat supports incoming and outgoing webhooks that are compatible with Slack's webhook format. Many Slack webhook integrations work in Rocket.Chat by changing the URL endpoint. Go to Administration → Integrations to set up webhook URLs.

Rocket.Chat vs Other Self-Hosted Chat Platforms

Feature Rocket.Chat Mattermost Element/Matrix Zulip
Chat model Channels + threads Channels + threads Rooms + threads Streams + topics
Federation Yes (Matrix bridge, RC federation) No (single server) Yes (native) No (single server)
E2E encryption Yes (opt-in per channel) No (enterprise only) Yes (default in DMs) No
Video calls Built-in (Jitsi, BBB, or native) Plugin (Jitsi, Zoom) Built-in (Jitsi) Plugin (Jitsi, BBB)
Omnichannel Yes (live chat widget) No No No
Mobile apps iOS + Android iOS + Android iOS + Android iOS + Android
LDAP/SSO Yes (Community) Yes (Enterprise) Yes (via Synapse) Yes
RAM usage 1.5-4 GB 500 MB-2 GB 500 MB-2 GB 1-3 GB
Database MongoDB PostgreSQL PostgreSQL PostgreSQL
Marketplace 200+ apps 100+ plugins Bridges + widgets ~30 integrations

Choose Rocket.Chat if you need omnichannel customer support, Slack-like UX with the most features, or 200+ marketplace apps. Choose Mattermost for a lighter, more polished Slack alternative with PostgreSQL. Choose Element/Matrix for federation between organizations. Choose Zulip for topic-based threading that scales better for async-first teams.

Community vs Enterprise Edition

Feature Community (free) Enterprise
Core messaging All features All features
LDAP/SSO Basic LDAP LDAP sync + SAML + custom OAuth
Omnichannel Basic live chat SLA management, routing, canned responses
Federation Basic Advanced federation controls
Auditing No Message audit log, compliance exports
Scalability Single instance Horizontal scaling
Push notifications 1,000/month via cloud gateway Unlimited via self-hosted gateway

The Community Edition is genuinely capable for most teams. Enterprise features matter primarily for regulated industries (auditing), large organizations (horizontal scaling), and customer-facing support operations (advanced omnichannel).

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.

FAQ

Can Rocket.Chat replace Slack for a small team?

Yes. The Community Edition has everything a small team needs — channels, threads, DMs, file sharing, video calls, and integrations. The main trade-off is resource usage: Rocket.Chat needs 2-4 GB of RAM where Mattermost runs in 500 MB. If server resources aren't a concern, Rocket.Chat's feature set exceeds Slack's free tier.

Does Rocket.Chat support end-to-end encryption?

Yes, but only for direct messages and private channels. E2E encryption is opt-in per conversation and uses the OTR (Off-the-Record) protocol. It's not enabled by default. Public channels cannot be E2E encrypted. For a platform where E2E encryption is on by default, use Element/Matrix.

How many users can a single Rocket.Chat instance handle?

With 4 GB RAM and 2 CPU cores, expect 50-100 concurrent users comfortably. With 8 GB RAM and 4 cores, 200-500 concurrent users. Beyond that, you'll need the Enterprise Edition for horizontal scaling (multiple Rocket.Chat instances behind a load balancer). MongoDB's memory appetite is the usual bottleneck.

Can I bridge Rocket.Chat with Matrix?

Yes. The Matrix bridge for Rocket.Chat connects Rocket.Chat channels to Matrix rooms, allowing cross-platform communication. This requires a Matrix homeserver (like Synapse) and the Rocket.Chat Matrix bridge app from the marketplace.

Is MongoDB as a replica set really required?

Yes, since Rocket.Chat 6.0+. Rocket.Chat uses MongoDB change streams for real-time updates, which require a replica set. Even with a single MongoDB node, it must be configured as a single-member replica set. The Docker Compose configuration above handles this automatically.

How do I enable push notifications without Rocket.Chat Cloud?

Self-host the push gateway. Rocket.Chat's push gateway project is open source — you'll need to compile it, configure Apple APN and Google FCM credentials, and point your Rocket.Chat instance to your gateway URL in Administration → Push. This is complex but removes the 1,000/month notification limit.

Can Rocket.Chat handle file sharing for large teams?

Yes, but configure S3-compatible storage instead of local filesystem for production. Local storage fills up quickly with 50+ users sharing files daily. Use MinIO or any S3-compatible backend. Set upload limits appropriate to your storage capacity and enforce per-user quotas through Rocket.Chat's admin settings.

Related

Top comments (0)