# 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](#1-executive-summary)
2. [Architecture](#2-architecture)
3. [Repository Structure](#3-repository-structure)
4. [System Requirements](#4-system-requirements)
5. [Installation & Deployment](#5-installation--deployment)
6. [Configuration: The Settings System](#6-configuration-the-settings-system)
7. [Settings Reference by Group](#7-settings-reference-by-group)
8. [Authentication & Identity](#8-authentication--identity)
9. [Authorization: Roles & Permissions](#9-authorization-roles--permissions)
10. [File Storage](#10-file-storage)
11. [Real-Time Transport & Horizontal Scaling](#11-real-time-transport--horizontal-scaling)
12. [Omnichannel (Live Chat)](#12-omnichannel-live-chat)
13. [Federation](#13-federation)
14. [The REST API](#14-the-rest-api)
15. [Security Hardening](#15-security-hardening)
16. [Monitoring, Health & Observability](#16-monitoring-health--observability)
17. [Operations: Start, Stop, Logs, Backup, Upgrade](#17-operations-start-stop-logs-backup-upgrade)
18. [Enterprise Edition & Licensing](#18-enterprise-edition--licensing)
19. [Developer Internals](#19-developer-internals)
20. [Troubleshooting](#20-troubleshooting)
21. [Potential Improvements & Tech Debt](#21-potential-improvements--tech-debt)
22. [Quick Reference](#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

```text
                          ┌─────────────────────────────────────────┐
        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:

| Package | Responsibility |
|---------|----------------|
| `core-typings` | Shared domain TypeScript types (IRoom, IUser, IMessage, …) |
| `model-typings` / `models` | MongoDB model interfaces and raw model implementations (`BaseRaw`) |
| `rest-typings` | Typed contracts for every REST endpoint |
| `ddp-client` | DDP client + typed `ServerMethods` |
| `core-services` | Service abstractions used by both monolith and microservices |
| `apps-engine` | The app runtime framework (definitions, bridges, sandboxed execution) |
| `fuselage-ui-kit` / `ui-*` | UI Kit rendering and component libraries |
| `i18n` | Translations (30+ languages) |
| `agenda` / `cron` | Job scheduling |
| `logger` / `log-format` | Pino-based logging |
| `tracing` | OpenTelemetry-style tracing hooks |
| `password-policies` | Password policy enforcement |
| `message-parser` / `gazzodown` | Message markup parsing and rendering |
| `instance-status` | Multi-instance presence/heartbeat bookkeeping |

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

These run as **standalone microservices** when you scale out:

| Service / package | Role |
|-------------------|------|
| `ee/apps/authorization-service` | Permission checks as a service (`USE_EXTERNAL_ABAC_SERVICE`) |
| `ee/apps/account-service` | Account operations |
| `ee/apps/presence-service` | Online/away presence aggregation |
| `ee/apps/ddp-streamer` | Dedicated DDP websocket gateway (`/websocket`, `/sockjs`) |
| `ee/apps/queue-worker` | Background Omnichannel queue processing |
| `ee/apps/omnichannel-transcript` | Chat transcript generation |
| `ee/packages/federation-matrix` | Matrix federation bridge |
| `ee/packages/license` | License validation and EE feature gating |
| `ee/packages/abac` | Attribute-based access control (policy decision point) |
| `ee/packages/presence` | Presence library |
| `ee/packages/network-broker` | Moleculer service broker wiring |
| `ee/packages/pdf-worker` | PDF generation (transcripts, exports) |

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

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

| Component | Requirement |
|-----------|-------------|
| **Node.js** | `22.22.3` (pinned in `engines`) |
| **Package manager** | Yarn `4.12.0` (Corepack) — for building from source |
| **MongoDB** | A supported MongoDB version, deployed as a **replica set** (required for oplog tailing / reactivity) |
| **Meteor** | `3.4.1` (only when building from source) |
| **Memory** | Production workspaces should provision generous RAM; the Node process plus MongoDB are the main consumers |
| **Reverse proxy** | Recommended (Traefik or nginx) for TLS termination and websocket routing |
| **NATS** | Required only for the microservices topology (as the Moleculer transporter) |

> [!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](https://docs.rocket.chat/docs/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

| Method | Best for | Notes |
|--------|----------|-------|
| **Docker / Podman** | Most self-hosted deployments | Official images on `ghcr.io` / Docker Hub |
| **Kubernetes (Helm)** | Production at scale, HA | Microservices, autoscaling |
| **Launchpad** | Quick Kubernetes setup | Managed dependency provisioning |
| **Air-gapped** | High-security / regulated | No internet egress |
| **Snap** | Quick single-host trials | `rocketchat-server` snap |
| **From source** | Development / contribution | Meteor + Yarn build |

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

| Variable | Purpose |
|----------|---------|
| `ROOT_URL` | The canonical public URL of the workspace (e.g. `https://chat.example.com`) |
| `MONGO_URL` | MongoDB connection string (`mongodb://host:27017/rocketchat?replicaSet=rs0`) |
| `MONGO_OPLOG_URL` | Oplog connection string (`mongodb://host:27017/local?replicaSet=rs0`) for reactivity |
| `PORT` | Port the Node server binds (default `3000`) |
| `INSTANCE_IP` | This instance's IP for multi-instance presence |
| `DEPLOY_METHOD` / `DEPLOY_PLATFORM` | Telemetry labels describing how/where it runs |
| `TRANSPORTER` | Moleculer transporter (e.g. `nats://nats:4222`) — enables microservices mode |
| `MULTIPLE_INSTANCES_PING_INTERVAL` / `MULTIPLE_INSTANCES_EXPIRE` | Inter-instance heartbeat tuning |
| `MAX_RESUME_LOGIN_TOKENS` | Cap on stored resume login tokens per user |
| `PROMETHEUS_PORT` / `BIND_IP` | Prometheus metrics exporter port and bind address |
| `OVERWRITE_SETTING_<id>` | Force a setting value at startup (overrides DB) |
| `ROCKETCHAT_LICENSE` | EE license key |

> [!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:

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

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

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

| Option | Meaning |
|--------|---------|
| `type` | `boolean`, `int`, `string`, `select`, `multiSelect`, `code`, `color`, `password`, `action`, `range`, `relativeUrl`, … |
| `public` | If true, the value is exposed to the client (non-secret) |
| `secret` | Marks a sensitive value (hidden/redacted) |
| `enableQuery` | Conditional visibility: setting is active only when another setting matches |
| `env` | The value may be supplied via an environment variable |
| `hidden` | Not shown in the UI (internal counters/state) |
| `i18nLabel` / `i18nDescription` | Translation keys for the UI |
| `alert` | A warning banner shown beside the setting |
| `values` | Allowed options for `select` / `multiSelect` |

### 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.

| Mechanism | Where configured | Notes |
|-----------|------------------|-------|
| **Email + password** | Accounts group | Subject to the password policy (default min length 14, complexity on) and password history |
| **OAuth** | OAuth group | Google, GitHub(+Enterprise), GitLab, Facebook, Apple, Twitter, Linkedin, Nextcloud, WordPress, Dolphin, Drupal, Meteor, plus **Custom OAuth** |
| **SAML 2.0** | (SAML admin) | `meteor-accounts-saml`; supports SP-initiated login, single logout (`idpSLORedirectURL`), request signing (`SAML_Custom_Private_Key`/`Public_Cert`), attribute mapping |
| **LDAP / Active Directory** | LDAP group | Connection, encryption, user/group filters, data-sync field mapping, avatar sync |
| **CAS** | CAS group | Apereo CAS 1.0/2.0 with attribute sync |
| **Atlassian Crowd** | AtlassianCrowd group | Directory sync on a cron interval |

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

| Permission | Default roles |
|------------|---------------|
| `access-permissions`, `access-setting-permissions` | admin |
| `create-c` / `create-p` / `create-d` | admin, user, federated-external, bot, app |
| `create-user`, `delete-user`, `edit-other-user-info` | admin |
| `edit-message`, `delete-message` | admin, owner, moderator |
| `delete-own-message` | admin, user, federated-external |
| `pin-message` | owner, moderator, admin |
| `mute-user`, `ban-user`, `remove-user` | admin, owner, moderator |
| `mention-all`, `mention-here` | admin, owner, moderator, user, federated-external |
| `archive-room`, `unarchive-room` | admin, owner / admin |
| `edit-privileged-setting`, `view-privileged-setting` | admin |
| `manage-apps`, `manage-cloud`, `manage-oauth-apps` | admin |
| `view-statistics`, `view-logs`, `view-user-administration` | admin |
| `toggle-room-e2e-encryption` | owner, admin |
| `create-team`, `delete-team`, `convert-team` | admin, owner |
| `view-l-room`, `close-livechat-room`, `transfer-livechat-guest` | livechat roles + admin |
| `api-bypass-rate-limit` | admin, bot, app |
| `export-messages-as-pdf` | admin, user |

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

| Backend | Setting context | Use when |
|---------|-----------------|----------|
| **GridFS** | (default) | Files stored in MongoDB; simplest, no external deps |
| **File System** | File System section | Local/NFS path; good for single-node |
| **Amazon S3** | Amazon S3 section | Scalable object storage / CDN |
| **Google Cloud Storage** | GCS section | GCP-native object storage |
| **WebDAV** | WebDAV section | Existing WebDAV/Nextcloud/ownCloud store |

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

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

| Surface | How | Notes |
|---------|-----|-------|
| **Prometheus metrics** | `prom-client` exporter on `PROMETHEUS_PORT` (bind via `BIND_IP`) | Enable under Admin → Logs → Prometheus; scrape with Prometheus/Grafana |
| **Health endpoint** | `/health` route | Reports liveness; thresholds tunable via `EVENT_LOOP_LAG_MS`, `HEAP_USAGE_PERCENT` |
| **Logging** | Pino (`packages/logger`) | Level via Admin → Logs or `OVERWRITE_SETTING_Log_Level`; `LESS_INFO_LOGS` reduces noise |
| **Tracing** | `packages/tracing` | Enable with `TRACING_ENABLED`; `LOG_UNTRACED_METHODS` for diagnostics |
| **Statistics** | `app/statistics` | Workspace telemetry (deploy method/platform, counts), surfaced in Admin → Statistics and sent to Rocket.Chat Cloud |
| **Engagement dashboard** | Admin (EE) | Usage analytics (`view-engagement-dashboard`) |

> [!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

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

| To... | Work in... |
|-------|-----------|
| Add a setting | `apps/meteor/server/settings/<group>.ts` via `settingsRegistry` |
| Add a permission | `apps/meteor/app/authorization/server/constant/permissions.ts` |
| Add a slash command | a new `apps/meteor/app/slashcommands-<name>/` module |
| Add a REST endpoint | `apps/meteor/app/api/server/v1/` with a `rest-typings` contract |
| Add a DDP method | `Meteor.methods<ServerMethods>({...})` with a `ddp-client` type augmentation |
| Add a model | `packages/models` + `packages/model-typings` (extend `BaseRaw`) |
| Build a third-party app | the **Apps-Engine** (`packages/apps-engine`) |

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

| Component | Version |
|-----------|---------|
| Rocket.Chat | `8.6.0-develop` (@ `121e19f`) |
| Meteor | `3.4.1` |
| Node.js | `22.22.3` |
| Yarn | `4.12.0` |
| MongoDB driver | `6.16.0` |
| React | `18.3.1` |
| Moleculer | `0.14.35` |

### Essential environment variables

| Variable | Purpose |
|----------|---------|
| `ROOT_URL` | Public workspace URL |
| `MONGO_URL` | MongoDB connection (replica set) |
| `MONGO_OPLOG_URL` | Oplog connection (reactivity) |
| `PORT` | Server port (default 3000) |
| `TRANSPORTER` | Moleculer transporter → enables microservices |
| `ROCKETCHAT_LICENSE` | EE license key |
| `PROMETHEUS_PORT` / `BIND_IP` | Metrics exporter |
| `OVERWRITE_SETTING_<id>` | Pin a runtime setting at startup |
| `INSTANCE_IP` | Instance identity for multi-instance presence |

### Endpoints & ports

| Path / port | Serves |
|-------------|--------|
| `/` | Web app + REST API (`/api/v1`) |
| `/websocket`, `/sockjs` | DDP websocket (main app, or `ddp-streamer` in MS mode) |
| `/health` | Health/liveness probe |
| `:PROMETHEUS_PORT/metrics` | Prometheus metrics |
| `:3000` (default) | Main HTTP port |

### Admin areas

| Area | Permission |
|------|-----------|
| Settings | `view-privileged-setting` / `edit-privileged-setting` |
| Users | `view-user-administration` |
| Permissions | `access-permissions` |
| Rooms | `view-room-administration` |
| Apps / Marketplace | `manage-apps` / `access-marketplace` |
| Statistics | `view-statistics` |
| Logs | `view-logs` |
| Omnichannel | livechat roles + `admin` |

### Key source locations

| What | Where |
|------|-------|
| Settings definitions | `apps/meteor/server/settings/*.ts` |
| Permissions seed | `apps/meteor/app/authorization/server/constant/permissions.ts` |
| REST API v1 | `apps/meteor/app/api/server/` |
| Slash commands | `apps/meteor/app/slashcommands-*/` |
| Models | `packages/models`, `packages/model-typings` |
| Apps-Engine | `packages/apps-engine` |
| EE services | `ee/apps/*` |

---

_Generated June 2026 from RocketChat/Rocket.Chat at 121e19f. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._