# How to Self-Host Rocket.Chat with Docker Compose

## What Is Rocket.Chat?

[Rocket.Chat](https://www.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](https://github.com/RocketChat/Rocket.Chat)

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

## Prerequisites

- A Linux server (Ubuntu 22.04+ recommended)
- Docker and Docker Compose installed ([guide](/foundations/docker-compose-basics/))
- 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:

```yaml
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:
```

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:

```bash
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:

```bash
docker compose logs -f rocketchat
```

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`:

```yaml
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"
```

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](https://apps.apple.com/app/rocket-chat/id1148741252) and [Android](https://play.google.com/store/apps/details?id=chat.rocket.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](https://docs.rocket.chat/docs/push-notifications)

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:

```yaml
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:

```nginx
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](/foundations/reverse-proxy-explained/) for full configuration with SSL.

## Backup

### MongoDB Database

```bash
# 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

```bash
# 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

```bash
# 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](/foundations/backup-3-2-1-rule/) 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:

```bash
docker compose logs mongodb
```

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

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

Then restart Rocket.Chat:

```bash
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:

```yaml
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:

```yaml
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:

```bash
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.

## 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](/apps/mattermost/) | [Element/Matrix](/apps/element/) | [Zulip](/apps/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](/apps/mattermost/) is lighter, more polished, and easier to operate. If you need federation between servers (think: cross-organization communication), [Matrix/Element](/apps/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](/apps/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](/apps/element/).

### 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](https://docs.rocket.chat/docs/matrix-bridge-new) connects Rocket.Chat channels to Matrix rooms, allowing cross-platform communication. This requires a Matrix homeserver (like [Synapse](/apps/matrix-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](/apps/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

- [Matrix vs Rocket.Chat: Self-Hosted Chat Compared](/compare/matrix-vs-rocket-chat/)
- [Rocket.Chat vs Zulip: Team Messaging Compared](/compare/rocket-chat-vs-zulip/)
- [Best Self-Hosted Team Chat](/best/communication/)
- [Mattermost vs Rocket.Chat](/compare/mattermost-vs-rocket-chat/)
- [Rocket.Chat vs Mattermost](/compare/rocket-chat-vs-mattermost/)
- [How to Self-Host Mattermost](/apps/mattermost/)
- [How to Self-Host Element (Matrix)](/apps/element/)
- [Self-Hosted Alternatives to Slack](/replace/slack/)
- [Self-Hosted Alternatives to Microsoft Teams](/replace/microsoft-teams/)
- [Self-Hosted Alternatives to Discord](/replace/discord/)
- [How to Self-Host Zulip](/apps/zulip/)
- [Docker Compose Basics](/foundations/docker-compose-basics/)
- [Reverse Proxy Setup](/foundations/reverse-proxy-explained/)
- [Backup Strategy](/foundations/backup-3-2-1-rule/)
- [Security Basics for Self-Hosting](/foundations/security-hardening/)
