mongodb

Install Rocket.Chat on Ubuntu 20.04 via Docker Compose

dave — Thu, 03 Mar 2022 00:00:52 +0000

Install Rocket.Chat on Ubuntu 20.04 via Docker Compose

Blog tags

ubuntu linux

20.04

rocket.chat

mongodb

docker

docker-compose

dave Thu 03/03/2022 - 13:00

This post is a companion to our video tutorial on installing Rocket.Chat 4.x on an Ubuntu 20.04 server via Docker Compose.

We start with a Docker Compose-configured server. You can also see our video tutorials on how to create one: complete, or starting from a DigitalOcean 'snapshot'.

From that starting point, we can install Rocket.Chat - which, incidentally, is a full-featured messaging service, similar to more heavily marketed Slack, Discord, or Microsoft Teams, but free and open source, and self-hostable (other free and open source options include Mattermost and Element/Matrix among others, by Rocket.Chat is the OERF's preference). You can also purchase it as Software-as-a-Service. It's also great for all sorts of integrations. There many ways you can interact with Rocket.Chat. It can be accessed via any modern web browser, and there are dedicated desktop applications for Linux, Microsoft Windows, and Apple MacOS, as well as mobile applications for Apple iOS and Android devices.

To complete this tutorial, you will need a fully qualified [domain name] (or subdomain) pointing to your server, a [port] number for your service - 8080 or 7080 are good options so long as they're not already in use by other services on the same server, and a set of authenticating SMTP credentials so you can configure your Rocket.Chat to send email (by default, Rocket.Chat uses TOTP (Time-based One-Time Password) sent via email for extra security).

Nginx reverse proxy

The first step is to set up the Nginx reverse proxy configuration to allow. You should create a file in /etc/nginx/sites-available with your [domain name] like this:

sudo nano /etc/nginx/sites-available/[domain name]

and fill it with this (replacing [domain name] and [port] appropriately:

server {
    listen 80;
    listen [::]:80;
    server_name [domain name];
 
    ## Access and error logs.
    access_log /var/log/nginx/[domain name]_access.log;
    error_log /var/log/nginx/[domain name]_error.log;
 
    include includes/letsencrypt.conf;
 
    location / {
      return 301 https://[domain name]$request_uri;
    }
    root /var/www/html;
}
 
 
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    #ssl_certificate /etc/letsencrypt/live/[domain name]/fullchain.pem;
    #ssl_certificate_key /etc/letsencrypt/live/[domain name]/privkey.pem;
    # temporary cert and private key, to be superseded by those provided by Let's Encrypt above.
    ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
    ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
 
    keepalive_timeout 20s;
 
    root /var/www/html;
    index index.html index.htm;
    server_name [domain name];
 
    ## Access and error logs.
    access_log /var/log/nginx/[domain name]_access.log;
    error_log /var/log/nginx/[domain name]_error.log;
 
    client_max_body_size 100m;
 
    include includes/letsencrypt.conf;  
 
    location / {
        proxy_pass       http://127.0.0.1:[port]; # use 8080 or 7080 if in doubt.
        proxy_http_version 1.1;
        proxy_set_header Upgrade                $http_upgrade;
        proxy_set_header Connection             "upgrade";
        proxy_set_header Host                   $http_host;
        proxy_set_header X-Forwarded-Host       $host;
        proxy_set_header X-Real-IP              $remote_addr;
        proxy_set_header X-Forwarded-For        $proxy_add_x_forwarded_for;
        proxy_set_header X-Forward-Proto        http;
        proxy_set_header X-Nginx-Proxy          true;
        proxy_redirect   off;
    }
}

Save and close that file. We now need to create the 'dhparam.pem' if it doesn't exist create it like this:

sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

After doing that, you can test Nginx's configuration:

sudo nginx -t

If you don't get any errors or warnings, you can activate the new configuration:

sudo service nginx reload

You server should now successfully respond to your [domain name], but it'll redirect to HTTPS using the default (self-signed) certificates that are valid as far as Nginx is concerned, but your browser won't let you access the page due to those inappropriate certificates. You can test it by putting http://[domain name] into your browser and seeing if it redirects you to https://[domain name] and a 'bad certificate` (or similar) page.

To fix that, we can now generate a Let's Encrypt certificate which will be valid.

sudo letsencrypt certonly --webroot -w /var/www/letsencrypt -d [domain name]

Since this is your first time running the letsencrypt script, you'll be asked for a contact email (so the Let's Encrypt system can warn you if your certificates are going to be expiring soon!) - you will need to provide an admin email for this. You can also opt in to allowing them to get anonymous statistics from your site (I do).

Once you've done that, the Let's Encrypt system will verify that you (the person requesting the certificate) also controls the server that's requesting it (using the details specified in the /etc/nginx/includes/letsencrypt.conf file, along with data that the letsencrypt script writes into a special file in the /var/www/letsencrypt directory) and, all going well, you'll see a "Congratulations!" message telling you that you have new certificates for your [domain name].

Then you can re-edit your Nginx confguration file:

sudo nano /etc/nginx/sites-available/[domain name]

and comment out the default certificates and uncomment the [Domain]-specific certificates, like this (we'll assume you've already got your [domain name] substituted!):

    ssl_certificate /etc/letsencrypt/live/[domain name]/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/[domain name]/privkey.pem;
    # temporary cert and private key, to be superseded by those provided by Let's Encrypt above.
    #ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
    #ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;

Once you've got that going, you again check to make sure your Nginx config is valid:

sudo nginx -t

and apply your configuration changes:

sudo service nginx reload

If you now go to http://[domain name] in your browser, you should be redirected to https://[domain name] and you shouldn't get any certificate errors, although you might get a "502" error because the service that reverse proxy configuration is trying to send you to doesn't yet exist! That's what we're expecting.

Rocket.Chat containers via Docker Compose

Next, we have to create the Rocket.Chat container recipe for Docker Compose. Create a Docker directory if it doesn't yet exist and a [domain name]-specific directory:

sudo mkdir -p /home/docker/[domain name]

and go there

cd home/docker/[domain name]

and create a file:

nano docker-compose.yml

putting this into it, replacing [domain name], [port], and the authenticating SMTP details: [smtp username], [smtp password], [smtp servername], and [smtp port]. Note the comment in the file as well if you're not sure about smtp:// or the [smtp port] to use.

This configuration specifies MongoDB version 4.2, which is the recommended version to use for Rocket.Chat right now. And the current version of Rocket.Chat at the time of this writing is 4.5.0.

version: '2'
services:
  mongo:
    restart: unless-stopped
    image: mongo:4.2
    volumes:
      - /home/data/[domain name]/mongodb/data:/data/db
      - /home/data/[domain name]/backups/mongodb:/backups
    command: mongod --oplogSize 128 --replSet rs0
  # 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.2
    command: 'bash -c "for i in `seq 1 30`; do mongo mongo/rocketchat --eval \"rs.initiate({ _id: ''rs0'', members: [ { _id: 0, host: ''localhost:27017'' } ]})\" && s=$$? && break || s=$$?; echo \"Tried $$i times. Waiting 5 secs...\"; sleep 5; done; (exit $$s)"'
    depends_on:
      - mongo
  rocketchat:
    restart: unless-stopped
    image: rocketchat/rocket.chat:4.5.0
    command: bash -c 'for i in `seq 1 30`; do node main.js && s=$$? && break || s=$$?; echo "Tried $$i times. Waiting 5 secs..."; sleep 5; done; (exit $$s)'
    ports:
      - "127.0.0.1:[port]:3000"
    depends_on:
      - mongo
    environment:
      - MONGO_URL=mongodb://mongo/rocket
      - MONGO_OPLOG_URL=mongodb://mongo/local
      - ROOT_URL=https://[domain name]
      # the SMTP port is likely to be 587 or 465, and instead of smtp:// you might need to use smtps:// (note the 's' for secure).
      - MAIL_URL=smtp://[smtp username]:[smtp password]@[smtp servername]:[smtp port]/  
    volumes:
      - /home/data/[domain name]/uploads:/app/uploads

Save and close that file. You can then start the Docker containers by invoking Docker Compose

docker-compose up -d && docker-compose logs -f

This command will 'pull' any missing reference containers from hub.docker.com (the default central place where many Docker containers are stored by their developers) and launch them in "daemon mode" (the '-d' flag achieves that) on your server, so that they'll keep running until you stop them. After it's done with the launching, Docker Compose will display the logging data being put out by both the MongoDB and Rocket.Chat containers.

You can issue a CTRL-C to cancel out of the logs view - it won't affect the running Rocket.Chat instance.

You can also stop Rocket.Chat by issuing:

docker-compose stop

and verify it status (running or not) via

docker-compose ps

If you then go https://[domain name] in your browser, you should get the 'initial user' start up page as shown in the attached screenshot. After filling in your content and content related to your instance, you should receive an email from both your Rocket.Chat instance and from the Rocket.Chat developers showing your instance is registered.

You can then log in (by default, you will have to wait for an email with a TOTP code to log in) you will be able to change the multitude of settings, behaviours, and integrations that Rocket.Chat supports. See its user documentation for more information on configuring and managing your Rocket.Chat instance. Note, there are many other sources for information on Rocket.Chat configuration - search engines will help you.

Backing up your data

To back up your Rocket.Chat installation, you will need to store both the content of your MongoDB and any files or other content uploaded.

Backing up the uploaded content involves regular file backups of the uploaded files and the docker-compose.yml configuration. Preferably, these should be stored off the original server, i.e.

We have developed a script for backing up Docker-based MongoDB installations. You can install it as follows. First, we'll make a place to put the backup script:

sudo mkdir /home/data/scripts && sudo cd /home/data/scripts

and then clone (i.e. download) our git repository:

sudo git clone https://git.oeru.org/oeru/mongobackup.git

which will create a directory /home/data/scripts/mongobackup - go into it

sudo cd /home/data/scripts/mongobackup

and create a backup configuration (substituting your domain name!) and edit the file:

sudo cp default-mongo.conf-sample default-mongo.conf

sudo nano default-mongo.conf

The content should look like this:

#
# dump backup directories
#
# for backup archives
BU_DIR=[path to backup archive store]
# working directories
# from docker-compose.yml 
BU_DIR_HOST=[path on host to mapped mongo container backup dir]
BU_DIR_DOCK=[path on mongo container to backup dir]
#
# Docker Compose details
#
# dir containing the docker-compose.yml
DC_DIR=[docker-compose directory for mongo container]
# name of the database container
DC_CONTAINER=[name of mongo container in docker-compose.yml]
#
# Reporting
#
# email address to send reports to, and subject
EMAIL=[admin email]
EMAIL_SUBJ="[email subject to distinguish this email from others]"

The values you set should look like this (replace [domain name] appropriate) - you can leave the original '#' comments in place if you want:

BU_DIR=/home/backup/mongodb
BU_DIR_HOST=/home/data/[domain name]/backups/mongodb
BU_DIR_DOCK=/backups
DC_DIR=/home/docker/[domain name]
DC_CONTAINER=mongo
EMAIL=[an email that you receive]
EMAIL_SUBJ="MongoDB Backup for Rocket.Chat: [domain name]"

save and close that file and then we have to create the location for the backups to be stored (and, ideally, transferred to the remote backup location along with the uploaded files and docker-compose.yml file):

sudo mkdir -p /home/backup/mongodb

Note, that the email alerts depend on you having configured your server properly to send out email as per our instructions for setting up a Docker Compose server.

You can test to make sure this all works by running

sudo /home/data/scripts/mongobackup/dbbackup-mongo --hourly

You should see a bunch of file paths as things are backed up - if you see nothing, you may have an error in your configuration.

To verify a backup has been made, you can run

ls -l /home/backup/mongodb/

and you should see a series of files (probably 3), named after each 'database' in the mongo server, with the name 'mongo-hourly' in them followed by the server's current date and time and a .tgz suffix.

If it works, copy the 'cron' task to your /etc/cron.d directory:

sudo cp dbbackup-mongo-cron /etc/cron.d/

after which, you should get hourly (and daily, weekly, monthly, and yearly) backups that tidy up after themselves...

Upgrading your installation

From time to time, assuming you've registered your Rocket.Chat installation, you will receive notifications that a new version of Rocket.Chat is available. You can upgrade at your convenience by creating a dated copy of your docker-compose.yml file - you can use this convenient little command (assuming you're in /home/docker/[domain name]):

sudo cp docker-compose.yml docker-compose.yml-$(date +"%Y%m%d")

and make sure you disable your instance

sudo docker-compose stop rocketchat

and then run a mongodb backup - the easiest way to do that is to run

sudo /home/data/scripts/mongobackup/dbbackup-mongo --hourly

as described above. Also, assuming the data involved is relatively small compared to your available storage space, you can copy your current mongo data to make sure you can recover quickly if necessary (after stopping mongodb!):

sudo docker-compose stop mongo

sudo cp -a /home/data/[domain name]/mongodb/data /home/data/[domain name]/mongodb/data-$(date +"%Y%m%d")

Then, to do the upgrade: edit docker-compose.yml to update the Rocket.Chat (4.5.0 in this tutorial) container number to the new version.

sudo nano docker-compose yml

at which point you can run:

sudo docker-compose up -d && sudo docker-compose logs -f

