Rocket.Chat Administrator & Developer Guide

This guide is the operational and architectural reference for Rocket.Chat — a self-hostable, open-source team-communications platform built in TypeScript on Meteor with a React client and an optional Moleculer-based microservices tier. It targets administrators, DevOps engineers, security teams, and developers who deploy, operate, secure, extend, or contribute to a Rocket.Chat workspace.

Note

Scope and version. This guide reflects the source at commit 121e19f (version 8.6.0-develop), Meteor 3.4.1, Node 22.22.3, Yarn 4.12.0. Settings, env vars, permissions, and architecture described here are read directly from the codebase. For end-user task instructions (messaging, channels, calls), see the companion Rocket.Chat User Guide.

Table of Contents

1. Executive Summary
2. Architecture
3. Repository Structure
4. System Requirements
5. Installation & Deployment
6. Configuration: The Settings System
7. Settings Reference by Group
8. Authentication & Identity
9. Authorization: Roles & Permissions
10. File Storage
11. Real-Time Transport & Horizontal Scaling
12. Omnichannel (Live Chat)
13. Federation
14. The REST API
15. Security Hardening
16. Monitoring, Health & Observability
17. Operations: Start, Stop, Logs, Backup, Upgrade
18. Enterprise Edition & Licensing
19. Developer Internals
20. Troubleshooting
21. Potential Improvements & Tech Debt
22. Quick Reference

1. Executive Summary

Rocket.Chat is a monolithic Meteor application (apps/meteor) surrounded by a large set of internal TypeScript packages, with an optional microservices tier for horizontal scale. Key architectural facts:

• Runtime: A Meteor 3.4.1 server (Node 22.22.3) serving a React 18 single-page client. Real-time data flows over DDP (Meteor's websocket protocol).
• Database: MongoDB (driver 6.16) is the single source of truth. Reactivity relies on the MongoDB oplog (a replica set is required for production-grade reactivity).
• Monorepo: Yarn 4 workspaces orchestrated by Turbo, spanning apps/*, packages/*, ee/apps/*, and ee/packages/*.
• Microservices (EE): Discrete services — authorization, account, presence, DDP streamer, queue worker, federation, omnichannel transcript — communicate via Moleculer over a NATS transporter for large deployments.
• Extensibility: The Apps-Engine runs third-party apps (in a sandboxed Deno runtime), and a comprehensive REST API plus webhooks integrate external systems.
• Editions: Community Edition (CE) is MIT-licensed; Enterprise Edition (EE) features (advanced Omnichannel, ABAC, microservices, etc.) gate behind a license key validated by ee/packages/license.

The platform is designed for high-trust environments (the README cites Deutsche Bahn, the US Navy, and Credit Suisse), with E2E encryption, SAML/LDAP/OAuth identity, role- and attribute-based access control, and air-gapped deployment as first-class concerns.

2. Architecture

2.1 High-level component diagram

                          ┌─────────────────────────────────────────┐
        Browsers /         │              Reverse Proxy               │
        Desktop / Mobile ─▶│        (Traefik / nginx / etc.)          │
                          └───────────────┬─────────────────────────┘
                                          │  HTTP + WebSocket (DDP)
                          ┌───────────────▼─────────────────────────┐
                          │      apps/meteor  (Meteor 3.4.1)         │
                          │  ┌────────────┬──────────┬────────────┐  │
                          │  │ React SPA  │ REST API │ DDP methods │  │
                          │  │ (client)   │  (v1)    │ + pub/sub   │  │
                          │  └────────────┴──────────┴────────────┘  │
                          │   Settings · Auth · Authorization ·       │
                          │   Apps-Engine · Omnichannel · E2EE        │
                          └───────┬───────────────────┬──────────────┘
                                  │ Mongo driver      │ Moleculer / NATS
                          ┌───────▼────────┐   ┌──────▼───────────────────────┐
                          │   MongoDB      │   │  Microservices (EE, optional) │
                          │  (replica set, │   │  authorization · account ·    │
                          │   oplog)       │   │  presence · ddp-streamer ·    │
                          └────────────────┘   │  queue-worker · federation ·  │
                                               │  omnichannel-transcript       │
                                               └───────────────────────────────┘

2.2 The Meteor monolith (apps/meteor)

The core application is a Meteor app whose entry points are client/main.ts (browser) and server/main.ts (Node). It contains:

• app/ — feature modules (api, authorization, authentication, livechat, file-upload, integrations, mentions, markdown, push-notifications, statistics, meteor-accounts-saml, slashcommands-*, etc.). Each module typically exposes server logic, client views, and an index.ts entry point.
• client/ — the React SPA: views, providers, hooks, and UI composed largely from the @rocket.chat/fuselage design system.
• server/ — server bootstrap, services, settings registration, routes (/health, /metrics, avatar), and module listeners.
• ee/ — Enterprise-only server code layered on top of the CE base (license, advanced Omnichannel, apps, authorization).
• lib/, definition/, tests/ — shared utilities, type definitions, and unit/e2e/end-to-end test suites (Jest + Playwright).

2.3 Internal packages (packages/*)

Rocket.Chat factors most non-Meteor logic into ~100 internal packages. The load-bearing ones:

2.4 Enterprise services (ee/apps/*, ee/packages/*)

These run as standalone microservices when you scale out:

Inter-service communication uses Moleculer over a transporter selected by the TRANSPORTER env var (NATS in the standard topology). The monolith detects microservice mode via isRunningMs (presence of TRANSPORTER).

3. Repository Structure

Rocket.Chat/
├── apps/
│   ├── meteor/            # The core Meteor application (server + React client)
│   │   ├── app/           # Feature modules (api, authorization, livechat, …)
│   │   ├── client/        # React SPA
│   │   ├── server/        # Server bootstrap, settings, routes, services
│   │   ├── ee/            # Enterprise server code
│   │   └── tests/         # unit (Jest), e2e + end-to-end (Playwright)
│   └── uikit-playground/  # UI Kit sandbox
├── packages/              # ~100 internal TS libraries (core-typings, models, …)
├── ee/
│   ├── apps/              # EE microservices (authorization, account, presence, …)
│   └── packages/          # EE libraries (license, abac, federation-matrix, …)
├── docker-compose-ci.yml      # CI compose (services + deps)
├── docker-compose-local.yml   # Local microservices compose
├── turbo.json             # Turbo task graph
├── package.json           # Monorepo root (workspaces, scripts)
└── yarn.lock

The root package.json is an orchestrator only — it defines workspaces and Turbo tasks (build, dev, lint, testunit, ms). The shippable application version lives in apps/meteor/package.json and its Meteor release in apps/meteor/.meteor/release (METEOR@3.4.1).

Tip

When navigating the codebase, remember the inversion typical of large monorepos: deep app/ plumbing is large and central, while the user-facing command surface (slash commands, REST endpoints) is spread thin across many small directories. Start from apps/meteor/server/settings/ for configuration and apps/meteor/app/authorization/server/constant/permissions.ts for the security model.

4. System Requirements

Important

MongoDB must be a replica set in production. Rocket.Chat tails the oplog (MONGO_OPLOG_URL) for real-time updates; a standalone mongod degrades reactivity and is unsupported for production. Verify supported MongoDB versions against the release you are deploying before upgrading the database.

Note

Always check the official system requirements for the exact supported MongoDB and Node versions for your target Rocket.Chat release, as these advance over time.

5. Installation & Deployment

Rocket.Chat supports several deployment methods. Choose based on scale and environment.

5.1 Deployment options

5.2 Core runtime environment variables

Rocket.Chat is configured at the process level by environment variables (and at runtime by in-database settings — see §6). The essential process env vars:

Note

Email transport (SMTP_*, Direct_Reply_*), federation (MATRIX_*, SERVER_*, MEDIA_*), and many other values can also be supplied via env when their setting is declared env: true or via OVERWRITE_SETTING_*. See the per-group reference in §7.

5.3 Single-node Docker (typical)

A standard single-node deployment runs the Rocket.Chat image plus a MongoDB replica set behind a reverse proxy. Conceptually:

# Illustrative single-node topology (use the official compose for your release)
services:
  rocketchat:
    image: registry.rocket.chat/rocketchat/rocket.chat:latest
    environment:
      ROOT_URL: https://chat.example.com
      MONGO_URL: mongodb://mongo:27017/rocketchat?replicaSet=rs0
      MONGO_OPLOG_URL: mongodb://mongo:27017/local?replicaSet=rs0
      PORT: "3000"
    depends_on:
      - mongo
    ports:
      - "3000:3000"
  mongo:
    image: mongo:6.0
    command: mongod --replSet rs0 --oplogSize 128
    volumes:
      - ./data/db:/data/db

Important

After first starting MongoDB you must initialize the replica set (rs.initiate(...)) once, or Rocket.Chat will not connect to the oplog. Use the official deployment guide's compose file for your release rather than hand-rolling, as image registry paths and defaults change between versions.

5.4 Microservices topology

For horizontal scale, run the discrete services from ee/apps/* alongside the main app, with NATS as the transporter and Traefik routing websockets to the DDP streamer. The repository's docker-compose-local.yml demonstrates the service set:

rocketchat (main)           → PathPrefix(`/`)
ddp-streamer-service        → PathPrefix(`/websocket`) || PathPrefix(`/sockjs`)
authorization-service       → depends on nats
account-service             → depends on nats
presence-service            → depends on nats
queue-worker-service        → depends on nats
+ nats (transporter), mongo, traefik

Each service receives MONGO_URL and TRANSPORTER; Traefik load-balances HTTP to the main app and websocket traffic to the DDP streamer. This is an Enterprise topology and requires a license.

Caution

Microservices mode is for scale, not for getting started. Begin with the monolith; move to microservices only when a single instance can no longer serve your concurrency, and validate with the official Helm chart, which encodes the correct routing and service dependencies.

6. Configuration: The Settings System

Almost everything an administrator tunes is a runtime setting stored in MongoDB and edited under Admin → Settings, not a config file.

6.1 How settings are defined

Settings are registered in code under apps/meteor/server/settings/*.ts using a fluent registry:

settingsRegistry.addGroup('Accounts', async function () {
  await this.section('Two Factor Authentication', async function () {
    await this.add('Accounts_TwoFactorAuthentication_Enabled', true, {
      type: 'boolean',
      public: true,
    });
  });
});

• addGroup creates a top-level group (a page in the admin UI).
• section subdivides a group.
• add(id, default, options) declares one setting.

Setting options you'll encounter:

6.2 Overriding settings from the environment

Two mechanisms let you pin settings outside the UI (useful for GitOps and immutable infra):

1. OVERWRITE_SETTING_<Setting_Id> — forces a value at every startup; the UI shows it as locked.
2. env: true settings — read their default from a matching environment variable on first run.

Tip

For reproducible, audited deployments, drive critical settings (SMTP, auth, file storage, Force_SSL) via OVERWRITE_SETTING_* so they live in your infra-as-code rather than only in the database.

7. Settings Reference by Group

The settings registry defines the following groups (each maps to a page in Admin → Settings). Below, each group lists its purpose and representative keys read from source.

Accounts

User account behavior. Sections: Two Factor Authentication (Accounts_TwoFactorAuthentication_Enabled, ..._By_TOTP_Enabled, ..._By_Email_Enabled, ..._RememberFor), Login Attempts (Block_Multiple_Failed_Logins_* by user and by IP), Login Logs, Registration (Accounts_RegistrationForm = Public/Disabled/Secret URL, Accounts_EmailVerification, Accounts_ManuallyApproveNewUsers, Accounts_AllowedDomainsList/BlockedDomainsList, default roles), Default User Preferences (the system-wide defaults for every user preference), Avatar (Accounts_AvatarResize, Accounts_AvatarSize, external provider URLs), Password Policy (Accounts_Password_Policy_* — min length default 14, complexity rules), Password History. Top-level keys include Accounts_AllowUsernameChange, Accounts_AllowEmailChange, Accounts_LoginExpiration (default 90 days), Accounts_AllowAnonymousRead.

Analytics

PiwikAnalytics_* (Matomo) and GoogleAnalytics_*, plus Analytics_features_* toggles for messages/rooms/users.

Assets

Workspace branding assets (Assets_SvgFavicon_Enable and uploaded logos/favicons via the Assets admin).

Bots

BotHelpers_userFields — which user fields bot helper methods may return.

CAS

Apereo CAS SSO: CAS_enabled, CAS_base_url, CAS_login_url, CAS_version (1.0/2.0), attribute sync (CAS_Sync_User_Data_*), and login button layout.

AtlassianCrowd

Crowd directory integration: CROWD_Enable, CROWD_URL, app credentials (secret), CROWD_Sync_* with a cron-mapped sync interval, plus Test Connection / Sync Users actions.

EmojiCustomFilesystem / CustomSoundsFilesystem

Storage type (GridFS or FileSystem) and filesystem path for custom emoji and sounds.

Discussion

Discussion_enabled — enable/disable the discussions feature.

End-to-end_encryption

E2E_Enable (master toggle), E2E_Allow_Unencrypted_Messages, default-on for direct/private rooms, E2E_Enable_Encrypt_Files, E2E_Enabled_Mentions.

Email

SMTP and mail templates. Sections: SMTP (SMTP_Host, SMTP_Port, SMTP_Protocol smtp/smtps, SMTP_Username/SMTP_Password secret, From_Email, Send test mail action), Direct Reply (IMAP/POP inbound for email replies), and the HTML templates for enrollment, verification, invitation, forgot-password, and email-changed notifications, plus header/footer and style.

Federation

Two federation surfaces: Matrix federation (homeserver, media limits, key refresh) and Rocket.Chat Federation. Plus a separate IRC_Federation group.

FileUpload

Upload limits and the storage backend, with sections for Amazon S3, Google Cloud Storage, File System, and WebDAV. Choose the backend, bucket/path, and credentials here.

General

Core workspace settings. Notable keys: Site_Name (default Rocket.Chat), Site_Url, Language, First_Channel_After_Login, Unread_Count / Unread_Count_DM, CDN_PREFIX, Force_SSL, Default_Referrer_Policy (default same-origin), Iframe_Restrict_Access, GoogleTagManager_id, Bugsnag_api_key. Sections include REST API (rate-limiter toggles, API_Upper_Count_Limit), UTF8 (username/channel name validation regex), Notifications, Iframe Integration, Reporting, NPS, Timezone, Update, and SSRF Protection.

Layout

Branding and UI: Login page customization, Home page content/title, Custom Scripts, User Interface options, and Custom CSS.

LDAP

LDAP/AD integration: connection + authentication, encryption (TLS/StartTLS), timeouts, user-search filter, group filter, data-sync field mapping (LDAP_DataSync_DataMap), and avatar sync.

Logs

Logging verbosity and a Prometheus section (metrics exposure).

Message

Messaging behavior: Attachments, Audio, Read Receipts, KaTeX (math), Google Maps, edit/delete windows, allowed message length, and link-preview (oEmbed) behavior.

Meta / Mobile

HTML meta tags; mobile-specific options including Screen Lock.

OAuth

Built-in OAuth providers: Drupal, Apple, GitHub, GitHub Enterprise, GitLab, Nextcloud, WordPress, Dolphin, Facebook, Google, Linkedin, Meteor, Twitter, plus a generic Custom OAuth mechanism and proxy settings.

Omnichannel

The Live Chat platform: routing, Business Hours, queue behavior, agent/visitor settings, plus the related SMS group (Twilio, External Frame).

Push

Mobile push gateway configuration, Certificates and Keys, and a Privacy section controlling how much message content appears in push payloads.

Rate Limiter

DDP Rate Limiter, API Rate Limiter, and Feature Limiting — throttle method calls and REST traffic to protect the server.

RetentionPolicy

Automatic message pruning: a Global Policy with per-room-type overrides and per-room configuration (edit-room-retention-policy permission required to set it on a room).

Setup_Wizard

The first-run wizard: Organization Info and Cloud Info (used to register the workspace with Rocket.Chat Cloud).

SlackBridge / Smarsh

Bi-directional Slack bridge; Smarsh email archiving/compliance connector.

Threads / Troubleshoot / UserDataDownload / Video_Conference / Webdav Integration

Threads toggle; Troubleshoot switches (disable specific subsystems to isolate issues); GDPR-style user-data export; video conferencing provider config; and WebDAV account integration.

Note

This is the structure of the configuration surface, not an exhaustive key-by-key dump — the registry defines hundreds of keys. Use Admin → Settings → Search to find any key by name, and remember that enableQuery hides settings until their prerequisite is enabled.

8. Authentication & Identity

Rocket.Chat builds on Meteor Accounts and adds many enterprise identity providers.

Two-Factor Authentication

Built-in 2FA supports TOTP and email codes. Key settings (Accounts → Two Factor Authentication): enable master toggle, per-method toggles, code expiration, max invalid attempts, and Remember For duration. Admins can enforce a password fallback. Per-user enrollment happens in the user's account security page.

Brute-force protection

Login Attempts settings block repeated failures by user and by IP, with configurable attempt thresholds, unblock windows, an IP allow-list, and optional notification to a channel on repeated failures.

Important

For SSO deployments, decide whether to allow password login at all. If you rely on SAML/LDAP, consider disabling self-registration (Accounts_RegistrationForm = Disabled) and password changes for OAuth users, and enforce 2FA for any local admin accounts.

9. Authorization: Roles & Permissions

Rocket.Chat uses role-based access control: users hold one or more roles, and roles grant permissions. Permission checks (hasPermission(userId, 'edit-message', roomId?)) can be global or room-scoped.

Built-in roles

admin, moderator, owner, user, guest, bot, app, anonymous, federated-external, and the Omnichannel roles livechat-manager, livechat-monitor, livechat-agent.

Caution

The admin, moderator, and user role identifiers are referenced directly in code and must not be deleted or renamed. You can freely create custom roles and reassign permissions, but leave these intact.

Permission model

Permissions are seeded from apps/meteor/app/authorization/server/constant/permissions.ts. Representative entries:

The full set spans general administration, room/message moderation, teams, Omnichannel, federation, media calls, cloud/registration, and moderation console permissions. Edit them under Admin → Permissions.

Attribute-Based Access Control (EE)

Enterprise deployments add ABAC (ee/packages/abac) — a policy decision point that evaluates attributes (not just static roles) for fine-grained access. An external authorization service (USE_EXTERNAL_ABAC_SERVICE) can offload these decisions.

10. File Storage

Uploaded files are stored in a pluggable backend, selected in Admin → File Upload:

Global upload constraints (max size, allowed media types) are set in the File Upload group. Image uploads are processed with sharp (resizing/thumbnails). The same storage-type choice (GridFS/FileSystem) applies to custom emoji and custom sounds.

Tip

For multi-instance or microservices deployments, do not use the local File System backend unless the path is shared storage — use S3/GCS so every instance can serve every file. GridFS also works across instances since it lives in MongoDB.

11. Real-Time Transport & Horizontal Scaling

DDP and the oplog

The client maintains a DDP websocket to the server for reactive pub/sub. Server-side reactivity is driven by tailing the MongoDB oplog (MONGO_OPLOG_URL). This is why a replica set is mandatory.

Multiple monolith instances

You can run several Rocket.Chat instances against the same MongoDB. They coordinate via:

• instance-status heartbeats (MULTIPLE_INSTANCES_PING_INTERVAL, MULTIPLE_INSTANCES_EXPIRE), each advertising its INSTANCE_IP.
• A load balancer with sticky sessions for websockets.

Microservices (EE)

For larger scale, offload hot paths to dedicated services (presence, DDP streaming, authorization, account, Omnichannel queue) over Moleculer + NATS. The DDP streamer service terminates websockets independently of the main app, letting you scale connection handling separately from business logic. The monolith switches into microservice-aware mode when TRANSPORTER is set (isRunningMs).

Note

DISABLE_MESSAGE_PARSER and other module-level env switches exist to selectively disable subsystems on specific instances (e.g. a worker instance that shouldn't parse messages). Use the Troubleshoot settings group and these switches to isolate load.

12. Omnichannel (Live Chat)

Omnichannel turns the workspace into a customer-engagement platform. Architecture:

• Live Chat widget (the packages/livechat Preact app) embeds on external websites and connects visitors to agents.
• Routing assigns incoming conversations to agents/departments (manual or automatic methods).
• Queue worker (ee/apps/queue-worker) processes the routing queue asynchronously in EE.
• Business hours gate availability; triggers fire proactive messages; canned responses speed replies.
• Transcripts can be emailed or exported as PDF (ee/packages/pdf-worker, omnichannel-transcript service).
• SMS (Twilio) and external-frame channels extend Omnichannel beyond web chat.

Administration lives under Admin → Omnichannel; agent operation is covered in the User Guide. The Omnichannel permission set (view-l-room, close-livechat-room, manage-livechat-agents, manage-livechat-departments, view-livechat-analytics, etc.) maps to the three livechat roles.

Note

Advanced Omnichannel routing and some analytics are Enterprise features. CE includes basic Live Chat; verify which Omnichannel capabilities your license unlocks.

13. Federation

Two federation technologies are available:

• Matrix federation (ee/packages/federation-matrix) bridges your workspace to the Matrix network. Configure the homeserver name, server URL/port (SERVER_VERSION, SERVER_PORT), media limits (MEDIA_MAX_FILE_SIZE, MEDIA_ALLOWED_MIME_TYPES, thumbnails, rate limits), key refresh interval, and its own Mongo/pool settings. Federated users appear as @user:homeserver and carry the federated-external role.
• IRC federation — a separate, legacy bridge (the IRC README warns it is development-grade and discouraged in production).

The access-federation, view-federation-data, and federated-external permissions govern federation access.

Warning

Federation expands your trust boundary to remote servers. Enable it deliberately, restrict which servers you federate with where possible, and review the media size/MIME limits to prevent abuse via remote uploads.

14. The REST API

Rocket.Chat exposes a versioned REST API (/api/v1) alongside the DDP method layer.

Authentication

Most endpoints require two headers obtained from /api/v1/login (or from a Personal Access Token):

curl -H "X-Auth-Token: <authToken>" \
     -H "X-User-Id: <userId>" \
     https://chat.example.com/api/v1/me

• Login: POST /api/v1/login with user/password returns authToken + userId.
• Personal Access Tokens: users with create-personal-access-tokens mint long-lived tokens under My Account; use them as X-Auth-Token/X-User-Id.
• 2FA-protected endpoints require a TOTP/email code header when the user has 2FA enabled.

Endpoint families

The API is organized by domain (typed in packages/rest-typings): chat.* (post/update/delete/react), channels.*, groups.* (private), im.*/dm.* (direct), rooms.*, users.*, teams.*, subscriptions.*, roles.*, permissions.*, settings.*, livechat.*, integrations.*, webdav.*, plus administrative and statistics endpoints.

Rate limiting

The API Rate Limiter and DDP Rate Limiter (Admin → Rate Limiter) throttle request volume. Trusted callers can be granted api-bypass-rate-limit (admin, bot, app by default). API_Upper_Count_Limit caps how many records a list endpoint returns.

Tip

For service accounts and integrations, create a dedicated user with a narrowly-scoped role and a Personal Access Token rather than reusing an admin account. Grant api-bypass-rate-limit only if the integration genuinely needs it.

Webhooks & integrations

• Incoming webhooks accept posts into a room via a generated URL (Slack-compatible payloads supported).
• Outgoing webhooks call external URLs on message triggers.
• Integration management is permission-gated (manage-incoming-integrations, manage-outgoing-integrations, and their manage-own-* variants).

15. Security Hardening

A practical checklist drawn from the available settings and architecture:

• [ ] Force HTTPS. Terminate TLS at the proxy and set Force_SSL / appropriate proxy settings; set a correct ROOT_URL.
• [ ] SSRF protection. Keep the General → SSRF Protection settings enabled so server-side fetches (oEmbed/link previews, avatars) can't be abused to reach internal hosts.
• [ ] Referrer policy. Default_Referrer_Policy defaults to same-origin; keep or tighten it.
• [ ] Iframe access. Iframe_Restrict_Access is on by default — leave it on unless you intentionally embed Rocket.Chat.
• [ ] Password policy. Enabled by default (min length 14, complexity, history) — keep it strict.
• [ ] 2FA. Enforce TOTP for admins at minimum.
• [ ] Brute-force. Keep Login Attempts blocking on (by user and by IP).
• [ ] Rate limiting. Keep DDP and API rate limiters enabled.
• [ ] Registration. Set Accounts_RegistrationForm to Disabled or Secret URL for closed workspaces; use allowed/blocked domain lists.
• [ ] E2EE. Enable for sensitive rooms; understand key-recovery implications.
• [ ] Secrets. Supply SMTP/OAuth/LDAP credentials via OVERWRITE_SETTING_* or secret managers, not committed files.
• [ ] Push privacy. Use the Push → Privacy settings to keep message content out of push payloads if required.
• [ ] Federation. Enable only when needed and constrain media limits.
• [ ] Audit. Enable Login Logs and review the moderation console.

Malicious-input considerations

The message parser (message-parser/gazzodown) renders user content; link previews fetch remote URLs (mitigated by SSRF protection). File uploads are processed by sharp and stored in the configured backend — enforce size and MIME limits in File Upload settings. Integration scripts run in a constrained engine (FREEZE_INTEGRATION_SCRIPTS can lock them down).

Important

Rocket.Chat targets regulated, high-trust deployments. Treat the workspace like any internet-facing app: front it with a hardened reverse proxy, keep MongoDB off the public network, rotate the EE license and admin credentials carefully, and subscribe to the project's security advisories (see SECURITY.md).

16. Monitoring, Health & Observability

Tip

Wire the /health endpoint into your orchestrator's liveness/readiness probes, and scrape Prometheus for event-loop lag and heap usage — those two metrics are the earliest warning signs of an overloaded Node instance.

17. Operations: Start, Stop, Logs, Backup, Upgrade

Start / stop

Lifecycle is managed by your platform: docker compose up -d / down, a Kubernetes Deployment, or a systemd unit for snap/source installs. The Node process reads its env (MONGO_URL, ROOT_URL, PORT, …) at startup. restart-server is an admin permission for in-app restarts.

Logs

• Container: docker logs <rocketchat-container> (Pino JSON or pretty output).
• In-app: Admin → View Logs (view-logs permission).
• Adjust verbosity via Admin → Logs → Log Level or OVERWRITE_SETTING_Log_Level.

Backup

• MongoDB is the system of record. Back it up with mongodump/snapshots on a schedule; this captures messages, users, rooms, settings, and (for GridFS) uploaded files.
• External file stores (S3/GCS/filesystem/WebDAV) must be backed up separately if not using GridFS.
• EE license and your env/IaC (settings overrides) should be version-controlled.

Upgrade

1. Read the release notes / changelog for breaking changes and required MongoDB/Node versions.
2. Back up MongoDB (and file store).
3. Upgrade one minor version at a time — do not skip across major versions.
4. Pull the new image / chart and restart; Rocket.Chat runs DB migrations on boot (run-migration permission for manual control).
5. Verify health (/health), then smoke-test login, messaging, and uploads.

Caution

Never skip major versions during upgrades, and never point a new Rocket.Chat version at a database you haven't backed up. Migrations are forward-only; a failed mid-upgrade state is far easier to recover from a snapshot than to repair in place.

Data retention

Configure Retention Policy to auto-prune old messages globally and per-room-type, reducing database growth. Combine with MongoDB TTL/compaction strategies for long-running, high-volume workspaces.

18. Enterprise Edition & Licensing

• CE vs EE. The MIT-licensed CE is the base. EE code lives under apps/meteor/ee/, ee/apps/, and ee/packages/, governed by the Rocket.Chat EE License (see apps/meteor/ee/LICENSE).
• License validation. ee/packages/license validates the ROCKETCHAT_LICENSE key and gates features (microservices, advanced Omnichannel, ABAC, engagement dashboard, etc.). LICENSE_DEBUG / LICENSE_VALIDATION_SUPPRESS_LOG aid troubleshooting.
• Cloud registration. The Setup Wizard's Cloud Info connects the workspace to Rocket.Chat Cloud for license sync, push, and marketplace.

Note

Running EE features in production requires a valid subscription for the correct number of seats. CE remains fully functional for core collaboration without a license.

19. Developer Internals

Build & develop from source

# Prerequisites: Node 22.22.3, Yarn 4.12.0 (via Corepack), Meteor 3.4.1, MongoDB replica set
corepack enable
yarn                    # install workspace deps
yarn dev                # turbo run dev (filtered to @rocket.chat/meteor)
yarn build              # turbo run build (all workspaces)
yarn lint               # turbo run lint
yarn testunit           # turbo run testunit
yarn ms                 # run microservices locally

The repo is a Turbo + Yarn 4 workspaces monorepo. turbo.json defines the task graph; most packages build independently and the Meteor app composes them.

Key extension points

Testing

• Unit: Jest (tests/unit, package-level *.spec.ts).
• Integration / end-to-end API: apps/meteor/tests/end-to-end/api (large suite exercising REST endpoints).
• UI e2e: Playwright (apps/meteor/tests/e2e), including federation and SAML container setups.

Apps-Engine architecture

Apps are sandboxed and communicate with the core through bridges (data adapters) and converters (schema translation), orchestrated server- and client-side. Third-party app code runs in a Deno runtime (packages/apps/deno-runtime) for isolation.

Internationalization

All UI strings are translation keys resolved by packages/i18n (and the legacy rocketchat-i18n package). Custom packages must contribute their translations into the i18n package to be respected.

20. Troubleshooting

Server won't connect to MongoDB / no real-time updates

Cause: MongoDB is not a replica set, or MONGO_OPLOG_URL is wrong/unset.

Solution: Deploy MongoDB as a replica set and run rs.initiate() once. Set both MONGO_URL and MONGO_OPLOG_URL (the latter pointing at the local db). Without the oplog, messages won't appear in real time.

Websockets fail behind the proxy

Cause: The reverse proxy isn't upgrading websocket connections, or isn't routing /websocket (and /sockjs) correctly — especially in microservices mode where these go to the DDP streamer.

Solution: Enable websocket upgrade headers on the proxy; in microservices mode route PathPrefix(/websocket) || PathPrefix(/sockjs) to ddp-streamer-service and everything else to the main app. Use sticky sessions across multiple instances.

Direct_Reply / SMTP errors

Cause: Misconfigured mail credentials or protocol.

Solution: Verify SMTP host/port/protocol and credentials in Admin → Email → SMTP; use the Send test mail action. For inbound email replies, confirm IMAP/POP host and that Direct_Reply_Enable is on.

Users can't register

Cause: Accounts_RegistrationForm = Disabled, manual approval pending, or domain not on the allowed list.

Solution: Adjust the Registration settings, approve users in Admin → Users, or fix Accounts_AllowedDomainsList.

EE features greyed out / "invalid license"

Cause: Missing/expired ROCKETCHAT_LICENSE or seat-count exceeded.

Solution: Apply a valid license; check logs with LICENSE_DEBUG=true. Confirm cloud registration if the license is cloud-managed.

High event-loop lag / slow UI

Cause: Single instance overloaded; heavy oplog volume; unindexed query patterns.

Solution: Scale out (more instances, or microservices for presence/DDP), enable Prometheus and watch EVENT_LOOP_LAG_MS/heap, apply a Retention Policy to shrink hot collections, and ensure MongoDB is appropriately sized and indexed.

File uploads fail in multi-instance setups

Cause: Using the local File System backend without shared storage.

Solution: Switch File Upload to S3/GCS/GridFS so every instance can serve every file.

Push notifications not delivered

Cause: Push gateway not configured, or privacy settings stripping content.

Solution: Configure Admin → Push (gateway, certificates). Review Push → Privacy for content visibility expectations.

21. Potential Improvements & Tech Debt

Observations a maintainer or operator might act on (derived from the codebase shape, not prescriptive):

• Deployment compose drift. The repo ships docker-compose-ci.yml and docker-compose-local.yml aimed at CI and microservices development, not a turnkey single-node production stack. Operators must assemble production compose/Helm from the docs; a tracked, opinionated production compose would reduce setup error (e.g. the easy-to-miss replica-set initialization).
• Settings discoverability. With hundreds of keys across ~40 groups, there is no single in-repo, generated settings reference. A generated catalog (id, type, default, group, enableQuery, env-overridable) would help admins and auditors.
• Legacy/experimental modules. IRC federation and some OAuth providers (Drupal, Dolphin) are clearly older; the IRC README itself discourages production use. Flagging deprecated integrations in-product would set expectations.
• Mandatory replica set. The hard dependency on the MongoDB oplog makes the simplest "just run mongod" setup unsupported; clearer first-boot validation/errors would shorten the time-to-diagnosis for new operators.
• Microservices complexity. The split between monolith and EE microservices is powerful but raises operational complexity (NATS, Moleculer, websocket routing). Strong defaults and health checks per service mitigate this; thorough runbooks are essential before adopting it.

22. Quick Reference

Versions

Essential environment variables

Endpoints & ports

Admin areas

Key source locations