CouchDB 2.0 on Raspberry Pi

The Apache Software Foundation has released CouchDB version 2.0.  CouchDB 2.0, is a “distributed” version of CouchDB, a mature NoSQL, document-oriented data-store that is accessable via a RESTful JSON API. Developers can take advantage of CouchDB’s offline capability and reliable data sync for web, mobile and IoT apps at (any) scale.

[NOTE: September 2017 — CouchDB 2.1 and Raspbian Stretch have been released.  Check out updated instructions in this blog post]

Current Raspbian (November 2016) can “apt-get install” version 1.4 and I have previously written about getting CouchDB 1.6 running on the R-Pi.  I have now installed version 2.0.0 on an R-Pi 3 and am sharing the process.  It is pretty straightforward to get CouchDB 2.0 running on the R-Pi. It takes a combination of the R-Pi specific 1.6 install and the “generic linux” 2.0 install to get things running.


First, make sure your R-Pi is running the latest Raspbian:

sudo apt-get update
sudo apt-get upgrade

On my R-Pi 3, you can see Raspbian and kernel versions:

pi@PiCam-3:~ $ uname -a
Linux PiCam-3 4.4.38-v7+ #938 SMP Thu Dec 15 15:22:21 GMT 2016 armv7l GNU/Linux

pi@PiCam-3:~ $ cat /etc/os-release
PRETTY_NAME="Raspbian GNU/Linux 8 (jessie)"
NAME="Raspbian GNU/Linux"
VERSION="8 (jessie)"


You should add a CouchDB specific repository and then “apt-get” dependencies:

sudo apt-key add erlang_solutions.asc
sudo apt-get update
sudo apt-get install -y erlang-nox erlang-dev erlang-reltool
sudo apt-get install -y build-essential
sudo apt-get install -y libmozjs185-1.0 libmozjs185-dev
sudo apt-get install -y libcurl4-openssl-dev libicu-dev


Setup the couchdb user:

sudo useradd -d /home/couchdb couchdb
sudo mkdir /home/couchdb
sudo chown couchdb:couchdb /home/couchdb

Get URL to download source for couchdb.  Use a browser to navigate to:  Under “Download CouchDB 2.0.x”, click on “Source” button.  Copy the suggested mirror download URL.  In my case it was:  On the R-Pi, download and unzip source:

tar zxvf apache-couchdb-2.0.0.tar.gz
cd apache-couchdb-2.0.0/
make release


after  a bit, you should see:

... done

    You can now copy the rel/couchdb directory anywhere on your system.
    Start CouchDB with ./bin/couchdb from within that directory.


For convience, I chose to copy the couchdb  directory with executables and configuration files to the couchdb home directory.  Make sure you are in the couchdb directory under the release (rel) directory.  Copy the contents of the …/rel/couchdb to the couchdb home directory.


cd ./rel/couchdb
sudo cp -Rp * /home/couchdb
sudo chown -R couchdb:couchdb /home/couchdb


I want to access CouchDB from other machines and run fauxton in a browser from my Mac.  Fauxton is a web-based interface for CouchDB. Change the local configuration file in “/home/couchdb/etc”.  Either use “vi” or “nano” or your favorite editor to edit “local.ini”


cd /home/couchdb/etc
sudo vi local.ini


Under the chttp section, change this line to enable remote access from any IP address.


#bind_address =


bind_address =


Save and exit the editor.

You should now be able to run CouchDB.  It needs to be run as user: couchdb.

sudo -i -u couchdb /home/couchdb/bin/couchdb


This will display some diagnostic messages and the CouchDB motto: “Relax” 😉

You may see some “shard errors” until you actually write to a DB.  Easiest thing to do is to setup an admin user via Fauxton utility.  Either from a remote machine – I use my Mac – or a local browser on the R-Pi, you can now launch Fauxton.  You need to know your R-Pi’s IP address if running remotely.  My particular R-Pi has the address:  In a browser you can put in the URL:


You should click on the “Verify” button in the left navigation panel and then click “Verify Installation” button at the top of the page.  If everything went well, you should see:





19 thoughts on “CouchDB 2.0 on Raspberry Pi”

  1. Hey Andy,

    I’m getting the following error when i enter the command ‘make release’:
    /usr/bin/env: escript: No such file or directory
    Makefile:67: recipe for target ‘couch’ failed
    make: *** [couch] Error 127

    Any ideas?

    1. Hi Jaime, I would confirm that you have done ALL the “apt-gets” that I show. Also make sure you are in the correct directory ( ~/apache-couchdb-2.0.0) when you do the “./configure” and “make release”. You could also try a plain “make” to see if you get errors. ALSO, I had a typo for the “apt-get erlang-reltool” as pointed out in another comment. Please check the updated instructions. LMK, Andy

  2. That’s excellent, the only issue I had is that erlang-reltools, is actually erlang-reltool without the “s”.

    Quick question, what would be the best way to make it so that couchdb starts on startup? I now have the couchdb set up as a headless server.

    Kind regards

    1. Thanks for the feedback. I have updated the instructions to fix the “apt-get erlang-reltool”, dropping the extraneous “s”. For auto-start of CouchDB, you might move couchdb directory to something like /usr/bin and create a service file for autorun. See the “service” command docs.

  3. Ok, I actually got couchdb2.0 to run as a service and automatically start at boot, so thought I would add what I had done here as it seemed like an appropriate place. So basically, I followed this tutorial to the letter up until the source code is compiled. When that is finished and you get the message “done”, instead of copying couchdb to the home folder, copy to /usr/bin/ as follows:
    cd ./rel/couchdb

    Create couchdb directory:
    sudo mkdir /usr/bin/couchdb

    Then copy to that folder:
    sudo cp -Rp * /usr/bin/couchdb
    sudo chown -R couchdb:couchdb /home/couchdb

    Carry on through tutorial the same, but remember where it now is in the user binaries folder. This also means that starting couchdb needs to be done like this:
    sudo -i -u /usr/bin/couchdb/bin/couchdb

    though I didn’t need the flags -i and -u to log in, though currently I am still running admin party to get this going.

    So now open a text editor and enter the following exactly:
    Description=Couchdb service

    ExecStart=/usr/bin/couchdb/bin/couchdb -o /dev/stdout -e /dev/stderr


    and put it here:

    Now the service needs to be added and loaded and whatnot. Just enter the following into terminal:
    systemctl daemon-reload
    systemctl start couchdb.service
    systemctl enable couchdb.service

    At this point a reboot is worth doing and then when it boots up, you should find that you can go straight to a browser and log into futon. But just as a sanity check typing the following into terminal will let you know if couchdb has indeed started:
    service couchdb status

    So this has worked for me, bear in mind that as you are running everything from /usr/bin, you will need to sudo everything or just do everything as root.

  4. hey guys,
    I followed the instructions of that tutorial and am able to run the db in single node mode, but I’d like to run a cluster on several RaspPi. I don’t get it running. Everything works fine until I am doing the Setup. Adding same credentials on every Pi, editing bind_address to, setup cluster, add IP of other nodes… and create cluster. But when I have a look at _membership the other nodes are only shown at cluster_nodes, but not at all_nodes. When I add a db at one node it is not synchronized to the others.

    I know its off-topic, but I really could use some help.

    thanks in advance

  5. Hi Andy,
    I’ve been running couchdB 2.0 on a pi 3 for a short while and am finding that the erlang runtime beam.smp seems to use a lot of cpu even when doing very little. At startup it can be p to 300% (e,g, 3 cpus at 100%) and even at “rest” its using about 65% to 200%.
    Have you any ideas of how to get it to run more efficiently ? any tweaks to the runtime for instance.

    Cheers, Geoff

  6. Hi Andy,

    thanks for the nice tutorial.

    Still a little typo: “sudu chown couchdb:couchdb /home/couchdb” needs to be sudo of course.



  7. When I follow this to the letter the ‘make release’ fails – it appears there’s an erlang problem. The last few lines that show the failure are below. Any ideas how to resolve this?

    Installing CouchDB into rel/couchdb/ …
    ==> rel (generate)
    ERROR: Unable to generate spec: read file info /usr/lib/erlang/man/man3/cerff.3.gz failed
    ERROR: Unexpected error: rebar_abort
    ERROR: generate failed while processing /home/pi/apache-couchdb-2.0.0/rel: rebar_abort
    Makefile:234: recipe for target ‘release’ failed
    make: *** [release] Error 1

    1. Hi Che, I followed my instructions and “copied and pasted” all commands — and had NO problems. I started with a new image of Raspbian Jessie with Pixel, dated: 2017-04-10 on a Raspberry Pi 3. I did the usual update/ugrade. As user: Pi, I followed my instructions and, as I said, copied and pasted all commands. Please ensure you obtained a “fresh” download URL from Check all owners & permissions 😉 You might email a full transcript of your session if you are still having issues.

      Here is the terminal history from my install:
      20 sudo apt-get update
      21 sudo apt-get upgrade
      22 sudo apt-get dist-upgrade
      23 clear
      24 uname -a
      25 cat /etc/os-release
      26 cat /proc/version
      27 cd
      28 wget
      29 sudo apt-key add erlang_solutions.asc
      30 sudo apt-get update
      31 sudo apt-get install -y erlang-nox erlang-dev erlang-reltool
      32 sudo apt-get install -y build-essential
      33 sudo apt-get install -y libmozjs185-1.0 libmozjs185-dev
      34 sudo apt-get install -y libcurl4-openssl-dev libicu-dev
      35 sudo useradd -d /home/couchdb couchdb
      36 sudo mkdir /home/couchdb
      37 sudo chown couchdb:couchdb /home/couchdb
      38 [ -- TYPO :( ]
      39 [ -- TYPO :( ]
      40 [ -- TYPO :( ]
      41 wget
      42 tar zxvf apache-couchdb-2.0.0.tar.gz
      43 cd apache-couchdb-2.0.0/
      44 ./configure
      45 make release
      46 cd ./rel/couchdb/
      47 pwd
      48 sudo cp -Rp * /home/couchdb
      49 sudo chown -R couchdb:couchdb /home/couchdb
      50 cd /home/couchdb/etc
      51 pwd
      52 sudo vi local.ini
      53 sudo -i -u couchdb /home/couchdb/bin/couchdb

  8. Pingback: CouchDB 2.1 on Raspberry Pi (Raspbian Stretch)

  9. Harshal Gosavi

    I am not able to run couchdb , i followed all steps. then

    [notice] 2019-05-27T04:51:11.333245Z couchdb@ ——– chttpd_auth_cache changes listener died database_does_not_exist at mem3_shards:load_shards_from_db/6(line:395) <= mem3_shards:load_shards_from_disk/1(line:370) <= mem3_shards:load_shards_from_disk/2(line:399) <= mem3_shards:for_docid/3(line:86) <= fabric_doc_open:go/3(line:39) <= chttpd_auth_cache:ensure_auth_ddoc_exists/2(line:195) <= chttpd_auth_cache:listen_for_changes/1(line:142)
    [error] 2019-05-27T04:51:11.333860Z couchdb@ emulator ——– Error in process on node ‘couchdb@’ with exit value:

  10. Pingback: UPDATE: CouchDB 2.3 on Raspberry Pi 4 & 3 –

  11. Here is the procedure to make it run on armbian (I ran on an orange pi zero)


    dpkg -i –force-depends libffi6_3.2.1-8_armhf.deb
    dpkg -i –force-depends libffi-dev_3.2.1-8_armhf.deb
    dpkg -i –force-depends libnspr4_4.18-1ubuntu1_armhf.deb
    dpkg -i –force-depends libnspr4-dev_4.18-1ubuntu1_armhf.deb
    dpkg -i –force-depends libmozjs185-1.0_1.8.5-1.0.0+dfsg-7_armhf.deb
    dpkg -i –force-depends libmozjs185-dev_1.8.5-1.0.0+dfsg-7_armhf.deb

    sudo apt-key add erlang_solutions.asc
    sudo apt-get update
    sudo apt-get install -y erlang-nox erlang-dev erlang-reltool
    sudo apt-get –no-install-recommends -y install build-essential pkg-config erlang libicu-dev libcurl4-openssl-dev
    sudo useradd -d /home/couchdb couchdb
    sudo mkdir /home/couchdb
    sudo chown couchdb:couchdb /home/couchdb
    tar zxvf apache-couchdb-2.3.1.tar.gz
    cd apache-couchdb-2.3.1/
    make release
    cd ./rel/couchdb/
    sudo cp -Rp * /home/couchdb
    sudo chown -R couchdb:couchdb /home/couchdb
    cd /home/couchdb/etc

    sed -i ‘s/;bind_address = =’ local.ini
    sed -i ‘s/;port = 5984/port = 5984/g’ local.ini
    sudo -i -u couchdb /home/couchdb/bin/couchdb

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top