which will pull the newer Rocket.Chat container, and run it, along with MongoDB, which will automatically upgrade your instance if possible (if it succeeds, you'll see a message similar to the attached log image showing the Rocket.Chat version info in the log messages), and you'll be up and running with a new version, job done!

Enjoy your free (in both senses of the word) world-class messaging platform!

Add new comment

Hourly versioned MongoDB backup

dave — Mon, 29 Apr 2019 04:28:43 +0000

Hourly versioned MongoDB backup

Blog tags

mongodb

backup

docker

docker-compose

bash

dave Mon 29/04/2019 - 16:28

Because the collaboration of an open community is its real history, I place a high value on backing up the Rocket.Chat servers I'm responsible for, and especially the data they generate, held in MongoDB files (on the host) managed by a MongoDB container.

To do that reliably, I have set up a bash script which does an hourly backup of all MongoDB "databases" and automatically maintains 24 hourly, 7 daily, 4 weekly, 12 monthly, and 7 yearly snapshots of the databases.

Once you've configured your backup script properly, you should be able to run this command to do a backup...

/etc/mongobackup/dbbackup-mongo --hourly

easy-peasy.

Add new comment

Upgrading RocketChat to 1.0.x and MongoDB to 4.0

dave — Mon, 29 Apr 2019 02:39:33 +0000

Upgrading RocketChat to 1.0.x and MongoDB to 4.0

Blog tags

rocket.chat

mongodb

docker

docker-compose

ubuntu linux

dave Mon 29/04/2019 - 14:39

With the recent release of Rocket.Chat 1.0.x (after a couple years undergoing development at a fairly blistering pace), it's time for many of us to upgrade!

Previously, I showed how to install Rocket.Chat via Docker Compose but that was a much earlier version of Rocket.Chat and version 3.4 of MongoDB, which is now quite old (by FOSS standards at least). And it turns out upgrading everything has a few gotchas, so here's how I managed to do it.

Before you do anything do a backup of your MongoDB!

The first thing you need to do is upgrade the way in which you're running MongoDB. You have to enable a capability called "Local Replication".

Update your Docker Compose configuration

My first step, after logging into my virtual machine via SSH as the unprivileged user that I created to run docker commands, was to update my docker-compose.yml file (if you followed my previous instructions, you'll find it in /home/www/docker-rocketchat-wekan-mongo).

First, make a backup of it nearby...

cd /home/www/docker-rocketchat-wekan-mongo
cp docker-compose.yml docker-compose.yml-mongo3.4

and then edit the file to say this:

version: '2' services: mongo:     restart: unless-stopped     image: mongo:3.4     volumes:       - [data directory path]:/data/db       - [backup directory path]:/backups     command: --smallfiles --oplogSize 128 --replSet rs0 # 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:3.4     command: 'bash -c "for i in `seq 1 30`; do mongo mongo/rocketchat --eval \"rs.initiate({ _id: ''rs0'', members: [ { _id: 0, host: ''localhost:27017'' } ]})\" && s=$$? && break || s=$$?; echo \"Tried $$i times. Waiting 5 secs...\"; sleep 5; done; (exit $$s)"'     depends_on:       - mongo rocketchat:     restart: unless-stopped     image: rocketchat/rocket.chat:latest
command: bash -c 'for i in `seq 1 30`; do node main.js && s=$$? && break || s=$$?; echo "Tried $$i times. Waiting 5 secs..."; sleep 5; done; (exit $$s)'     ports:       - "127.0.0.1:[port number]:3000" # should be a free port above 1024     depends_on:       - mongo     environment:       - MONGO_URL=mongodb://mongo/rocket       - MONGO_OPLOG_URL=mongodb://mongo/local       - ROOT_URL=[domain name (including schema, e.g. http://)]     volumes:       - [upload directory path]:/var/www/rocket.chat/uploads
    labels:       - "traefik.backend=rocketchat"       - "traefik.frontend.rule=Host: [your domain name (not including schema)]"

Now, having updated your docker-compose.yml file, you have to do a couple other things. To do the upgrade from MongoDB 3.4 to 4.0, you have to do the interim upgrade to 3.6 first.

Enabling Local Replication

First you need to check what version of MongoDB you're currently using - both the version you're running and the "Feature Compatibility Version" (you can run a newer version of MongoDB, but configure it to only run features from some previous version to avoid breaking older software that depends on old features)... Do this as follows.

Access your MongoDB instance:

docker-compose exec mongo bash

That should give you a command prompt that looks like this:

root@a56eefe9f352: #

but the container identifier (after the @) will be different (but the same length). At that prompt, you can run this command:

mongo --eval "db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )"

Tip: if you're on a Linux desktop, you can copy this command (via CTRL-C) from this document and past it into your SSH terminal window (via CTRL+SHIFT-V).

It should tell you you're either running "featureCompatibilityVersion" 3.2 or 3.4. If it's the latter, skip this next step. If not, run this next:

mongo --eval "db.adminCommand( { setFeatureCompatibilityVersion: '3.4' } )"

to set the version to 3.4. If the command succeeds you'll likely see something like

{ "ok" : 1 }

as the response.

Now you can upgrade your Mongo 3.4 is the latest version (should be 3.4.20 at the time of this writing). Get out of the container (back to your Docker host) via CTRL-D (or "exit" - they're synonymous for logging out of a terminal session). Then you can run:

docker-compose pull mongo

That should update both your Mongo docker container to the latest version in the 3.4 series.

The final step to enabling local replication is to run

docker-compose up -d mongo mongo-init-replica && docker-compose logs -f

That will restart MongoDB and drop you into the stream of logging from all the containers (including the rocket.chat container). It'll also start the "mongo-init-replica" container. That container should run briefly and then exit cleanly having set up the local replication that you'll need for subsequent upgrades to MongoDB!

Check for any errors in the output... there might be a couple if it takes your MongoDB a bit of time to accept connections... as long as it eventually stops showing errors, you should be ok!

Upgrading Rocket.Chat to 1.0.x

Now that you're fully on version 3.4, running in local replica mode, you can update your Rocket.Chat instance. Rocket.Chat still supports Mongo 3.4 (it won't for long, thus this tutorial!), so you can now upgrade the Rocket.Chat container as well as make sure your Mongo 3.4 is the latest version (should be 3.4.20 at the time of this writing).

Note that the latest version of the Rocket.Chat docker container could be quite a lot higher when you read this... if it's beyond, say, 1.1 it might be unsafe to use the approach I'm describing. You can check the current version release status. To protect yourself, you can alter the rocket.chat image line in your docker-compose.yml file to explicitly tell it to use the 1.0.x series for which these instructions should continue to apply... pick the highest 1.0.x version you can find in the releases and alter the line in docker-compose.yml to specify that version:

image: rocketchat/rocket.chat:1.0.1

or whatever the latest 1.0.x version is. Then you can run:

docker-compose pull rocketchat

which will update your Rocket.Chat from the current version to the one specified.

Then restart your Rocket.Chat instance:

docker-compose up -d && docker-compose logs -f

That should restart both MongoDB and Rocket.Chat, and drop you into the stream of logging from both containers. It'll also start the "mongo-init-replica" container again, but having done its job it should exit happily again.

Check for any errors in the output... there might be a couple if it takes your MongoDB a bit of time to accept connections... as long as it eventually stops showing errors, you should be ok! Eventually, you should see something similar to (with version details updated appropriately):

Your instance is now running the right version! Time to tidy things up by upgrading Mongo the rest of the way to 4.0!

Upgrading to MongoDB 3.6

Now you can upgrade Mongo to 3.6. First, adjust your docker-compose.yml file. Update both occurances of this line:

image: mongo:3.4

image: mongo:3.6

Then you can do another

docker-compose pull mongo

which will download the newer Mongo 3.6 docker container. Then you can again run

docker-compose up -d && docker-compose logs -f

Again check for errors. If there are none (other than perhaps a brief set of "mongo is not accepting connections" errors), you should be fine to update the "compatibility version" from 3.4 to 3.6... Get a session on your Mongo container via

docker-compose exec mongo bash

and then (as above) run this:

mongo --eval "db.adminCommand( { setFeatureCompatibilityVersion: '3.6' } )"

which should give you a more complicated response than that for the 3.4 transition, but it should still more or less say "ok"... To make sure everything's happy with the change, it's wise to run

docker-compose up -d && docker-compose logs -f

again and make sure there're no obvious errors. If not (after making another database backup for safety!!) we can proceed to Mongo 4.0!

Final push to MongoDB 4.0

Finally, you can again edit your docker-compose.yml and change both occurrences of

image: mongo:3.6

image: mongo:4.0

Then you can do a final

docker-compose pull mongo

which will download the newer Mongo 4.0 docker container. Then you can again run

docker-compose up -d && docker-compose logs -f

And, assuming you don't see any errors, you can push the feature compatibility to 4.0:

docker-compose exec mongo bash

and then run:

mongo --eval "db.adminCommand( { setFeatureCompatibilityVersion: '4.0' } )"

followed by a final

docker-compose up -d && docker-compose logs -f

And, again, if you don't see any errors... you should get something a bit like this:

you're done and future proofed!

Add new comment

Docker Compose: A better way to deploy Rocketchat, Wekan, and MongoDB

dave — Mon, 22 May 2017 23:03:29 +0000

Docker Compose: A better way to deploy Rocketchat, Wekan, and MongoDB

Blog tags

docker-compose

rocket.chat

wekan

ubuntu linux

16.04

docker

mongodb

nginx

dave Tue 23/05/2017 - 11:03

A few months back, I posted instructions on deploying Rocket.Chat and Wekan instances (and their mutual dependency, MongoDB) individually. Since then, I've spent some time with Docker Compose, a set of scripts which help you to define, build, and manage a set of Docker containers. Docker Compose is a thing of beauty. This is the way I now deploy Rocket.Chat, Wekan, and MongoDB together.

Install Docker and Docker Compose

Install Docker (including the "post-installation" steps to allow non-root users to run Docker) and Docker Compose on your server (we recommend Ubuntu 16.04 or the older 14.04). We recommend using the "pip" (Python package manager) to do the install.

Create your Docker Compose recipe

We recommend creating a directory with an obvious name - in my case, it's /home/www/docker-rocketchat-wekan-mongo

In that directory, I create a file called docker-compose.yml containing (I've removed implementation specific details and replaced them with [placeholders]):

version: '2' services: mongo: restart: unless-stopped image: mongo volumes: - [data directory path]:/data/db - [backup directory path]:/backups command: --smallfiles rocketchat-oeru: restart: unless-stopped image: rocketchat/rocket.chat ports: - "127.0.0.1:[port number]:3000" # should be a free port above 1024 depends_on: - mongo environment: - MONGO_URL=mongodb://mongo/rocket - ROOT_URL=[domain name (including schema, e.g. http://)] volumes: - [upload directory path]:/var/www/rocket.chat/uploads wekan: restart: unless-stopped image: mquandalle/wekan ports: - "127.0.0.1:[port number]:80" # should be a free port above 1024 depends_on: - mongo environment: - VIRTUAL_HOST=[domain name (don't include schema, e.g. https://)] - MONGO_URL=mongodb://mongo/plan - ROOT_URL=[domain name (include schema, e.g. https://)] - MAIL_URL=smtp://[smtp username]:[smtp password]@[server name or IP]:[port: 25, 465, or 587]/ volumes: - [path to public content]:/built_app/programs/web.browser/app

Note, you can include multiple instances of either Rocket.Chat or Wekan simply by providing a new name (e.g. rocketchat2 or wekan2 or similar) and a new set of properties - just make sure you're using a unique (and otherwise unused) port number! You can check what's on your server's ports using netstat -punta | less to make sure you're not doubling up.

In case it's not obvious, you can leave out either the rocketchat or wekan definitions if you don't want to run those services!

Creating and Running the Docker Containers

It's easy to create the containers: simply run

docker pull mongo docker pull rocket.chat docker pull mquandalle/wekan

and when it's finished, run

docker-compose up

which should start all your containers, but leave you with a running log - this is great for testing, but when you're happy it's all running you hit CTRL-C (to shut down the current set of containers) and then run

docker-compose up -d

which runs the containers in daemon mode, without the running log. You can then log out of your server, and your containers will continue running!

Based on the configuration above (the "unless-stopped" directive), your containers will restart automatically if your server is rebooted. If you do want to stop them for some reason, you can via

docker-compose stop

Easy.

Serving them to the Web

Once you've got your containers running, you need to make sure you've got a web server running on your host to act as the reverse proxy so that external requests get sent to them reliably! We use Nginx.

RocketChat Nginx

Here's our configuration (with appropriate [substitutions]) - you can create it as /etc/nginx/sites-available/[domain name]:

server { listen 80; server_name [domain name];

## Access and error logs. access_log /var/log/nginx/[domain name]_access.log; error_log /var/log/nginx/[domain name]_error.log;

# see https://tech.oeru.org/protecting-your-users-lets-encrypt-ssl-certs include /etc/nginx/includes/letsencrypt.conf

# we use a 302 temporary redirect rather than a 301 permanent redir
location / { return 302 https://[domain name]$request_uri; } } server { listen 443 ssl; ssl on;
# see https://tech.oeru.org/protecting-your-users-lets-encrypt-ssl-certs ssl_certificate /etc/letsencrypt/live/[domain name]/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/[domain name]/privkey.pem; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_dhparam /etc/ssl/certs/dhparam.pem;

keepalive_timeout 20s;

root /var/www/html; index index.html index.htm;

server_name [domain name];

## Access and error logs. access_log /var/log/nginx/[domain name]_access.log; error_log /var/log/nginx/[domain name]_error.log;

location / { proxy_pass http://127.0.0.1:[your rocketchat port]; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $http_host; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forward-Proto http; proxy_set_header X-Nginx-Proxy true; proxy_redirect off; } }

Wekan Nginx

Here's our configuration (with appropriate [substitutions]) - you can create it as /etc/nginx/sites-available/[domain name]:

# from https://github.com/wekan/wekan/wiki/Install-Wekan-Docker-in-production upstream websocket { server 127.0.0.1:[wekan port]; }

map $http_upgrade $connection_upgrade { default upgrade; '' close; }

server { listen 80; root /var/www/html; index index.html index.htm;

# Make site accessible from http://localhost/ server_name [domain name];

access_log /var/log/nginx/[domain name]_access.log; error_log /var/log/nginx/[domain name]_error.log;

# see https://tech.oeru.org/protecting-your-users-lets-encrypt-ssl-certs include /etc/nginx/includes/letsencrypt.conf

location / { return 302 https://[domain name]$request_uri; } }

server { listen 443 ssl; ssl on;
# see https://tech.oeru.org/protecting-your-users-lets-encrypt-ssl-certs ssl_certificate /etc/letsencrypt/live/[domain name]/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/[domain name]/privkey.pem; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_dhparam /etc/ssl/certs/dhparam.pem;

keepalive_timeout 20s;

access_log /var/log/nginx/[domain name]_access.log; error_log /var/log/nginx/[domain name]_error.log;

root /var/www/html; index index.html index.htm;

server_name [domain name];

location / { proxy_read_timeout 300; proxy_connect_timeout 300; proxy_redirect off; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto scheme; proxy_pass http://127.0.0.1:[your wekan port]; proxy_set_header Host $host; }

location ~ websocket$ { proxy_pass http://websocket; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; }
}

Enable Nginx Configuration

To make your configurations active, do the following for each of your Nginx configurations:

cd /etc/nginx/sites-enabled

Do this for each file:
ln -sf ../sites-available/[filename] .

To check if there are any errors in the files, run

nginx -t

If not, you can restart Nginx to incorporate the new configuration files:

sudo service nginx reload

You can check for errors in the relevant log files specified in your nginx configurations above in /var/log/nginx/*_error.log or /var/log/nginx/*_access.log.

Protecting your users and reputation with encryption

We encourage you to ensure that these services are made available with full encryption to protect your users' privacy. It's easy (and no cost) to set up! The "include" directive in the Nginx configuration files above are examples of this approach.

Upgrades and Backups

We also encourage you to keep your services upgraded. It's easy to do and you'll experience little if any perceptible down time!

Simply re-pull the containers and restart them - the updated containers will be launched without loss of data!

docker pull mongo docker pull rocket.chat docker pull mquandalle/wekan

docker-compose up -d

If you want to back up your data - you need to do normal file backups of the directories on your local server that you've configured in the docker-compose.yml file, and you can do MongoDB backups based on our previous article on the topic!

Add new comment

Installing Rocket.Chat with Docker on Ubuntu Linux 14.04

dave — Wed, 23 Nov 2016 21:59:47 +0000

Installing Rocket.Chat with Docker on Ubuntu Linux 14.04

Blog tags

install

ubuntu linux

14.04

docker

rocket.chat

let's encrypt

mongodb

dave Thu 24/11/2016 - 10:59

Rocket.Chat is a modern, open source messaging application which is functionally similar to a popular (and heavily marketed) proprietary tool called Slack. Rocket.Chat is built on a powerful open source real-time collaboration platform called Meteor (which, in turn, is built on the Node.JS open source framework), which supports real-time collaborative applications. The real-time collaboration means that if multiple people are using an app at the same time, even if they're spread across the world, they'll see the changes others are making in real-time.

The OERu has a Rocket.Chat instance that has been getting very positive feedback from our Open Education Resource designers and collaborators, who use it to communicate with us at the OER Foundation, and with their fellow collaborators. There are currently about 20 channels to which users can subscribe and in which they can participate, dedicated to different topics of discussion.

Rocket.Chat instances store their data in another open source tool, a key-value storage engine called MongoDB - these instructions assume that you have already got a running MongoDB installed, and to facilitate that, we've provided this handy MongoDB install guide as a companion.

This guide will cover both configuring and launching a Docker container with a working instance of Rocket.Chat. It will, in turn, be linked to another Docker container running MongoDB, and both will be capable of sending email via external authenticating email server. External user access to Rocket.Chat is provided by the Nginx web server (as a forward proxy). User interaction with Rocket.Chat is (and should always be) encrypted via recognised SSL certificates using the brilliant (and gratis) Let's Encrypt service.

This instruction set assumes that you have command-line access (via SSH, in most cases) to your server, running Ubuntu Linux 14.04, probably a Virtual Machine hosted in a data centre somewhere - a very inexpensive way to do this is, for example, via DigitalOcean (for the record, we have no relationship with DigitalOcean, I simply have substantial experience with their services), but there are many many options worldwide. These instructions will need to be modified slightly for other versions of Linux (e.g. Debian 8 or Ubuntu 16.04 or CentOS or others), but should be mostly valid. We'd be grateful to hear about anyone else's experiences in the comments below!

Installing Docker

See our instructions in the MongoDB blog post.

Installing Rocket.Chat

First, we would normally create a rocketchat user to create a place for any persistent data required for the app:

sudo adduser rocketchat

Although Rocket.Chat stores almost everything in the MongoDB you've already set up, it can store uploaded files in a designated directory so they survive updates to the Docker image:

sudo -u rocketchat mkdir /home/rocketchat/uploads

Assuming you've got Docker installed properly, to install the official Rocket.Chat Docker image, you can just run:

docker pull rocketchat/rocket.chat

Then you can launch it by running this by first launching your MongoDB container, and then running this (assumes you've named your MongoDB instance "mongodb" as per our instructions):

docker run -d --name rocketchat -p 8051:3000 \ -h [your_RocketChat_domain] \ -v /home/rocketchat/uploads:/var/www/rocket.chat/uploads \ -e "MAIL_URL=[outgoing_mail_server]" \ --link mongodb:mongo -e "MONGO_URL=mongodb://mongo/chat" \ -e "ROOT_URL=http://[your_RocketChat_domain]" \ --restart unless-stopped rocketchat/rocket.chat

Note: Please copy and paste the exact text of your "docker run" command into a reference file (I usually have a "README.oeru" reference file in the home directory of each Docker-based app I run) as you will want to refer to it when doing upgrades!

You'll need to make sure you set appropriate values for [your_RocketChat_domain] and details for an SMTP (outgoing mail) server, because Rocket.Chat needs to send emails related to things like account registration, forgotten passwords, and configurable notifications, for example to alert you that you've been mentioned in discussions.

You can use either a local mail server on the Docker host, in which case you'd put the local IP address of your server, as it would be seen by the Docker container, so 172.17.42.1 is the default IP of a Docker host. You could also use an authenticating SMTP server, and specify the details like this: smtp://[username]:[password]@[IP-or-domainname]:[port, usually 25, 465, or 587]. Here's a what a made-up example might look like:

-e "MAIL_URL=smtp://smtpmail:blahdiblah88@mail.oeru.org:25"

Note, the --restart unless-stopped will ensure that this container is restarted on a reboot unless it's explicitly stopped, like via a docker stop rocketchat, like you might to update the Docker container.

Setting up Nginx as a proxy server

Having set up the Docker container, which is listening on port 8051 on the Docker container's host, you'll need to set up a reverse proxy on that host to make the site visible to the broader internet on your public IP address (you'll want to make sure the domain you specified above points to that IP address or is a CNAME to a domain that does).

Once you've got that, you can proceed. In /etc/nginx/sites-available, I create a file called plan (as we use plan.oeru.org as our domain). Note, I use "vim" as my text editor. If you don't know it, perhaps use "nano" instead. It's much less powerful, but easier to use...

sudo vim /etc/nginx/sites-available/chat

Here're the contents - you'll want to change the domain name to suit your own choices. Similarly the names of SSL files and logs. The following file has a chunk in the middle commented out with "#s". More on that below:

server {

        listen 80; # this is one of our external IPs on the server.         #listen   [::]:80 default ipv6only=on; ## listen for ipv6         root /usr/share/nginx/www;         index index.html index.htm;         server_name chat.oeru.org;         access_log /var/log/nginx/chat.oeru.org_access.log;         error_log /var/log/nginx/chat.oeru.org_error.log;         location /.well-known {                 root /var/www/html;                 default_type text/plain;         } #        location / { #                return 301 https://chat.oeru.org$request_uri; #        }      #} # #server { #        listen 443 ssl; #        ssl on; #        ssl_certificate /etc/letsencrypt/live/chat.oeru.org/fullchain.pem; #        ssl_certificate_key /etc/letsencrypt/live/chat.oeru.org/privkey.pem;
#        ssl_protocols TLSv1 TLSv1.1 TLSv1.2; #        ssl_dhparam /etc/ssl/certs/dhparam.pem; #        keepalive_timeout 20s; # #        access_log /var/log/nginx/chat.oeru.org_access.log; #        error_log /var/log/nginx/chat.oeru.org_error.log;
#        root /var/www/html; #        index index.html index.htm;
#        server_name chat.oeru.org; # #        location /.well-known { #                root /var/www/html; #                default_type text/plain; #        }

location / { proxy_read_timeout 300; proxy_connect_timeout 300; proxy_redirect off; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://127.0.0.1:8081; }
}

When you've set up the file, you can enable it:

sudo ln -sf /etc/nginx/sites-available/chat /etc/nginx/sites-enabled

Test the file to ensure there aren't any syntax errors before reloading nginx:

sudo nginx -t

If this shows an error, you'll need to fix the file. If all's well, reload nginx to include the new configuration:

sudo service nginx reload

You should now be able to point your browser at your domain name, and you should get your Rocket.Chat site via the HTTP (not encrypted) protocol.

A word to the wise - if it doesn't work, check your firewall settings!

In the next step, we'll sort out your SSL certificate from Let's Encrypt.

Protecting your users

Have a look at our Let's Encrypt howto.

Upgrading Rocket.Chat

You should periodically upgrade Rocket.Chat, say every couple months, to benefit from improved features... The upgrade process usually means a few minutes of down time for the site, so pick a time when it isn't likely to be heavily used... You'll normally want to upgrade any dependent Docker containers at the same time (like your MongoDB and Wekan) so we have a dedicated Upgrade article for that.

Add new comment

Upgrading your Docker Apps: MongoDB, Wekan, and Rocket.Chat

dave — Wed, 23 Nov 2016 21:56:41 +0000

Upgrading your Docker Apps: MongoDB, Wekan, and Rocket.Chat

Blog tags

wekan

rocket.chat

mongodb

dave Thu 24/11/2016 - 10:56

(Update 2017-05-24: see an easier way to run Wekan, Rocketchat, and MongoDB) You may not have all of these installed, but if you're running Wekan or Rocket.Chat based on our instructions, you'll also have MongoDB, and the need to keep them all up-to-date to benefit from their rapid development processes (quick bug fixes and new and improved features every few days!).

I'd recommend doing an upgrade monthly or more rapidly if you hear about security issues, or fixes to any bugs which might be affecting you.

Upgrading Step By Step

1. find the 3 IDs of the mquandalle/wekan, rocketchat/rocket.chat, and mongo containers you're running via

docker ps

The output might look something like this:

5c35737f4de2 mongo "/entrypoint.sh mongo" 45 hours ago Up 45 hours 27017/tcp oeru-mongo 7e8ef524ba0a mquandalle/wekan "/bin/sh -c 'bash $ME" 45 hours ago Up 45 hours 127.0.0.1:5555->80/tcp plan b370ad72f358 rocketchat/rocket.chat "node main.js" 45 hours ago Up 45 hours 127.0.0.1:7996->3000/tcp chat

in this case, the relevant IDs are 5c35737f4de2, 7e8ef524ba0a, and b370ad72f358

2. Stop the containers:

docker stop 5c35737f4de2 7e8ef524ba0a b370ad72f358

3. Remove the old containers (not the images):

docker rm 5c35737f4de2 7e8ef524ba0a b370ad72f358

4. Update the images to the latest versions for each.

docker pull mongo docker pull mquandalle/wekan docker pull rocketchat/rocket.chat

5. restart updated MongoDB (create new container) using the same "docker run" command you used initially.

6. similarly restart your updated Rocket.Chat and Wekan containers, using exactly the same "docker run" command you used initially.

Add new comment

Installing Wekan with Docker on Ubuntu Linux 14.04

dave — Thu, 27 Oct 2016 01:12:48 +0000

Installing Wekan with Docker on Ubuntu Linux 14.04

Blog tags

install

ubuntu linux

14.04

mongodb

wekan

docker

let's encrypt

dave Thu 27/10/2016 - 14:12

Wekan is an excellent, easy-to-use "kanban board" project management support tool, suitable for all manner of projects. For those who have used the highly marketed Trello kanban service, Wekan is functionally similar open source alternative that organisations can host and control for themselves. They can also enhance it in whatever ways they are moved to do so. We encourage our partner institutions to consider this path as a way of reducing costs as well as increasing freedom and privacy. To make migrating a win-win, we have also found that Wekan is able to import entire Trello boards, preserving your data. (Update: 2017-05-24 we've just published an easier way to run Wekan and MongoDB)

The OERu provides a Wekan instance that has proven very popular with our Open Education Resource designers and collaborators.

Wekan instances store their data in another open source tool, a key-value storage engine called MongoDB - these instructions assume that you have already got a running MongoDB installed, and to facilitate that, we've provided this handy MongoDB install guide as a companion.

This guide will cover both configuring and launching a Docker container with a working instance of Wekan. It will, in turn, be linked to another Docker container running MongoDB, and both will be capable of sending email via external authenticating email server. External user access to Wekan is provided by the Nginx web server (as a forward proxy). User interaction with Wekan is (and should always be) encrypted via recognised SSL certificates using the brilliant (and gratis) Let's Encrypt service.

Installing Docker

See our instructions in the MongoDB blog post.

Installing Wekan

First, we would normally create a wekan user:

sudo adduser wekan

and then create a directory in that user's space to store Wekan-related data (so it survives updates to the Docker image):

sudo -u wekan mkdir /home/wekan/public

Assuming you've got Docker installed properly, to install the official Wekan Docker image, you can just run:

docker pull mquandalle/wekan

Then you can launch it by running this by first launching your MongoDB container, and then running this (assumes you've named your MongoDB instance "mongodb" as per our instructions):

docker run -d --name wekan -p 127.0.0.1:5555:80 \ -h [your_Wekan_domain] -e "VIRTUAL_HOST=[your_Wekan_domain]" \ -v /home/wekan/public:/built_app/programs/web.browser/app \ -e "MAIL_URL=[outgoing_mail_server]" \ --link mongodb:mongo -e "MONGO_URL=mongodb://mongo/plan" \ -e "ROOT_URL=http://[your_Wekan_domain]" \ --restart unless-stopped mquandalle/wekan

You'll need to make sure you set appropriate values for [your_Wekan_domain] and details for an SMTP (outgoing mail) server, because Wekan needs to send emails. You can use either a local mail server on the Docker host, in which case you'd put the local IP address of your server, as it would be seen by the Docker container, so 172.17.42.1 is the default IP of a Docker host. You could also use an authenticating SMTP server, and specify the details like this: smtp://[username]:[password]@[IP-or-domainname]:[port, usually 25, 465, or 587]. Here's a what a made-up example might look like:

-e "MAIL_URL=smtp://smtpmail:blahdiblah88@mail.oeru.org:25"

Note, the --restart unless-stopped will ensure that this container is restarted on a reboot unless it's explicitly stopped, like via a docker stop wekan, like you might to update the Docker container.

Setting up Nginx as a proxy server

Having set up the Docker container, which is listening on port 5555 on the Docker container's host, you'll need to set up a reverse proxy on that host to make the site visible to the broader internet on your public IP address (you'll want to make sure the domain you specified above points to that IP address or is a CNAME to a domain that does).

sudo vim /etc/nginx/sites-available/plan

# from https://github.com/wekan/wekan/wiki/Install-Wekan-Docker-in-production upstream websocket { server 127.0.0.1:5555; }

map $http_upgrade $connection_upgrade { default upgrade; '' close; }

server {         listen 80; # this is one of our external IPs on the server.         #listen   [::]:80 default ipv6only=on; ## listen for ipv6         root /usr/share/nginx/www;         index index.html index.htm;         server_name plan.oeru.org;         access_log /var/log/nginx/plan.oeru.org_access.log;         error_log /var/log/nginx/plan.oeru.org_error.log;         location /.well-known {                 root /var/www/html;                 default_type text/plain;         } #        location / { #                return 301 https://plan.oeru.org$request_uri; #        }      #} # #server { #        listen 443 ssl; #        ssl on; #        ssl_certificate /etc/letsencrypt/live/plan.oeru.org/fullchain.pem; #        ssl_certificate_key /etc/letsencrypt/live/plan.oeru.org/privkey.pem;
#        ssl_protocols TLSv1 TLSv1.1 TLSv1.2; #        ssl_dhparam /etc/ssl/certs/dhparam.pem; #        keepalive_timeout 20s; # #        access_log /var/log/nginx/plan.oeru.org_access.log; #        error_log /var/log/nginx/plan.oeru.org_error.log;
#        root /var/www/html; #        index index.html index.htm;
#        server_name plan.oeru.org; # #        location /.well-known { #                root /var/www/html; #                default_type text/plain; #        }

location / { proxy_read_timeout 300; proxy_connect_timeout 300; proxy_redirect off; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://127.0.0.1:5555; proxy_set_header Host $host; }

location ~ websocket$ { proxy_pass http://websocket; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; } }

When you've set up the file, you can enable it:

sudo ln -sf /etc/nginx/sites-available/plan /etc/nginx/sites-enabled

Test the file to ensure there aren't any syntax errors before reloading nginx:

sudo nginx -t

If this shows an error, you'll need to fix the file. If all's well, reload nginx to include the new configuration:

sudo service nginx reload

You should now be able to point your browser at your domain name, and you should get your Wekan site via the HTTP (not encrypted) protocol.

A word to the wise - if it doesn't work, check your firewall settings!

In the next step, we'll sort out your SSL certificate from Let's Encrypt.

Protecting your users

Have a look at our Let's Encrypt howto.

Upgrading Wekan

You should periodically upgrade Wekan, say every couple months, to benefit from improved features... The upgrade process usually means a few minutes of down time for the site, so pick a time when it isn't likely to be heavily used... You'll normally want to upgrade any dependent Docker containers at the same time (like your MongoDB and Rocket.Chat) so we have a dedicated Upgrade article for that.

Add new comment

Installing MongoDB with Docker on Ubuntu Linux 14.04

dave — Thu, 27 Oct 2016 01:06:55 +0000

Installing MongoDB with Docker on Ubuntu Linux 14.04

Blog tags

install

ubuntu linux

14.04

docker

mongodb

dave Thu 27/10/2016 - 14:06

This post describes installing MongoDB (and backing it up and restoring from backup) in a Docker container on an Ubuntu Linux 14.04 virtual machine. (Update: 2017-05-24 we've just published an easier way to run MongoDB and Rocket.Chat and Wekan which depend on it)

The motivation for installing MongoDB is that it is the key-value based data container engine used by two compelling web technologies, Rocket.Chat and Wekan, that the OER Foundation has deployed for the OERu as https://chat.oeru.org and https://plan.oeru.org.

Installing Docker

Rather than trying to write a comprehensive guide to installing Docker, I'll instead recommend that you have a look at this one provided by the Docker community. It also covers installing on other versions of Ubuntu which might be helpful for some. Once you've got a working Docker container install going on your server, you can continue to the next step...

Note: the idea with Docker is that nothing important is stored in the container itself. That means that you can blow it away at any time without losing any important data. You can do that to quickly upgrade it, or to change its properties. You simply re-launch the container making sure it points properly to the persistent stuff you want it to use.

Installing MongoDB

Once you've got Docker working on your virtual machine, getting the MongoDB docker container (where it's preinstalled and ready to go) is simple:

docker pull mongo

This will install the latest version of the MongoDB container from docker.io.

Launching MongoDB

I recommend setting up a per-container user to help keep things well segmented. You can create a "mongo" user:

sudo adduser mongo

This creates a directory /home/mongo and that's where we'll get the Mongo container to store the data we want to keep persistent.

We can create "data" and "backups" directories in which it should store its data and save its backups respectively:

sudo mkdir /home/mongo/data sudo mkdir /home/mongo/backups

Then you can launch the container:

docker run --name mongodb --restart unless-stopped \ -v /home/mongo/data:/data/db -v /home/mongo/backups:/backups -d mongo --smallfiles

You should be able to check it's running by typing

docker ps

and looking for the reference to "mongodb" (that's the "name" we've assigned to this instance of the "mongo" container).

You can even log into the container and poke around the filesystem if you like, using the container's "id":

ID=`docker ps | grep mongo | cut --characters=1-12` docker exec -it $ID bash

which will drop you at the command line in the container. You can exit with "exit" or CTRL-D.

If things go wrong, you can run this:

ID=`docker ps | grep mongo | cut --characters=1-12` docker inspect $ID | grep log

Which will give you a result like this (your filenames will be different):

"LogPath": "/var/lib/docker/containers/539072b8fb976b5048bd13e90074ea4b43166b81c3d69d1720b4746785f7d917/539072b8fb976b5048bd13e90074ea4b43166b81c3d69d1720b4746785f7d917-json.log",

In which case, you can look at the log file to see what's gone wrong:

less +G /var/lib/docker/containers/539072b8fb976b5048bd13e90074ea4b43166b81c3d69d1720b4746785f7d917/539072b8fb976b5048bd13e90074ea4b43166b81c3d69d1720b4746785f7d917-json.log

You can exit less by hitting "q" or CTRL-C.

Backing up MongoDB

Backing up MongoDB requires a somewhat circuitous process. Here's what I do (after quite a bit of head scratching and web searching - Note: these backups are not directly related to the "backups" directory created above. More on that in the script below.):

On the host VM, I create a directory for backups - I use /home/backup

sudo mkdir /home/backup

and I create a bin directory in /home/mongo

sudo mkdir /home/mongo/bin

and I create a script file with my preferred editor (I use vim, you could use nano instead if vim scares you):

sudo vim /home/mongo/bin/mongo_backup.sh

In it, I put the following:

#!/bin/bash
#
# backup all the mongo DBs hosted on this server, in a docker container
#
# useful reference: https://docs.mongodb.org/manual/core/backups/
#
# in event of a disaster, this could be useful:
# https://docs.mongodb.org/manual/tutorial/recover-data-following-unexpec…
#
# script copyright dave@davelane.nz - available under terms of GPL v2 or later,
# see https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
#
# Note: I've commented out some "echo" statements below that might be useful if you're
# debugging this script...
DATE=`date '+%Y%m%d-%H%M%S'`
# this is the local backup directory - gets cleared out after every backup...
DIR=/home/mongo/backups
# the archive dir, with a past archive as well.
ARCHDIR=/home/backup/mongodb
PREV=$ARCHDIR/previous
LATEST=$ARCHDIR/latest
#
# this is the backup directory on the Docker host
DDIR=/backups
# 1. get mongo container (this assumes only one running on the machine, with "mongo" in is name!)
ID=`docker ps | grep "mongo" | cut -c 1-12`
##echo "working with ID = $ID"
#
# 2. back up databases
# 2.1 backup to the local $DDIR on the Docker host
MSG=`docker exec -i $ID mongodump --quiet --out $DDIR`
##echo $MSG
# go into local backup dir
CWD=`pwd`
cd $DIR
# 2.2. get list of backup databases
DBS=`find $DIR -mindepth 1 -maxdepth 1 -type d -exec basename {} \;`
for DB in $DBS
do
    ARCH="${DB}.tgz"
    if [ -f $PREV/$ARCH ] ; then
        ##echo "explicitly jettison old backup of $PREV/$ARCH"
        rm $PREV/$ARCH
    else
        echo "***no previous version of $ARCH in $PREV on $DATE"
    fi
    if [ -f $LATEST/$ARCH ] ; then
        ##echo "move previous $LATEST/$ARCH into $PREV (overwritting old)"
   mv $LATEST/$ARCH $PREV/$ARCH
    else
        echo "***no latest backup $ARCH in $LATEST on $DATE"
    fi
    ##echo "archiving contents of $DB into $LATEST/$ARCH"
    tar cvfz $LATEST/$ARCH $DB
    #echo "removing $DB *.json and *.bson and the dir"
    rm -f $DB/*.bson $DB/*.json
    rmdir $DB
done
# return to where we started
cd $CWD
# exit with a happy 0, which shows we were successful!
exit 0

Save that file, and then run this to fix the ownership of the file and make the script executable:

sudo chown -R mongo:mongo /home/mongo/* sudo chmod a+x /home/mongo/bin/mongo_backup.sh

You can try running the script to make sure it creates a backup of your mongo database (such as it is! There might not be much there yet, if you haven't got any apps installed that use MongoDB - you can wait until after that before testing. If you run it twice, you should see both a "latest" and "previous" backup directory containing suitably dated directories - this provides extra data security):

sudo /home/mongo/bin/mongo_backup.sh

Once you're happy that's working, set up a cron job to make it run daily... Again, edit a file with your preferred text editor:

sudo vim /etc/cron.d/mongodb-backup

and fill it with the following (replacing [an email that will get to you!] appropriately):

#
# cron.d/mongodb-backup -- backups up the Mongo DBs running in a docker container
#
#
MAILTO=[and email that will get to you!]
# run daily at 12:17pm as the root user
17 12 * * * root /home/mongo/bin/mongo_backup.sh

Recovering a MongoDB database

In the event that you ever have to recover or transfer a MongoDB database, aka container, you can do so like this (sort of the reverse of the backup script):

work out the name of the container you want to restore and copy the backup of the database directory (e.g. rocketchat or wekan) into /home/mongo/backups - to be clear: for MongoDB, a "database" is represented as a directory of files holding all the relevant data.

Then log into Docker instance:

ID=`docker ps | grep mongo | cut --characters=1-12` docker exec -it $ID bash

and on the Docker container's command line run this, replacing the [names] appropriately below. Note, you might want to change the database name from the backup's original to a new name, so they don't need to be the same (but they can be):

mongorestore --db [recovered DB Name] --drop /backups/[backed up DB Name]/

Upgrading MongoDB

Note, if you have other apps in other containers that depend on MongoDB, it's usually most convenient to upgrade them all at the same time. Look at our instructions for, for example, running Wekan, to see how to upgrade MongoDB.

Blog comments

Really helpful post - thx I…

Keith W (not verified) Thu 15/07/2021 - 08:48

Really helpful post - thx

I had to remove the --smallfiles from the command to start the docker/mongo container