# How to install Rocket.Chat with Docker Compose and HTTPS > Deploy Rocket.Chat with the official rocketchat-compose files, a MongoDB replica set and automatic HTTPS from Traefik, then secure, back up and update it. Difficulty: Intermediate\ Tested on: Ubuntu 24.04 LTS, Debian 12, Debian 13 Rocket.Chat is an open source team chat platform with channels, direct messages, threads, file sharing, video conferencing integrations and an omnichannel module for customer conversations. This guide deploys it with Rocket.Chat's official **rocketchat-compose** project on Ubuntu or Debian: the Rocket.Chat container, MongoDB as a replica set, the NATS message broker and Traefik, which obtains a Let's Encrypt certificate on its own. You then create the first administrator, close the registration form, and learn how to back up, restore and update the workspace. > **Note** > > Rocket.Chat's guide installs Docker with the `get.docker.com` convenience script. Docker's own documentation recommends that script for testing only, so this guide uses the repository install from [Install Docker on Ubuntu](/guides/install-docker-ubuntu) or [Install Docker on Debian](/guides/install-docker-debian) instead. The result is the same Docker Engine and Compose plugin. ## Prerequisites - A server running **Ubuntu 24.04 LTS**, **Debian 12** or **Debian 13** with Docker Engine, the Compose plugin and `git` installed. Rocket.Chat's deployment guide warns that MongoDB 8.x may fail to start on Ubuntu 26.04 and recommends Ubuntu 24.04 LTS, so this guide does not cover 26.04. - A non-root user with `sudo` rights who can run `docker` commands: see [Secure a new Linux server](/guides/secure-a-new-linux-server). - A domain name such as `chat.example.com` with an A record (and AAAA record if you use IPv6) pointing to the server. Traefik can only obtain a certificate once this record resolves. - Ports 80 and 443 free. Traefik uses them, so do not run Caddy or Nginx on the same server. - Outbound HTTPS access to Rocket.Chat's cloud services, which registration, push notifications and the Marketplace use. Rocket.Chat's requirements page lists its smallest production deployment (up to 500 concurrent users) per component: | Resource | Minimum (official) | Suggested starting point | |---|---|---| | CPU | 2 vCPU for Rocket.Chat plus 2 vCPU for MongoDB | 4 vCPU when both run on one server | | RAM | 4 GiB for Rocket.Chat plus 4 GiB for MongoDB | 8 GB on one server | | Disk | 20 GiB for Rocket.Chat plus 10 GiB for MongoDB | 40 GB plus room for uploaded files | The official table assumes a three-member MongoDB replica set for high availability. This guide runs one member, which suits a single server but has no automatic failover. ## Step 1 — Clone the official Compose project Create the application folder and clone the repository into it: ```bash sudo mkdir -p /opt/rocketchat sudo chown $USER:$USER /opt/rocketchat git clone --depth 1 https://github.com/RocketChat/rocketchat-compose.git /opt/rocketchat cd /opt/rocketchat cp .env.example .env chmod 600 .env ls ``` The project splits the stack into several Compose files: - `compose.yml` — the Rocket.Chat application, - `compose.database.yml` — MongoDB, a helper that fixes data folder permissions, and a one-off container that initiates the replica set, - `compose.nats.yml` — the NATS message broker, - `compose.traefik.yml` — Traefik with Let's Encrypt, - `compose.monitoring.yml` and `docker.yml` — the optional Prometheus, Loki and Grafana monitoring stack. Rocket.Chat advises against editing these files. Everything you change goes into `.env`. ## Step 2 — Configure the .env file Open the file with `nano .env`. Change the existing values and add the lines that are missing: ```env RELEASE=8.8.1 DOMAIN=chat.example.com ROOT_URL=https://chat.example.com LETSENCRYPT_ENABLED=true LETSENCRYPT_EMAIL=admin@example.com TRAEFIK_PROTOCOL=https BIND_IP=127.0.0.1 TRAEFIK_DASHBOARD_PORT=127.0.0.1:8080 MONGODB_VERSION=8.0 COMPOSE_FILE=compose.traefik.yml:compose.database.yml:compose.yml:compose.nats.yml ``` What these settings do: - `RELEASE` pins the Rocket.Chat version. Rocket.Chat strongly recommends a fixed version number in production instead of `latest`. Take the newest release from the [supported versions page](https://docs.rocket.chat/docs/supported-versions-eol-schedule); `8.8.1` was current when this guide was written. - `DOMAIN` and `ROOT_URL` must match the public address. Traefik requests the certificate for `DOMAIN`, and Rocket.Chat builds links from `ROOT_URL`. - `LETSENCRYPT_ENABLED`, `LETSENCRYPT_EMAIL` and `TRAEFIK_PROTOCOL=https` switch Traefik to HTTPS with a Let's Encrypt certificate. - `BIND_IP=127.0.0.1` matters for security. `compose.yml` publishes port 3000 and the metrics port on all addresses by default, and Docker-published ports bypass ufw. Traefik reaches Rocket.Chat over the Compose network, so the host port only needs to listen on localhost. - `TRAEFIK_DASHBOARD_PORT=127.0.0.1:8080` keeps the Traefik dashboard port on localhost. The dashboard is switched off by default, but the port mapping would otherwise still open 8080 on every address. - `MONGODB_VERSION=8.0` matches the minimum MongoDB version for Rocket.Chat 8.x. Each release states its compatible MongoDB versions: `curl -s https://releases.rocket.chat/8.8.1/info` shows them in `compatibleMongoVersions`. - `COMPOSE_FILE` tells `docker compose` which files make up the stack, so every later command uses the same set without `-f` options. The repository README says you can leave out components by leaving out their files; this list skips the monitoring stack. Check that Compose reads the configuration: ```bash docker compose config --services ``` The list should include `traefik`, `mongodb`, `rocketchat` and `nats`. An error here usually points to a typo in `.env`. > **Tip** > > To add the monitoring stack later, append `:compose.monitoring.yml:docker.yml` to `COMPOSE_FILE`, set a strong `GRAFANA_ADMIN_PASSWORD` in `.env` before the first start (the value only applies at first setup) and run `docker compose up -d`. Grafana is then served under `/grafana` on your domain. ## Step 3 — Open the firewall Allow SSH and web traffic only: ```bash sudo ufw allow OpenSSH sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw enable sudo ufw status verbose ``` Traefik uses the TLS challenge on port 443 to prove that you control the domain, so port 443 must be reachable and DNS must point to this server before the first start. MongoDB and NATS are published on `127.0.0.1` only by the official files, and Step 2 moved Rocket.Chat's own ports there as well. ## Step 4 — Start Rocket.Chat Pull the images and start the stack: ```bash cd /opt/rocketchat docker compose pull docker compose up -d docker compose ps -a docker compose logs -f rocketchat ``` Containers such as `rocketchat`, `mongodb`, `nats` and `traefik` should be `Up`. The permission helper and the replica set init container finish their job and show `Exited (0)`, which is expected. Rocket.Chat is ready when its log prints a `SERVER RUNNING` box; press `Ctrl+C` to stop following the log. Check HTTPS and the closed app port: ```bash curl -I https://chat.example.com ``` The response should be `HTTP/2 200` with a valid certificate. From another machine, `nc -vz your-server-ip 3000` should be refused or time out. ## Step 5 — Run the setup wizard and close the registration form Open `https://chat.example.com`. The setup wizard asks for the first administrator (name, username, email and password), then for your organisation details, and then registers the workspace with Rocket.Chat Cloud using your email address. Confirm the email Rocket.Chat sends you to finish the registration. Rocket.Chat's workspace FAQ notes that the registration form is usually set to **Public**, which lets anyone who finds the address create an account. Close it before you share the link: 1. Go to **Manage > Workspace > Settings > Accounts**. 2. Scroll to **Registration** and set **Registration Form** to **Disabled**. 3. Save, then invite users from **Manage > Workspace > Users**. Existing users can still log in as usual. While you are in the settings, turn on two-factor authentication for every administrator account and review **File Upload**: files are stored in MongoDB GridFS by default, and Rocket.Chat recommends object storage such as S3 or MinIO for production (see [Self-hosted S3 storage](/guides/self-hosted-s3-storage)). Rocket.Chat emails invitations, password resets, address verification and notifications about missed messages through the relay you set under **Manage > Workspace > Settings > Email**, in the **SMTP** section (protocol `smtp`, host `smtp.example.com`, port `587`, your SMTP user and password, and a **From Email** address). > **Note** > > Outbound port 25 is closed by default on HyperDC VPS. For services bought for a term of 3 months or longer, it is opened on request: [open a support ticket](/guides/support-tickets). Until then, send mail through an SMTP relay on port 587. ## Back up and restore With the default GridFS storage, MongoDB holds everything: users, messages, settings and uploaded files. The `.env` file holds your deployment settings. Rocket.Chat's guide backs up the database with `mongodump` streamed to the host: ```bash sudo mkdir -p /opt/backups sudo chown $USER:$USER /opt/backups chmod 700 /opt/backups cd /opt/rocketchat docker compose exec -T mongodb sh -c 'mongodump --archive' > /opt/backups/rocketchat-db-$(date +%F).archive cp .env /opt/backups/rocketchat-env-$(date +%F) ls -lh /opt/backups ``` `-T` turns off the pseudo-terminal so the binary archive reaches the file unchanged. If you switched file uploads to the FileSystem storage type, archive that folder too; with S3 or MinIO, back up the bucket with your storage provider's tools. To restore, start from a running stack with the same `RELEASE` and `MONGODB_VERSION` (on a new server, repeat Steps 1 to 4 with your saved `.env`). Stop Rocket.Chat, load the archive and start it again: ```bash cd /opt/rocketchat docker compose stop rocketchat docker compose exec -T mongodb sh -c 'mongorestore --archive --drop' < /opt/backups/rocketchat-db-2026-10-09.archive docker compose start rocketchat ``` > **Warning** > > `--drop` deletes each collection in the target database before restoring it from the archive, so the restored data replaces what is there now. Do not run this against a workspace you want to keep. Copy backups off the server as well. ## Update Rocket.Chat Rocket.Chat's update guidelines come down to four rules: read the release notes, back up first, update MongoDB before Rocket.Chat when the new release needs it, and move through major versions one at a time (7.x to 8.x, never 6.x straight to 8.x). Minor and patch updates within a major version can be applied directly. ```bash cd /opt/rocketchat curl -s https://releases.rocket.chat/8.8.1/info nano .env docker compose pull docker compose up -d docker compose ps ``` Replace `8.8.1` in the `curl` command with the target version and check `compatibleMongoVersions`. In `.env`, set `RELEASE` to the new version. If the release needs a newer MongoDB, first change `MONGODB_VERSION`, run `docker compose up -d mongodb` and wait for the container to become healthy. Because `COMPOSE_FILE` lists all your files, `docker compose up -d` recreates the stack with the same services; Rocket.Chat's guide warns that leaving out a file drops those services. Afterwards, confirm the version under **Manage > Workspace**. MongoDB cannot be downgraded directly; going back requires lowering the feature compatibility version first, so keep the backup you took before the update. ## Troubleshooting ### Traefik does not get a certificate Run `docker compose logs traefik`. The usual causes are a DNS record that does not point to this server yet, port 443 blocked by a firewall in front of the server, or Let's Encrypt rate limits after repeated attempts. Fix the cause, then run `docker compose restart traefik`. ### The mongodb container keeps restarting Read `docker compose logs mongodb`. MongoDB waits up to about five minutes for the permission helper to fix the ownership of its data folder and exits if that fails. On Ubuntu 26.04, MongoDB 8.x may not start at all; use Ubuntu 24.04 LTS or Debian instead. ### Rocket.Chat exits with a MongoDB version error after an update The new release needs a newer MongoDB. Check `compatibleMongoVersions` for the release, raise `MONGODB_VERSION` in `.env`, update MongoDB first with `docker compose up -d mongodb`, then start Rocket.Chat again. ### Port 3000 is reachable from the internet `BIND_IP` is missing from `.env`, so Docker publishes the port on all addresses and ufw does not block it. Add `BIND_IP=127.0.0.1` and run `docker compose up -d` to recreate the container. ### Push notifications do not reach phones Push notifications go through Rocket.Chat's cloud gateway, which requires a registered workspace on a supported version. Check the registration status under **Manage > Workspace**, register or sync the workspace again, and update if your version is past its end-of-life date. ## Next steps - Compare Rocket.Chat with [Mattermost](/guides/install-mattermost) and [Matrix Synapse with Element](/guides/install-matrix-synapse). - Add video meetings with [Jitsi Meet](/guides/install-jitsi-meet). - Learn the Compose commands used here in [Docker Compose basics](/guides/docker-compose-basics). - Read the official [Rocket.Chat Docker deployment guide](https://docs.rocket.chat/docs/deploy-with-docker-docker-compose) for monitoring, external MongoDB and scaling. - Compare servers for team chat on the [team chat hosting](/team-chat-hosting) page. ## Frequently asked questions ### Where does Rocket.Chat store uploaded files? In MongoDB GridFS by default, so the database backup in this guide also contains the files. Under Manage > Workspace > Settings > File Upload you can switch to the FileSystem storage type or to S3-compatible object storage such as MinIO, which Rocket.Chat recommends for production; then back up that storage as well. ### Do I have to register my workspace with Rocket.Chat Cloud? Rocket.Chat's documentation calls registration a required step in the setup wizard. Registration links the workspace to cloud services such as the push notification gateway and the Marketplace. Air-gapped workspaces follow a separate process and have no cloud services. ### Why does Rocket.Chat need a MongoDB replica set? Rocket.Chat uses the replica set's oplog for real-time updates. The official compose.database.yml starts MongoDB as a single-node replica set named rs0 and initiates it automatically, so you do not have to configure it by hand. ### How long is each Rocket.Chat version supported? Standard releases are supported for six months and LTS releases for twelve. After end of life a version gets no security fixes, cloud services such as push notifications stop, and the official mobile and desktop apps may be unable to connect. ### Can I use Caddy or Nginx instead of Traefik? Yes. Rocket.Chat documents an Nginx setup: leave out compose.traefik.yml, set LETSENCRYPT_ENABLED=false and proxy your domain to port 3000 with WebSocket support. This guide uses the bundled Traefik because it is the default path in the official files. --- Source: \ Updated: 2026-10-09