Apache CouchDB is an open-source document-oriented NoSQL database, implemented in Erlang.

CouchDB uses multiple formats and protocols to store, transfer, and process its data, it uses JSON to store data, JavaScript as its query language using MapReduce, and HTTP for an API.


For this guide you should be familiar with the basic concepts of


All relevant legal information can be found here


We’re using CouchDB in the stable version 3:

[isabell@stardust ~]$ uberspace tools version use couchdb 3
Selected couchdb version 3
The new configuration is adapted immediately. Minor updates will be applied automatically.
[isabell@stardust ~]$


Uberspace provides the latest binaries, see CouchDB on how to interact with them. No extra installation required!


Environment setup

Next we need to create directories for our configuration and application data:

[isabell@stardust ~]$ mkdir -p ~/etc/couchdb
[isabell@stardust ~]$ mkdir -p ~/opt/couchdb

Application config

Create ~/etc/couchdb/local.ini with the following content:


Replace <username> with your username!

database_dir = /home/<username>/opt/couchdb/data
view_index_dir = /home/<username>/opt/couchdb/index

port = 5984
bind_address =

admin = SecureAdminPassword


Make sure to set your own super secure admin password!

Setup daemon

Create ~/etc/services.d/couchdb.ini with the following content:

command=couchdb -couch_ini /opt/couchdb/etc/default.ini %(ENV_HOME)s/etc/couchdb/local.ini

After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$

If it’s not in state RUNNING, check your configuration.

Finishing installation

If everything looks fine, you should now be able to query CouchDB using localhost:5984:

[isabell@stardust ~]$ curl http://localhost:5984
{"couchdb":"Welcome","version":"3.1.1","git_sha":"CENSORED","uuid":"CENSORED","features":["access-ready","partitioned","pluggable-storage-engines","reshard","scheduler"],"vendor":{"name":"The Apache Software Foundation"}}

Create database

Let’s create a test database called testdb:

[isabell@stardust ~]$ curl -X PUT http://admin:SecureAdminPassword@localhost:5984/testdb

Best practices


Change all default passwords. Especially the admin password within the config file ~/etc/couchdb/local.ini. Don’t get hacked!

Web backend


This exposes CouchDB to the global internet and allows anyone to query your CouchDB database. Not recommended without authentication!


couchdb is running on port 5984. Also make sure to set bind_address = in ~/etc/couchdb/local.ini. Additionally, the --remove-prefix parameter is needed if you want to run CouchDB under a sub URI like /couchdb instead of the root URI /.

To make the application accessible from the outside, configure a web backend:

[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

Written by: Lukas Wolfsteiner <>