CouchDB

#self-hosting #database 

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.

Note

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

License

All relevant legal information can be found here

Prerequisites

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 ~]$

Installation

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

Configuration

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:

Warning

Replace <username> with your username!

[couchdb]
single_node=true
database_dir = /home/<username>/opt/couchdb/data
view_index_dir = /home/<username>/opt/couchdb/index

[chttpd]
port = 5984
bind_address = 127.0.0.1

[admins]
admin = SecureAdminPassword

Note

Make sure to set your own super secure admin password!

Setup daemon

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

[program:couchdb]
command=couchdb -couch_ini /opt/couchdb/etc/default.ini %(ENV_HOME)s/etc/couchdb/local.ini
autostart=yes
autorestart=yes

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
{"ok":true}

Best practices

Security

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

Web backend

Warning

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

Note

couchdb is running on port 5984. Also make sure to set bind_address = 0.0.0.0 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 <lukas@wolfsteiner.media>