Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
How to get started with CouchDB through Docker on OpenStack

Setting up a CouchDB with Docker on OpenStack

I will be using the OpenStack provider NREC, which is available for free for all students at the University of Oslo and University of Bergen (among others).

Setting up an instance in OpenStack

Create a Linux Virtual machine with SSH access (see NREC-tutorial), and test that you can log in:

$ ssh centos@<your instance public ip>
Last login: Tue Mar 24 06:33:00 2020 from <your machine>
[centos@<your instance name> ~]$ 

Install Docker on instance

Follow the instructions at

Install CouchDB container

Use the official CouchDB image with tag latest and name my-couchdb (see documentation in master-branch for latest info):

[centos@<your instance name> ~]$ docker run -d --name my-couchdb -e COUCHDB_USER=<choose an admin username> -e COUCHDB_PASSWORD=<choose an admin password> couchdb:latest

And expose standard port to outside world:

[centos@<your instance name> ~]$ docker run -p 5984:5984 -d couchdb

# use IP if you want to expose it to all external machines (you will then have to open ports, explained later):
[centos@<your instance name> ~]$ docker run -p -d couchdb

Confirm that container is running ($ docker ps):

CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                          NAMES
5a54bd538baf        couchdb             "tini -- /docker-ent…"   2 minutes ago       Up 2 minutes        4369/tcp, 5984/tcp, 9100/tcp   my-couchdb

You can now test that your CouchDB is running successfully. First find the IP address of the container:

[centos@<your instance name> ~]$ docker inspect my-couchdb | grep IPAddress
            "SecondaryIPAddresses": null,
            "IPAddress": "",
                    "IPAddress": "",

The IP of the container is, from the Docker host you can now try getting the welcome message from CouchDB:

[centos@<your instance name> ~]$ curl
{"couchdb":"Welcome","version":"3.0.0","git_sha":"06a17db8e","uuid":"3b57fbf49b50d12173109a3a62d2bd1f","features":["access-ready","partitioned","pluggable-storage-engines","reshard","scheduler"],"vendor":{"name":"The Apache Software Foundation"}}

Open ports on your instance for CouchDB

If you started your CouchDB container with IP, you will have to open ports in OpenStack to complete the setup for all external machines to connect to the DB.

CouchDB uses port 5984 for standard communication, so you will need to open this port in OpenStack to be able to access the CouchDB container from other machines. Create a new security group that you name CouchDB, and add port 5984 for ingress communication:

Open port 5984 in OpenStack for CouchDB

Add this new security group to your instance which is running the CouchDB container (the same way you added the SSH security group earlier if you followed the NREC documentation).

You will now be able to access your CouchDB instance from anywhere, it will be running on <your instance public ip>:5985, you can try:

<any host>$ curl <your instance public ip>:5985

... to get the welcome message.

Open an SSH tunnel to your instance to connect from CouchDB from other host

If you don't want to expose your DB to all of internet, but still be able to communicate with CouchDB from outside the Docker host that is hosting the CouchDB container, you will need to somehow bind the internal IP address of the container to the IP of the Docker host. One way to do this is to create an SSH tunnel that will map localhost on an external machine to the Docker container IP on the Docker host:

<external host>$ ssh -f -L localhost:15984: centos@<your instance public ip> -N

# or use autossh for a more robust connection:
<external host>$ autossh -M 0 -o "ServerAliveInterval 30" -o "ServerAliveCountMax 3" -L localhost:15985: centos@<your instance public ip>

(see Everything CLI guide for more config options)

This will make it possible to open the Fauxton dashboard on localhost of the external machine, try this in the browser of the external machine: http://localhost:15985/_utils/ or cURL on the external machine:

<external host>$ curl localhost:15985
{"couchdb":"Welcome","version":"3.0.0","git_sha":"06a17db8e","uuid":"3b57fbf49b50d12173109a3a62d2bd1f","features":["access-ready","partitioned","pluggable-storage-engines","reshard","scheduler"],"vendor":{"name":"The Apache Software Foundation"}}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment