Documentation Index

Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt

Use this file to discover all available pages before exploring further.

Server Environment Setup

Prev Next

This guide walks you through configuring your local development environment required to build, test, and modify the Rocket.Chat core server from source code.

⚠️ This is not a deployment guide. If you want to deploy a workspace for your team or organization, refer to Deploy Rocket.Chat. The recommended deployment methods are Docker and Kubernetes.

Choose the tab corresponding to your operating system:

Prerequisites

  • 12 GB RAM (16+ GB highly recommended)

  • Use a standard user account (not root) for setup. Avoid using sudo to prevent potential file permission issues.

  • Fork the Rocket.Chat repository on GitHub.

The following steps use Ubuntu as the reference distribution, but apply to most Debian-based distributions.

Step 1: Clone the Rocket.Chat Repo

  1. Update system packages and install core build utilities:

    sudo apt update && sudo apt dist-upgrade -y
sudo apt install git curl unzip make build-essential python3 g++

  2. Clone the forked repository:

    git clone https://github.com/<your-username>/Rocket.Chat.git

  3. Navigate to the Rocket.Chat root directory:

    cd Rocket.Chat

    Unless otherwise specified, run all subsequent commands in this guide from this Rocket.Chat root directory.

Step 2: Setting up Node.js and Yarn

  1. Install Node Version Manager (nvm) to manage Node.js versions required for Rocket.Chat:

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
source ~/.bashrc
nvm --version

  2. Inspect package.json to identify the required Node.js version:

    cat package.json | grep -A4 engines | grep node

  3. Install that Node.js version with nvm, replacing x.x.x with the version from the previous step:

    nvm install x.x.x

  4. Verify the installed Node.js version:

    node -v

  5. Install Yarn globally and verify:

    npm install -g yarn
yarn --version

Step 3: Setting up Deno

  1. Confirm the Deno version required by your Rocket.Chat project:

    cat .tool-versions | grep deno

  2. Install the required Deno version, replacing x.x.x with the version from the previous step:

    curl -fsSL https://deno.land/install.sh | sh -s vx.x.x

    For alternative installation methods, check the official Deno installation documentation.

  3. Add Deno to your PATH:

    echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

  4. Verify the installation:

    deno --version

Step 4: Installing Meteor

Rocket.Chat pins its Meteor version in the .meteor/release file.

  1. From the Rocket.Chat directory, confirm the Meteor version required by your Rocket.Chat project:

    cat apps/meteor/.meteor/release

  2. Install Meteor, replacing x.x.x with the version from the previous step:

    curl https://install.meteor.com/\?release\=x.x.x | sh

  3. After installation, verify the version:

    meteor --version

Step 5: Run the Rocket.Chat project

The commands in this step must be run from the Rocket.Chat root folder. Otherwise, MongoDB will not start.

  1. Install all the dependencies:

    yarn

  2. When completed, build and run the server by executing this command:

    yarn dsv

    • The first build can take ten or more minutes. Subsequent dev builds will take lesser time.

    • During the build, you may notice warnings about peer or transitive dependencies. These are typically safe to ignore unless you are developing the specific features or modules that require them

  3. After the build completes, open:

    http://localhost:3000

    You should see your Rocket.Chat workspace running locally.

Step 6: Edit Rocket.Chat files

You can use any code editor, but Visual Studio Code is recommended for the best development experience.

  • Launch your IDE and open the cloned repository folder in your IDE.

  • When you make changes to Rocket.Chat the server will automatically rebuild.

  • If the server stops after a change, restart it with:

    yarn dsv

This guide is suitable for macOS systems running on Apple silicon or Intel processors.

Prerequisites

Install the following dependencies before you begin:

  • Homebrew: Package manager for macOS used to install required system dependencies.

  • Yarn: Package manager used to install project dependencies.

Verify that each dependency is installed:

brew --version
yarn --version

Step 1: Clone the Rocket.Chat repository

  1. Fork the official Rocket.Chat repository .

  2. Clone your fork and navigate to the repository:

    git clone https://github.com/<your-username>/Rocket.Chat.git
cd Rocket.Chat

    Unless otherwise specified, run all subsequent commands in this guide from this Rocket.Chat root directory.

  3. Add the official Rocket.Chat repository as an upstream remote if you want to keep your fork synchronized:

    git remote add upstream https://github.com/RocketChat/Rocket.Chat

Step 2: Install Node.js

  1. Install Node Version Manager (nvm) to manage Node.js versions required for Rocket.Chat:

    brew install nvm

  2. Confirm nvm is version 0.39.2 or higher:

    nvm --version

  3. Check the Node.js version the project requires:

    cat package.json | grep -A4 engines | grep node

  4. Install the required Node.js version (replace x.x.x with the version shown above):

    nvm install x.x.x

  5. Check the node version installed by running: 

    node -v

    Ensure the output matches the required version.

Step 3: Set up Deno

Rocket.Chat requires a specific version of Deno for certain development tools and scripts.

  1. Confirm the Deno version required for your RocketChat project by running this command:

    cat .tool-versions | grep deno

  2. Install the required Deno version, replacing x.x.x with the version above:

    curl -fsSL https://deno.land/install.sh | sh -s vx.x.x

    For alternative installation methods, see the official Deno installation documentation.

  3. Add Deno to your PATH permanently to make it available in future sessions:

    echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

  4. Confirm the version matches:

    deno --version

Step 4: Install Meteor

Rocket.Chat pins its Meteor version in the .meteor/release file.

  1. From the Rocket.Chat root directory, confirm the Meteor version required by your project:

    cat apps/meteor/.meteor/release

  2. Install Meteor, replacing x.x.x with the version from the previous step:

    curl https://install.meteor.com/\?release\=x.x.x | sh

  3. After installation, verify the version:

    meteor --version

Step 5: Run the Rocket.Chat project

The commands in this step must be run from the Rocket.Chat root folder. Otherwise, MongoDB will not start.

  1. Install all the dependencies:

    yarn

  2. Start your development server:

    yarn dsv

    • The first build can take ten or more minutes. Subsequent builds will take lesser time.

    • During the build, you may notice warnings about peer or transitive dependencies. These are typically safe to ignore unless you are developing the specific features or modules that require them

  3. After the build completes, open:

    http://localhost:3000

    You should see your Rocket.Chat workspace running locally.

Step 6: Edit Rocket.Chat files

You can use any code editor, but Visual Studio Code is recommended for the best development experience.

  • Launch your IDE and open the cloned repository folder in your IDE.

  • When you make changes to Rocket.Chat the server will automatically rebuild.

  • If the server stops after a change, restart it with:

    yarn dsv

Prerequisites

  • WSL 2 (Ubuntu distribution)

  • 12 GB RAM (16+ GB highly recommended)

  • Four or more cores on CPU (at least 3 GHz boosted, 4.2 GHz or higher recommended)

  • 80 GB of available fast SSD storage (PCIe 4.0 NVMe SSD recommended)

  • Fork the Rocket.Chat repository on GitHub.

All the setup steps below for the Windows development environment must be performed within the Ubuntu WSL 2 shell.

Step 1: Clone the Rocket.Chat Repo

  1. Update system packages and install core build utilities:

    sudo apt update && sudo apt dist-upgrade -y
sudo apt install git curl unzip make build-essential python3 g++

  2. Clone the forked repository:

    git clone https://github.com/<your-username>/Rocket.Chat.git

  3. Navigate to the Rocket.Chat root directory:

    cd Rocket.Chat

    Unless otherwise specified, run all subsequent commands in this guide from this Rocket.Chat root directory.

Step 2: Setting up Node.js and Yarn

  1. Install Node Version Manager (nvm) to manage Node.js versions required for Rocket.Chat:

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
source ~/.bashrc
nvm --version

  2. Inspect package.json to identify the required Node.js version:

    cat package.json | grep -A4 engines | grep node

  3. Install that Node.js version with nvm, replacing x.x.x with the version from the previous step:

    nvm install x.x.x

  4. Verify the installed Node.js version:

    node -v

  5. Install Yarn globally and verify:

    npm install -g yarn
yarn --version

Step 3: Setting up Deno

  1. Confirm the Deno version required by your Rocket.Chat project:

    cat .tool-versions | grep deno

  2. Install the required Deno version, replacing x.x.x with the version from the previous step:

    curl -fsSL https://deno.land/install.sh | sh -s vx.x.x

    For alternative installation methods, check the official Deno installation documentation.

  3. Add Deno to your PATH:

    echo 'export PATH="$HOME/.deno/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

  4. Verify the installation:

    deno --version

Step 4: Installing Meteor

Rocket.Chat pins its Meteor version in the .meteor/release file.

  1. From the Rocket.Chat directory, confirm the Meteor version required by your Rocket.Chat project:

    cat apps/meteor/.meteor/release

  2. Install Meteor, replacing x.x.x with the version from the previous step:

    curl https://install.meteor.com/\?release\=x.x.x | sh

  3. After installation, verify the version:

    meteor --version

Step 5: Run the Rocket.Chat project

The commands in this step must be run from the Rocket.Chat root folder. Otherwise, MongoDB will not start.

  1. Install all the dependencies:

    yarn

  2. When completed, build and run the server by executing this command:

    yarn dsv

    • The first build can take ten or more minutes. Subsequent dev builds will take lesser time.

    • During the build, you may notice warnings about peer or transitive dependencies. These are typically safe to ignore unless you are developing the specific features or modules that require them

  3. After the build completes, open:

    http://localhost:3000

    You should see your Rocket.Chat workspace running locally.

Step 6: Edit Rocket.Chat files

You can use any code editor, but Visual Studio Code is recommended for the best development experience.

  • Launch your IDE and open the cloned repository folder in your IDE.

  • When you make changes to Rocket.Chat the server will automatically rebuild.

  • If the server stops after a change, restart it with:

    yarn dsv

References

If you encounter any issues during the setup, refer to the development environment troubleshooting guide for assistance.

Now that your development server is running, you can contribute to the Rocket.Chat server! See participate in Rocket.Chat development to learn more about Rocket.Chat contributions.

Rocket.Chat versions receive support for six months after release. End-of-life for any version is the last day of the month when support ends.