TUTORIALS

Starting points for below instructions

Below instructions will guide you through the steps which are required to host a CouchDB Docker container on your Synology NAS. Although there other ways (Portainer Stacks) of running the CouchDB Image as container on your NAS, below instructions will use the native -out of the box- toolset as part of your Synology DSM operating system. This tutorial will enable you to deploy a CouchDB container on your Synology NAS which you can securely connect to within your own network.

Instructions

Step1: Open the Docker Manager on your Synology NAS

Step2: Select the Image you would like to use

After you have opened the Docker manager, please:

1. Click on Registry
2. Search for couchdb
3. Select the ‘couchdb’ option

When you have selected the image, please click on the Download button to download the image. When requested, pick the latest tag to download:

Your image will be download, see the blue indicator next to the Image section:

Step3: Configure a container from your CouchDB Image

Once your image is download (this can take some time, depending on your network speed), switch to the ‘Image’ tab, where you will find your just downloaded Image:

Select the couchdb:latest image and click on the Launch button:

You will now be guided though the setup and configuration steps of the container. The first step is to pick your Network. Please keep the default option -bridge- and click on the NEXT button:

The next screen will request you to configure some general settings.
First of all, give your new container a name which makes sense.
Please make sure to enable the auto restart option, which will make sure your container will automatically restart when it is stopped from running. This can -for example- happen when your NAS is rebooted.

Now that the initial settings are configured, you can click on the Advanced Settings button. A new screen will appear:

We need to create 2 additional Environment Variables to ensure our CouchDB instance will work properly:

1. COUCHDB_USER => which defines the username which will enables you to login to CouchDB
2. COUCHDB_PASSWORD => the password to use for the above defined user

Once you have added these 2 variables, click on the SAVE button and you will be redirected to the General Settings screen where you can click the NEXT button which will direct you to the next step/screen of the guided setup. This screen will define the network ports CouchDB will expose from the container. In order to access the container via these ports from your server, you should map them to similar local (server) ports. In addition you should add an additional port configuration (port 6984) which we will use later:

When you created above mapping, you can click on the NEXT button which will direct you to the screen where you will have to map a directory (volume in docker terms) from the container to a local (NAS) directory. This will ensure that the data persist hen the container needs to be rebooted, re-deployed or upgraded to a new version.

Click on the Add Folder options and provide the details as per below screenshot. Please make sure that you have created the folders you would like to map towards within your file explorer on your Synology NAS. In my example below I created the folders /docker/couchdb/data & /docker/couchdb/cert in the root of my Synology file explorer.

Click on the NEXT button and you will be directed to the last screen which will provide you with a summary of the settings you created:

When all the settings are correct, you can choose the DONE button to confirm. The container will be deployed and initialized.

Step4: Validate if your container is running

In order to validate if your container is running, please click on the ‘container’ tab and search for the container you just deployed:

As you can see in above screenshot, mine is properly running 🥳🎉. In addition you can validate in your browser if the database is running by typing <your server ip>:5984

Step5: Some additional settings for Nomie

As Nomie runs as a PWA from within your webbrowser and stores data in the browser cache, by default it will not be able to connect with your CouchDB server/data. This is by design -to keep your setup secure- to prevent that the CouchDB server can be connected and consumed from each and every ‘domain’.
We need to configure CouchDB to allow for Cross-Origin Resource Sharing (CORS). We will configure CouchDB via its admin Gui.
In your browser, please go to <your server ip>:5984/_utils and logon with your userid and password you configured in Step3.

After you have successfully logged in, please go to the settings page and select CORS as per below screenshot:

Now, click on the Enable CORS button and you will be given the below options:

You can either allow CouchDB to be accessed from all domains (not recommended from a security perspective), or you can specify the domain your Nomie application is running from. Click on the Add Domain button to activate your input.

Step6: Initialize CouchDB

We need to make sure that we run CouchDB in single Node Mode, as that all we need for our Nomie setup. In order to do so, please point your browser to <your server ip>:5984/_utils/#setup/singlenode

Once you have clicked the Configure Node button, you will get a message about replicating data. You can ignore this for our single node purpose.

Step7: Create your database

While you are in the CouchDB user interface, please click on the database icon and choose ‘Create Database’ as per below screenshot. Once done, you can configure the database as also shown in the screenshot:

Step8: Set the DataBase permissions

You have now created your database, but still need to configure its permissions. In order to do so, click on the Permissions option and under the Members section, add a user named nomie:

