Skip to content

Latest commit

 

History

History
300 lines (198 loc) · 12.3 KB

deploy-with-docker-and-docker-compose.md

File metadata and controls

300 lines (198 loc) · 12.3 KB

Deploy with Docker & Docker Compose

{% hint style="info" %} As of December 15, 2023, Rocket.Chat has ceased support for connections from cloud services and official mobile/desktop apps to workspaces running legacy versions outside our support window. Users on unsupported legacy servers are advised to upgrade to the latest Rocket.Chat version to ensure continued access to cloud, mobile, and desktop applications. Each Rocket.Chat version is supported for six months post-release. {% endhint %}

Deploying Rocket.Chat with Docker and Docker Compose is a straightforward and highly recommended deployment method due to its simplicity and flexibility. This guide will walk you through the essential steps, whether you're a seasoned Docker expert or new to containerization, ensuring a smooth deployment for your Rocket.Chat workspace.

In this guide, you'll learn how to:

Preparation Steps

Installing Docker and Docker Compose

  • Ensure you have Docker and Docker-compose (v2 is required) installed and operational. If you don't have them installed, you can conveniently set them up using Docker's official helper script:
curl -L https://get.docker.com | sh
  • To run Docker commands without using sudo, add the current user to the Docker group and then reboot using the following commands:
sudo usermod -aG docker $USER
sudo reboot

Deploy Rocket.Chat on Docker

Fetching Compose file

  • Navigate to your preferred directory and create a compose.yml file following our example. Alternatively, you can use the curl command to download the example compose.yml file by executing this command:
curl -L https://raw.githubusercontent.com/RocketChat/Docker.Official.Image/master/compose.yml -O

Editing Environment Variables

Modifying the configurations in the compose file directly is strongly discouraged. Instead, use environment variables. You can set environment variables using a .env file.

{% hint style="warning" %} Remember to uncomment the variables you are updating in the .env file. {% endhint %}

  • In your project directory, create a .env file with this command and paste the contents of this example file 
sudo nano .env

{% hint style="info" %} If you cloned the GitHub repository, you can copy the .env.example to .env with this command:

cp env.example .env

{% endhint %}

  • Set the RELEASE variable in the .envto your desired Rocket.Chat version.

{% hint style="info" %} See our releases page and available docker images. Keeping the default release aslatest is not recommended. {% endhint %}

  • Edit ROOT_URL from the default http://localhost:3000 to match your domain name or IP address.
  • If you have a registration token to register the workspace automatically, you can add it to the .env file like this:
REG_TOKEN={your token here}
  • If you are using MongoDB Atlas as the database provider, edit the value of the MONGO_URL variable to be your connection string in this format:
MONGO_URL=mongodb://<user>:<pass>@host1:27017,host2:27017,host3:27017/<databaseName>?replicaSet=<replicaSet>&ssl=true&authSource=admin
  • Save the .env file and start up the container by executing this command:
docker compose up -d

This command will:

  • Start a MongoDB service named mongodb.
  • Start a service rocketchat, which will also wait for mongodb to be ready.

{% hint style="info" %} MongoDB ensures continuous 24 x 7 operations and live backup, reducing the need for frequent restarts. Refer to the MongoDB documentation for proper server operation and management. Optionally, manage messages and configurations by uncommenting the volume mounts, and ensuring a data subdirectory is available for data storage and mounting. {% endhint %}

Once the container is running, visit http://localhost:3000 on your browser. You can now explore your Rocket.Chat workspace and invite other users.

Start & Stop Docker Compose

To stop your workspace from running, execute this command:

docker compose down

To start your docker-compose container, run this command:

docker compose up -d

To see the log/status of your Rocket.Chat container, execute this command:

docker compose logs -f rocketchat

Rocket.Chat Docker Images

Official image (stable and tested)

The Official Docker Images Repository is responsible for maintaining and controlling Rocket.Chat's official stable image through Docker. It is also reviewed by the Docker committee.

docker pull registry.rocket.chat/rocketchat/rocket.chat

Latest Release Image

This is an image that holds the latest stable Rocket.Chat updates on the docker repository. The release may be from the develop or master branch.

docker pull registry.rocket.chat/rocketchat/rocket.chat:latest

Preview Image

The Rocket.Chat preview image deploys a container with a database inside. It's useful for quickly trying or running tests, not requiring a dedicated database installation.

{% embed url="https://hub.docker.com/r/rocketchat/rocket.chat.preview" %}

Specific Release Image

You can set up your Rocket.Chat workspace with a specific release image. Select the release you need from the docker hub tags and use it to run the following command: 

docker pull registry.rocket.chat/rocketchat/rocket.chat:<release-tag>

Bleeding-edge untested develop build image

This is an image maintained at Rocket.Chat's docker repository was updated from the develop (untested) branch, containing the latest updates for those who want to work with the newest features.

docker pull registry.rocket.chat/rocketchat/rocket.chat:develop

Updating Rocket.Chat on Docker

{% hint style="info" %} Before you proceed, see the general guidelines for updating Rocket.Chat. {% endhint %}

{% hint style="warning" %} Updating the Rocket.Chat image doesn't affect your data since it exists in the Mongo image. Ensure that the version of your MongoDB is compatible with the intended release before proceeding with the update. {% endhint %}

Using Docker & Docker compose, you can update your rocketchat docker image to the latest or preferred version of Rocket.Chat.

To update your Rocket.Chat version,

  • For a specific version, modify the RELEASE variable in the .env file to point to the docker image tag of that version. Alternatively, you can edit the compose.yml file to point to the desired Rocket.Chat version.
Changing version in .env

In the .env file, change the RELEASE value to your specified version.

RELEASE=<desired version>
Changing version in compose.yml

In the compose.yml file, change the rocketchat service image value to point to an image in the rocketchat registry image with a tag of your desired version.

services:
  rocketchat:
    image:registry.rocket.chat/rocketchat/rocket.chat:<desired version>
  • For the latest version, use latest as the RELEASE variable in the .env file. Alternatively, you can pull the Rocket.Chat image directly with the latest tag with this command:
docker pull registry.rocket.chat/rocketchat/rocket.chat:latest
  • Now, stop, remove and restart the existing container with these commands:
docker compose stop rocketchat
docker compose rm rocketchat
docker compose up -d rocketchat

{% hint style="info" %} See #rocket.chat-docker-images for more details on Rocket.Chat docker images. {% endhint %}

Enable HTTPs

You can secure your Rocket.Chat docker instance with TLS certificates from Let's Encrypt. Using Traefik as a reverse proxy, the certificates are automatically generated, enabling safe access to your Rocket.Chat instance via HTTPS on your specified domain.

To get HTTPS, ensure the correct A record (optionally CNAME) is set for your domain going to your server IP.

  • Update the following variables in your .env file. If you don't have one, create a .env file following our example.
    • LETSENCRYPT_EMAIL: Your required email for the TLS certificates.
    • DOMAIN: Your domain or subdomain name only. Avoid adding https:// or any trailing slashes. Confirm that this domain resolves to the server IP address.
    • RELEASE : Your preferred Rocket.Chat release. See the releases page to know more about our releases.
    • DOMAIN : Set the value to "https://your-domain.com," replacing "your-domain.com" with the domain name you want to use.
    • BIND_IP: Set to 127.0.0.1 .
LETSENCRYPT_EMAIL= # your email, required for the tls certificates
# set this to your domain name or subdomain, not trailing slashes or https://, just the domain
# make sure it actually resolves to your droplet ip
DOMAIN= 
RELEASE= # pin the rocketchat version, at the time of writing, prefer 6.0.0
ROOT_URL= # set this to https://${DOMAIN} replace ${DOMAIN} with the actual domain
BIND_IP=127.0.0.1
  • Download the traefik template by running the following command:
curl -LO \
    https://raw.githubusercontent.com/RocketChat/Docker.Official.Image/master/traefik.yml
  • Recreate the existing Rocket.Chat container
docker compose up -d rocketchat --force-recreate
  • Star traefik
docker compose -f traefik.yml up -d

Wait for the TLS certificates to generate and Rocket.Chat to restart. Then, access your Rocket.Chat instance securely at https://your-domain.com, using the actual domain name you configured.

Docker Mongo Backup and Restore

To back up your MongoDB database in docker,

  • Run the following command on your terminal to list out all running containers:
docker ps -a

{% hint style="warning" %} Take note of your mongo container name. {% endhint %}

  • Run this command to dump the database into a binary file db.dump
docker exec <container_name> sh -c 'mongodump --archive' > db.dump

When successful, you should see db.dump file in the current directory.

To restore the backup, run the following command:

docker exec -i <container_name> sh -c 'mongorestore --archive' < db.dump

{% hint style="info" %} You can export your database dump directly to MongoDB Atlas by simply running

mongorestore --uri mongodb+srv://<user>:<password>@cluster0.w2btl.mongodb.net --archive=db.dump {% endhint %}

Congratulations on successfully deploying Rocket.Chat using Docker! You can now communicate effortlessly with your team members on your workspace. Visit the accessing your workspace guide to configure your workspace and onboard other team members.