Install Rocket.Chat with Docker as a Slack alternative

Once you’ve SSH-ed into your VPS, and you have Docker up and running smoothly, you can get started on setting up docker-compose to automate the process of deploying your Rocket.Chat app.

First, create a nice space for our docker-compose.yml file. You can place this wherever you’d like, but I think your user’s home directory is a good choice.

$ cd ~
$ mkdir rocket.chat && cd rocket.chat

Now that you’re in the rocket.chat folder, you can create a docker-compose.yml file to tell Docker how you want the system configured. Create the file with your text editor of choice and paste in the following example file from Rocket.Chat.

version: '2'

services:
  rocketchat:
    image: rocketchat/rocket.chat:latest
    restart: unless-stopped
    volumes:
      - ./uploads:/app/uploads
    environment:
      - PORT=3000
      - ROOT_URL=http://rocketchat.jollof.io
      - MONGO_URL=mongodb://mongo:27017/rocketchat
      - MONGO_OPLOG_URL=mongodb://mongo:27017/local
      - MAIL_URL=smtp://smtp.email
#       - HTTP_PROXY=http://proxy.domain.com
#       - HTTPS_PROXY=http://proxy.domain.com
    depends_on:
      - mongo
    ports:
      - 3000:3000
    labels:
      - "traefik.backend=rocketchat"
      - "traefik.frontend.rule=Host: rocketchat.jollof.io"

  mongo:
    image: mongo:4.0
    restart: unless-stopped
    volumes:
     - ./data/db:/data/db
     #- ./data/dump:/dump
    command: mongod --smallfiles --oplogSize 128 --replSet rs0
    labels:
      - "traefik.enable=false"

  # this container's job is just run the command to initialize the replica set.
  # it will run the command and remove himself (it will not stay running)
  mongo-init-replica:
    image: mongo:4.0
    command: 'mongo mongo/rocketchat --eval "rs.initiate({ _id: ''rs0'', members: [ { _id: 0, host: ''localhost:27017'' } ]})"'
    depends_on:
      - mongo

  # hubot, the popular chatbot (add the bot user first and change the password before starting this image)
  hubot:
    image: rocketchat/hubot-rocketchat:latest
    restart: unless-stopped
    environment:
      - ROCKETCHAT_URL=178.62.118.172:3000
      - ROCKETCHAT_ROOM=GENERAL
      - ROCKETCHAT_USER=bot
      - ROCKETCHAT_PASSWORD=botpassword
      - BOT_NAME=bot
# you can add more scripts as you'd like here, they need to be installable by npm
      - EXTERNAL_SCRIPTS=hubot-help,hubot-seen,hubot-links,hubot-diagnostics
    depends_on:
      - rocketchat
    labels:
      - "traefik.enable=false"
    volumes:
      - ./scripts:/home/hubot/scripts
  # this is used to expose the hubot port for notifications on the host on port 3001, e.g. for hubot-jenkins-notifier
    ports:
      - 3001:8080

 #traefik:
  #  image: traefik:latest
  #  restart: unless-stopped
  #  command: traefik --docker --acme=true --acme.domains='your.domain.tld' --acme.email='[email protected]' --acme.entrypoint=https --acme.storagefile=acme.json --defaultentrypoints=http --defaultentrypoints=https --entryPoints='Name:http Address::80 Redirect.EntryPoint:https' --entryPoints='Name:https Address::443 TLS.Certificates:'
  #  ports:
  #    - 80:80
  #    - 443:443
  #  volumes:
  #    - /var/run/docker.sock:/var/run/docker.sock

Be sure that the text, when copied, looks exactly like this. yml files are finicky when it comes to syntax, which might lead to parsing errors.

Step 2. Configuring the docker-compose file

You can’t just go ahead with this default file—you need to change a few of the variables to fit your unique Rocket.Chat installation. You only need to change one of them, however, to enable the most basic setup. That’s what we’ll focus on for now.

Find line 11 of the docker-compose.yml file, which begins with ROOT_URL.

You will need to change the ROOT_URL based on your particular needs. If you’d like to host Rocket.Chat on yourdomain.com, or even chat.yourdomain.com, replace localhost:3000 with that—just be sure to have your DNS set up properly. If you want to use your VPS’ public IP to connect to Rocket.Chat, replace localhost:3000 with that IP.

So, to be clear, here are some examples:

If you’re using a domain name to access Rocket.Chat:

- ROOT_URL=http://yourdomain.com

If you’re using an IP address:

- ROOT_URL=http://123.456.78.9

If you’re using an IP address plus a port:

- ROOT_URL=http://123.456.78.9:3000

If you fail to specify the protocol (http) or the port (:3000, but only if you’re using one), the installation won’t work.

That’s it for configuration!

Step 3. Starting MongoDB

Rocket.Chat uses the MongoDB database to store information about users, their interactions, and more. You’ll have to start up mongo before you can launch Rocket.Chat itself. Docker-compose will help us here as well.

$ docker-compose up -d mongo

You’ll see output detailing the new rocketchat_default network that’s being created to help mongo and Rocket.Chat communicate, followed by Docker downloading the necessary images and launching a new container called rocketchat_mongo_1.

Now, double-check that mongo has started properly by listing the running Docker containers. You should see output like the following:

$ docker ps
CONTAINER ID        IMAGE                      COMMAND                  CREATED             STATUS              PORTS                    NAMES
174d2856344f        mongo:4.0                  "docker-entrypoint..."   46 seconds ago      Up 45 seconds       27017/tcp                rocketchat_mongo_1

If the status says Up and there are no other errors, you’re ready to initialize the database.

$ docker-compose up -d mongo-init-replica

If that command exits with done, your database is ready.

Step 4. Starting Rocket.Chat

Now that our database is in place, we can finally launch Rocket.Chat.

$ docker-compose up -d rocketchat

Once again, check docker ps to make sure Rocket.Chat is running. You should see something similar to the following:

CONTAINER ID        IMAGE                           COMMAND                  CREATED             STATUS                  PORTS                    NAMES
f72878c2d108        rocketchat/rocket.chat:latest   "node main.js"           49 seconds ago      Up Less than a second   0.0.0.0:3000->3000/tcp   rocketchat_rocketchat_1
174d2856344f        mongo:4.0                       "docker-entrypoint..."   7 minutes ago       Up 7 minutes            27017/tcp                rocketchat_mongo_1

Step 5. Getting started with Rocket.Chat

Now that Rocket.Chat shows that it’s running via these docker commands, it’s time to connect to your instance. Open up your web browser of choice and direct it toward the ROOT_URL you specified earlier.

With any luck, you’ll see the following screen:

Click on the Register a new account link to create your administrator account. Once you’ve done that, you’ll be able to log into your Rocket.Chat instance, which will launch you into the primary Rocket.Chat interface:

Congratulations! You now have a fully-functional Rocket.Chat installation.

Troubleshooting

There are not many places for this Rocket.Chat install to go wrong, considering we’re only changing one variable within the docker-compose.yml file.

If something isn’t working right, be sure to run docker logs rocketchat_rocketchat_1 to see output from the container. That should give you some insight into what might be going wrong. Most likely, you’ve set up your ROOT_URL incorrectly.

If you do have an issue like this, correct your docker-compose.yml file and re-run docker-compose up -d rocketchat—Docker will recreate the containers using this new configuration while retaining your data.

Welcome to a Slack-free future!

I hope this tutorial has been useful—both helping you install a Rocket.Chat instance, but also in reducing your reliance on others.

If this tutorial has given you the self-hosting bug, be sure to check out our massive guide of self-hosted alternatives for dozens more opportunities.

That’s the beauty of the cloud—you can create your own infrastructure, in exactly the way you want, and have complete control of your data.