Docker Containers

Introduction
This guide will walk you through the installation and configuration of a Docker-based Rocket.Chat instance on Ubuntu 16.04 LTS (64 bit) VPS, using Nginx as a reverse SSL proxy, Hubot chatbot, and necessary scripts for an automatic restart and crash recovery.
For people new to docker here's a quick primer: Docker is a program that allows other programs and their dependencies to be run in a type of virtual container. Using this deployment guide, you do not need to download any of the rocket chat program files manually whatsoever.
Docker will get everything needed for Rocket.Chat to run. If you follow this guide closely, it provides everything from start to finish needed to install, create, and run your own Rocket.Chat web instance with Nginx handling SSL termination, and a Hubot chatbot keeping your general chat channel warm on those cold winter mornings.
This guide is designed for everyone, however, it is intentionally detailed to help the new users who may need a little extra guidance. If you're experienced with things like docker, Nginx, etc. you may prefer one of the other deployment guides found elsewhere on this wiki.
What we'll cover in this guide
1.​Securing the server: Firewall basics (optional)​
2.​Securing the server: Fail2Ban IDS (optional)​
3.​Installing Docker and Docker-Compose​
4.​Editing the hosts file​
5.​Installing Nginx SSL Reverse Proxy​
6.​Creating docker-compose.yml​
7.​Automatic start-up, and crash recovery​
8.​Reboot & Status check​
9.​Registering & Configuring Hubot, the chat robot​
10.​FAQ & Troubleshooting​
11.​TODO​
12.​Known Issues​
Prerequisites
This guide is written assuming that you're starting with:
A clean new installation of Ubuntu 16.04 LTS (64 bit)
properly configured DNS that resolves requests to your domain name
1. Securing the server: Firewall basics (optional, recommended)
First, make sure UFW (Uncomplicated FireWall) is installed. It should be installed by default in Ubuntu, but if it’s not, you can check if it is installed by running.
1
apt -qq list ufc
Copied!
It will return simple information about the package if it is found. Otherwise, install the package by running
1
sudo apt-get install ufw
Copied!
IMPORTANT: We're going to add a firewall rule to permit your default SSH connection port on port 22/tcp.
In case you have the port changed on your device, be sure to use the corresponding port.
Failure to do so will break your SSH connection and log you out of the server as soon as you enable the firewall!
Set the default access rules:
1
sudo ufw default deny incoming
2
​
3
sudo ufw default allow outgoing
Copied!
Set the service rules (SSH / HTTPS):
1
sudo ufw allow 22/tcp
2
​
3
sudo ufw allow 443/tcp
Copied!
Enable the firewall:
1
sudo ufw enable
Copied!
Check the Firewall status:
1
sudo ufw status
Copied!
If you ever add or delete rules you should reload the firewall:
1
sudo ufw reload
Copied!
If you ever need to turn off the firewall:
1
sudo ufw disable
Copied!
2. Securing the server: Fail2ban (optional, recommended)
Fail2ban is an intrusion prevention software framework that protects computer servers from brute-force attacks.
Install:
1
sudo apt-get update
2
​
3
sudo apt-get install fail2ban
Copied!
Press Y when prompted to proceed with the install.
3. Installing Docker and Docker-Compose
Install Docker
Follow this guide https://docs.docker.com/linux/step_one/ to get Docker installed.
Install Docker-Compose version 1.24.0 (64 bit) via cURL
1
sudo curl -L "https://github.com/docker/compose/releases/download/1.24.0/docker-compose-Linux-x86_64" -o /usr/local/bin/docker-compose
Copied!
Set the executable permissions
1
sudo chmod +x /usr/local/bin/docker-compose
Copied!
Notes: We're using version 1.24.0 for this guide. If you wish to try a newer version, you will need to edit the cURL command to reflect the alternate version number. If you get a "Permission denied" error, your /usr/local/bin directory probably isn't writable and you'll need to install Compose as the superuser. Run sudo -i, then the two commands above, then exit. (credit: docker compose docs)
Confirm docker-compose is properly installed
1
sudo docker-compose --version
Copied!
Notes: For minimal distributions, or systems where /usr/local/bin is not part of the $PATH env you might need to symlink the binary into /usr/bin as well:
1
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
Copied!
4. Editing the hosts file
If your hostname.domain.tld is mapped to a publicly routable IP, it needs to be set to your local address, for example, 127.0.0.1. Please note that the order in which localhost and your hostname are placed in this file is important; make sure localhost is first.
Edit the hosts file
1
sudo nano /etc/hosts
Copied!
1
127.0.0.1    localhost.localdomain    localhost
2
127.0.0.1    chat.inumio.com          chat
Copied!
Save and Exit. (Press CTRL-X to save, Y for yes, then ENTER to save as current filename.)
5. Installing Nginx & SSL certificate
Install Nginx
1
sudo apt-get install nginx
Copied!
5a. Using a commercial SSL cert (recommended)
If you don't have a certificate already, you can grab one for free at Let's Encrypt.
Or, if you want to use a self-signed SSL cert instead, skip ahead to Self-Signed SSL.
Install the private key (created when you generated the CSR)
1
sudo nano /etc/nginx/certificate.key
Copied!
Open the private key and Copy the entire private key text-block from the file that was generated when you created the CSR. Right click on the terminal window and select paste to paste it into nano. Alternatively, if you have a tool such as filezilla, you can use it via SSH over FTP to upload your cert and key files instead of copy / paste.
Save and Exit.
Install the SSL certificate (note that this goes in certificate.crt, not .key)
1
sudo nano /etc/nginx/certificate.crt
Copied!
Open the SSL Certificate provided by the SSL vendor (will probably have a .crt or .pem extension) and copy the entire text-block. Right click on the terminal window and select paste to paste it into nano.
Save and Exit.
5b. Self-Signed SSL
If you acquired an SSL cert and installed it via the steps above, skip this step.
Create and install a self-signed SSL certificate:
1
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/certificate.key -out /etc/nginx/certificate.crt
Copied!
Follow the prompts.
Tip: It is IMPORTANT that the Common Name be set properly. Enter your fully qualified domain name (FQDN) here or, if you don’t have a FQDN, use your public IP address. For example, my FQDN for the chat server is chat.inumio.com.
Save and Exit.
5c. Set Key Permissions, Dhparams, Configure NGINX
Set permissions:
1
sudo chmod 400 /etc/nginx/certificate.key
Copied!
Generate Strong Diffie Helman group
1
sudo openssl dhparam -out /etc/nginx/dhparams.pem 2048
Copied!
Configure Nginx:
1
sudo nano /etc/nginx/sites-available/default
Copied!
Delete the example in this file, and paste in the following:
1
# HTTPS Server
2
    server {
3
        listen 443 ssl;
4
        server_name chat.inumio.com;
5
​
6
        error_log /var/log/nginx/rocketchat_error.log;
7
​
8
        ssl_certificate /etc/nginx/certificate.crt;
9
        ssl_certificate_key /etc/nginx/certificate.key;
10
        ssl_dhparam /etc/nginx/dhparams.pem;
11
        ssl_protocols TLSv1.2;
12
        ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA';
13
        ssl_prefer_server_ciphers on;
14
        ssl_session_cache shared:SSL:20m;
15
        ssl_session_timeout 180m;
16
​
17
        location / {
18
            proxy_pass http://chat.inumio.com:3000/;
19
            proxy_http_version 1.1;
20
            proxy_set_header Upgrade $http_upgrade;
21
            proxy_set_header Connection "upgrade";
22
            proxy_set_header Host $http_host;
23
            proxy_set_header X-Real-IP $remote_addr;
24
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
25
            proxy_set_header X-Forwarded-Proto https;
26
            proxy_set_header X-Nginx-Proxy true;
27
            proxy_redirect off;
28
        }
29
    }
Copied!
Edit the config Change the server name and proxy_pass to reflect your own details.
Save and Exit.
Test the config & Restart nginx:
1
sudo service nginx configtest && sudo service nginx restart
Copied!
TIP: You can pinpoint problems in your nginx config using the following command
1
sudo nginx -t
Copied!
6. Create the docker-compose.yml file & local directories
Create docker-compose.yml file:
To create a docker-compose file, please follow the instructions here.
Create the directories:
1
sudo mkdir -p /var/www/rocket.chat/data/runtime/db
2
sudo mkdir -p /var/www/rocket.chat/data/dump
Copied!
Create the docker-compose.yml file:
Edit the ROOT_URL value to be your FQDN.
Edit the ROCKETCHAT_URL to be your public IP address. Keep the port (3000) the same.
Edit ROCKETCHAT_USER, ROCKETCHAT_PASSWORD, and BOT_NAME.
If your Rocket.Chat docker instance is behind a proxy, set the additional env-variable "Accounts_UseDNSDomainCheck" to "false" (this only works, if these is a completely new deployment)
Save and Exit.
Start the services by:
1
docker-compose up -d
Copied!
7. Automatic Startup & Crash Recovery
Create the upstart job for MongoDB
1
sudo nano /etc/init/rocketchat_mongo.conf
Copied!
1
description "MongoDB service manager for rocketchat"
2
​
3
# Start MongoDB after docker is running
4
start on (started docker)
5
stop on runlevel [!2345]
6
​
7
# Automatically Respawn with finite limits
8
respawn
9
respawn limit 99 5
10
​
11
# Path to our app
12
chdir /var/www/rocket.chat
13
​
14
script
15
    # Showtime
