The Dokku mongo plugin provides a mongo:connect command, which opens a tunnelled connection to you MongoDB instance on Dokku. This is how you can connect to your database using the tool of your choice, the examples will be using Robo3T.

Pre-requisites

dokku-mongo is installed

See github.com/dokku/dokku-mongo, to install it:

• ssh into the server running Dokku as root
• run: sudo dokku plugin:install https://github.com/dokku/dokku-mongo.git mongo

You have a database to play with

Create one with: ssh -t dokku@YOUR_INSTANCE_IP mongo:create public-database

You should get the following output, the bolded string is the mongo connection URI:

Waiting for container to be ready
=====> MongoDB container created: public-database
=====> Container Information
    Config dir: /var/lib/dokku/services/mongo/public-database/config
    Data dir: /var/lib/dokku/services/mongo/public-database/data
    Dsn: mongodb://public-database:289b4a4b32ab3182895d8aac7def0ee1@dokku-mongo-public-database:27017/public-database
    Exposed ports: -
    Id: 67163f2006dd9e17f8325620814bae9b881ee6465088b8b1c571fbb6c08ac801
    Internal ip: 172.17.0.11
    Links: -
    Service root: /var/lib/dokku/services/mongo/public-database
    Status: running
    Version: mongo:3.4.9

Connect to your remote MongoDB instance on Dokku

First off, let’s check that we can connect using the included dokku-mongo :connect command. Run the following command:

ssh -t dokku@YOUR_INSTANCE_IP mongo:connect public-database

It should open a MongoDB shell:

MongoDB shell version v3.4.9
connecting to: mongodb://127.0.0.1:27017/public-database
MongoDB server version: 3.4.9
>

Dokku’s behaviour around access of MongoDB

If we look back at the mongo:info output we’ll notice the following line:

Exposed ports: -

That means this MongoDB instance is not exposed to anything outside of Dokku, that’s good for security, bad for accessing it from your local tools.

Exposing our MongoDB instance

We’ll need to expose it, and pass some ports we want to map to (this helps with predictability/reproducibility)

ssh -t dokku@YOUR_INSTANCE_IP mongo:expose public-database 20017 20018 20019 20020

Which yields the following output:

-----> Service public-database exposed on port(s) [container->host]: 27017->20017 27018->20018 27019->20019 28017->20020

Which means the MongoDB ports 27017, 27018, 27019 and 28017 were exposed at the server’s 20017, 20018, 20019, 20020 ports respectively.

Connecting with Robo3T

In order to connect with Robo3T we’ll create a new connection to the MongoDB instance.

• Open the “Connect” menu (File > Connect)
• In the first line, click “Create”
• Fill out the “Connection” tab, of course, replace YOUR_SERVER_IP with your actual server IP or domain name.

• Fill out the “Authentication” tab, if you remember our connection string from dokku mongo:info public-database, **mongodb://public-database:289b4a4b32ab3182895d8aac7def0ee1@dokku-mongo-public-database:27017/public-database**
  • The format is mongodb://USERNAME:PASSWORD@INTERNAL_HOSTNAME:INTERNAL_PORT/DATABASE_NAME
  • So we have
  • Database: public-database
  • User Name: public-database
  • Password: 289b4a4b32ab3182895d8aac7def0ee1 (use your actual password)

• You can now hit “Test” and it should tell you everything is fine
• You can “Save” and “Connect” to this new database

Testing out the connection

Create a new collection “newest-public-spaces”

Insert some data

Let’s disconnect and go back to the dokku-mongo plugin connection and get data for the newest-public-spaces collection to see if we were talking to the same database.

ssh -t dokku@YOUR_SERVER_IP mongo:connect public-database
MongoDB shell version v3.4.9
connecting to: mongodb://127.0.0.1:27017/public-database
MongoDB server version: 3.4.9
> db.getCollection('newest-public-spaces').find({})
{ "_id" : ObjectId("5c2a39e6e632f9bc24ec1a2d"), "name" : "my park", "location" : "next door" }

Security concerns

These connections are not done with TLS (transport layer security), which is fine for non-sensitive data.

I would also suggest using dokku mongo:unexpose YOUR_DATABASE_NAME when not actively using the connection.

For more about Dokku and deployment see: Deployment options: Netlify + Dokku on DigitalOcean vs now.sh, GitHub Pages, Heroku and AWS or the “Deployment” category on Code with Hugo

If you’re looking for a good place to host your Dokku instance, I recommend DigitalOcean, they have a great One-click install and deploy Dokku, if you use this referral link you’ll get $100 free credit.

unsplash-logo
Cameron Kirby