Step9: Create the user

In Step8 we made a user named ‘nomie’ member of our database, but that specific user is not yet defined in our environment. In this last step we will define the user. In order to do so, please use the UI to navigate to the _users database, and click on Create Document. A basic JSON string is populated for you, with a random _id value. Overwrite this string with a variation of the object below, and click Create Document.

{
  "_id": "org.couchdb.user:nomie",
  "name": "nomie",
  "type": "user",
  "roles": [],
  "password": "yoursecretpassword"
}

Step10: Enabling secure (ssl) connectivity

Most modern browsers will not allow to connect from a secure connection (https) to a non secure connection (http). The current setup of CouchDB as we established in the first 10 steps delivers us a non secure (http) setup. Luckily we have already prepared our container for the next step as we have enabled port 6984 (which will be needed for a secure connection) and we have created a volume mount for the certificates we need for the secure connection.

CouchDB supports TLS/SSL natively, without the use of a proxy server. HTTPS setup can be tricky, but the configuration in CouchDB was designed to be as easy as possible. All you need is two files; a certificate and a private key. If you have an official certificate from a certificate authority, both should be in your possession already. If you just want to try this out and don’t want to go through the hassle of obtaining an official certificate, you can create a self-signed certificate. Everything will work the same, but clients will get a warning about an insecure certificate. In the below instructions we will assume you do not have the certificates yet.

Step10-1: create a self-signed certificate

We will create our self-signed certificates ‘inside’ your running CouchDB container. Once created, they will persist in the certificate volume we have mounted in one of the earlier steps above. This will ensure that when you have to restart/update/upgrade the container, your certificates will be available and you do not have to repeat these steps. Please move to the container section in your Docker Manager app on your Synology. Select the CouchDB container and click on the Details button:

You will be directed to the screen as per below screenshot. Where you should select terminal (at the top in blue) and thereafter push the Create button:

Now a new terminal screen will appear.

Within this screen, please -one by one- execute the below commands:

shell> mkdir /etc/couchdb/cert
shell> cd /etc/couchdb/cert
shell> openssl genrsa > privkey.pem
shell> openssl req -new -x509 -key privkey.pem -out couchdb.pem -days 1095
shell> chmod 600 privkey.pem couchdb.pem
shell> chown couchdb privkey.pem couchdb.pem

Please see my example below, when requested in the terminal, please provide the details as per your situation:

Now you can close this window.

Step10-2: configure CouchDB

The next step is to ensure that CouchDB is enabled to use a secure connection by using the created certificates. Please switch to your CouchDB instance in your browser via <your server ip>:5984/_utils

While in the UI, choose the configuration screen, click on Main config.

The next action is to click on the Add Option button and fill in the below details and click on the Create button:

[ssl]
enable = true

Please repeat the above steps 2 more times with the following details:

[ssl]
cert_file = /etc/couchdb/cert/couchdb.pem
key_file = /etc/couchdb/cert/privkey.pem

Once done, you can validate if all was processed accordingly by scrolling through the Main config settings. You should find the following items as just created:

Step10-3: restart your container

In order to make the changes effective, you should restart your container. Please go back to your Synology Docker Manager app, find your CouchDB container and toggle the ‘active’ switch:

You should be able to connect to it using HTTPS on port 6984

Step10-4: validate if all is working

Now it is time to see if we can reach our CouchDB instance in a secure way, using https. Go to https://<ip to your server>:6984

When everything goes well, you will see a warning… Oh no! What happened?! Remember, clients will notify their users that your certificate is self signed!

Please be aware that the message might look different in each browser. The above example is from a Firefox screenshot. Click on the Advanced… button and you will be directed to the next screen:

Click on the Accept the Risk and Continue button. There you go, you will be directed to a screen which looks familiar from one of the first steps in this instruction, but now via a secure connection:

The final step we need to take is to make sure Nomie is configured to connect to our database. Let’s quickly configure Nomie to sync with your newly created database.

Step11: Setting up Nomie

REMARK: if you use Nomie on your Iphone/Ipad as an app (so not in a browser), please first follow the steps which I have added at the bottom of this instruction page (=> Iphone Users additional steps)

Please open your Nomie application and go to the More tab. When in the tab, go to the CouchDB settings. If you have not yet configured Nomie to use CouchDB, please make sure the CouchDB option is enabled by clicking on the Local Storage Only setting. You will be directed to below view, make sure to select he CouchDB option:

Once the CouchDB option is enabled you will be provided with a couple of fields to configure Nomie. Make sure to configure the settings as per below screenshot and in line with the configuration of your database through step1 to step9:

Note how we connect via our secure connection. Please make sure to use the password you have created for the nomie user in step 9. Sometimes you might get an error message that the connection was not successful. In most cases I was able to solve that by following step10-4 first in the browser you are launching Nomie from….
(and if you are using Nomie in an Iphone/Ipad app, please first follow the steps at the bottom of these instructions)
If everything went well, you will be shown the following screen:

You can click on the OK button after which this popup message will disappear and you will be back to the previous screen…. almost the same, but with 1 important difference. The switch behind the CouchDB option is now active and nicely colored green 🎉

We are done! I hope you made it so far following above instructions, because that means you have your own CouchDB database running on your Synology NAS, correctly configured and securely connecting to your Nomie installations on the devices you have installed Nomie on.

You are now in Sync 🛟…..have fun with it!

Some afterburners

Please be aware that your CouchDB database is only accessible within your own network (wifi). So a connection via a mobile service provider will fail.

You can obtain a domain or use the Synology DDNS functionality to enable connection from outside your own network/lan. This requires some more complex network setup on your Synology or your router. That can be a nice set of additional instructions I can add in the future.😃

✋Iphone/Ipad Users additional steps

A self signed certificate is an easy way to secure your connection…unfortunately, if you have installed Nomie on your Iphone/Ipad as an application (so not running within a browser) you connection will fail. IOS does not trust self signed certificates, unless you take some additional actions.
You are lucky, I have documented these steps below.👌

Iphone Setup Step1: locate your certificate file

In order to have your Iphone trust your self signed certificate, you need to load it within your settings as a trusted profile/certificate.
The first step is to get your certificate file downloaded on your Iphone. There are several ways to achieve this:

• send the file via an email to your email address. Open the email on your Iphone and download the file
• download the file in your Icloud and open the file in your Icloud from your Iphone
• send the file via airdrop to your Iphone

I will provide you with a fourth alternative method which will also work.
First of all, make sure you remember where your certificate files are stored on your Synology Nas. We have defined that in Step3 of these instructions, where we mounted the volumes to your docker container. In my example I have mounted the certificate folder in the container to the /docker/couchdb/cert folder on my NAS. When you open that folder on your NAS with the Synology file explorer you will indeed find 2 certificate files:

In the next steps below, we will use the couchdb.pem file.

Iphone Setup Step1: download your certificate file

Now move over to your Iphone, go to your browser and browse to the address of your Synology NAS. You will be asked to login, please do so.
Initially you will be directed to the mobile UI of your Synology NAS as per below screenshot. Now please click on the settings icon:

You will see the following dialogue, please select Desktop Mode:

You will be directed to the desktop User interface, which will look very small on your screen 🥴. Remember you can always ‘zoom’ in via your normal gestures on your phone. On your screen you will see the file explorer icon, please click on this icon:

You will be directed to the file explorer on your NAS. Please navigate to the folder where your certificate files are located (see Iphone Setup Step1 above):

Now select the couchdb.pem file, click on the Action Button and choose ‘download’:

The following Popup screen will appear on your Iphone, please select Allow.
By the way, if you have chosen to download the certificate file via an alternative way as listed above, you will get the same Popup screen and you can follow the instructions further below for the additional setup steps.

When applicable you will be asked on which device you would like to install the profile. Pick your Iphone:

You will get a confirmation that the profile is download, you can now logout of the Synology NAS web GUI:

Iphone Setup Step3: Install the profile/certificate

The next step is to open the settings app on your Iphone and you will immediately notice below option popping up. Please click on it:

You will be directed to the following screen where you have the option to install your profile. Mine is called rdl, your is probably called different, depending on the name you gave it when you created the certificate. Please click on the install button:

You will be requested for your Iphone password and directed to the following screen where you should click on the install button:

Your profile is now installed, click on the Done button:

Next step is (again in your settings app) to navigate to: settings => General => About
At the bottom of the screen you will find the Certificate Trust Settings option. Please click on that option:

You will be directed to the next screen where you will also see your newly imported certificate (in my case ‘rdl’):

Now you can toggle the switch to activate your certificate. You will be requested to confirm, once confirmed…you are done.

You should now be able to connect to your CouchDB database from Nomie installed on your Iphone/Ipad as explained in Step11 above.

Have fun with it👍