16
    exec /usr/local/bin/docker-compose up mongo
17
end script
Copied!
Save and Exit.
Create the upstart job for Rocket.Chat
1
sudo nano /etc/init/rocketchat_app.conf
Copied!
1
description "Rocketchat service manager"
2
​
3
# Start Rocketchat only after mongo job is running
4
start on (started rocketchat_mongo)
5
stop on runlevel [!2345]
6
​
7
# Automatically Respawn with finite limits
8
respawn
9
respawn limit 99 5
10
​
11
# Path to our app
12
chdir /var/www/rocket.chat
13
​
14
script
15
    # Bring up rocketchat app and hubot
16
    exec /usr/local/bin/docker-compose up rocketchat hubot
17
end script
Copied!
Save and Exit.
8. Reboot and Status check
We're ready to start the show! With luck, you should be able to reboot, and the chat system will come online by itself. The first time the system runs, it will have to download a bunch of docker image files. You won't see this occurring when you log back in. It's important to allow the downloads to complete without interruption.
After the downloads are extracted, the total combined installation is around 800 MB, so this initial downloading may take it awhile. On a commercial server with a fast connection, this will typically take a few minutes.
Restart the server:
1
sudo reboot
Copied!
Reconnect via SSH, and do a systems check by viewing the docker containers:
1
sudo docker ps -a
Copied!
As you can see, our three docker containers are up and running: Rocket.Chat, MongoDB, and Hubot. NOTE: You may see only one, or none at all if the downloads are still in progress. Be patient, and check it periodically. Eventually, it should look similar to our sample screenshot. If it does, congratulations, you did it! GREAT JOB!
Next, let's try opening the web browser and going to your new chat room. Provided that your DNS is properly configured, you should be able to simply type your chatroom URL into the browser and open it up.
First try with HTTPS:
1
https://chat.inumio.com
Copied!
If for some reason that fails, try HTTP: Open port 3000/tcp in the firewall, and reload to set the new policy.
1
sudo ufw allow 3000/tcp
2
​
3
sudo ufw reload
Copied!
Try accessing in your web browser via HTTP
1
http://chat.inumio.com:3000
Copied!
PROBLEM? See Section 10: Troubleshooting​
Once you've successfully reached your chat room login page, you need to register your admin account. By default, the first account to register on Rocket.Chat becomes the admin, so if your chat room is public, do this immediately in order to prevent someone else from registering and becoming the administrator.
Great! I'm in, but the bot is nowhere to be seen!
No worries! In order to get your bot up and running, we must register it…
9. Registering & Configuring Hubot, the chat robot
Previously, we created the docker-compose.yml file. It's this file where we defined the basic attributes for Hubot. We set the bot name, password, room to join, and scripts to run. Before the bot can join the chat room, we must manually create the bot using the configuration details we provided in docker-compose.yml.
​https://github.com/RocketChat/hubot-rocketchat#creating-a-user-on-the-server​
You can now optionally login and set some of the preferences, such as bot avatar. When finished, log out of the bot account.
With the bot account created, you can force it to join by simply rebooting the server, upon which the init script should automatically launch your chat room, and the bot should join the “General” room.
For basic command help, in the chat message box, type BOTNAME help (where BOTNAME is your bot's name).
10. Troubleshooting & FAQ
FAQ
Q: It works! But how do I add more functionality to the bot? A: You can add more scripts to the bot by adding them to the EXTERNAL_SCRIPTS definitions: nano /var/www/rocket.chat/docker-compose.yml
Find out more about Hubot scripts here: https://github.com/RocketChat/hubot-rocketchat and here: https://github.com/hubot-scripts. Some of the available scripts for example: hubot-help, hubot-isup, hubot-4chan, hubot-strawpoll, hubot-seen, hubot-weather, hubot-hackerman, hubot-links, hubot-greetings, hubot-tell, hubot-geo, hubot-decides, hubot-praise, hubot-hello-ninja, hubot-thank-you, hubot-cool-ascii-faces, hubot-insulter, hubot-reddit
Q: How do I get email working? A: You need to configure SMTP parameters via the Administration UI (from inside rocketchat).
TROUBLESHOOTING
PROBLEM: I can't bring up my chat page in the browser using HTTPS!
POSSIBLE SOLUTIONS: If you're able to resolve HTTP, but not HTTPS, you need to re-visit sections 4 & 5 of this guide. Make sure you've correctly entered the data in the hosts file, as well as in the /etc/nginx/sites-available/default file.
Check the nginx logs for any errors or other clues
1
sudo cat /var/log/nginx/error.log
Copied!
Check the Firewall policy to make sure port 443 is open
1
sudo ufw status
Copied!
Check your SSL installation https://www.digicert.com/help/​
PROBLEM: I rebooted and waited forever for docker to download everything and start the chat room. NOTHING happened. It's like it didn't even try!
POSSIBLE SOLUTION: If there are errors in the docker-compose.yml file, it will fail to bring up the rocketchat app. Improperly formatted yml will cause problems.
Check upstart jobs for log errors
1
cd /var/log/upstart
2
​
3
sudo cat rocketchat_mongo.log
4
​
5
sudo cat rocketchat_app.log
Copied!
Look for any errors in the output of those last two commands, which show the log contents of the upstart jobs we created in step 7.
Test your YML http://www.yamllint.com/ simply copy the contents of docker-compose.yml and paste into the tool.
Try to start it manually
1
cd /var/www/rocket.chat
2
​
3
/usr/local/bin/docker-compose up
Copied!
If docker-compose doesn't throw an error and instead launches the job, then the problem is possibly in the upstart script.
PROBLEM: When I upload a file the server crashes!
POSSIBLE SOLUTION: If you're running low on system resources, such as RAM, this can cause problems with not just performance, but stability. Make sure that you're not running out of memory, or have any other choke points, like not enough CPU, etc. One way to check is to issue the following command via SSH (or console) which runs TOP, a utility that will show valuable information about system resources and processes.
1
sudo top
Copied!
With TOP running, try to replicate the problem while watching TOP for high loads, overloaded CPU, etc. While Rocket.Chat can be run on a single core with 512MB of memory, that's really not enough for stable performance. If you're seeing high values in TOP, consider upgrading your server to at least 1GB or RAM, or more.
11. KNOWN ISSUES
[FIXED] Issue #978: Avatars not saving, or crashing the server. https://github.com/RocketChat/Rocket.Chat/issues/978​
If you are saving your avatars inside the container, they will be lost after a "docker pull" update job
See Also
You can also deploy using Docker and Docker Compose by following one of these guides:
​Docker Compose​
​Available Images​
Docker & Docker Compose
Available Images
Last modified 2d ago