Skip to content

Latest commit

 

History

History
151 lines (93 loc) · 3.61 KB

guide_couchdb.rst

File metadata and controls

151 lines (93 loc) · 3.61 KB
.. author:: Lukas Wolfsteiner <[email protected]>

.. tag:: self-hosting
.. tag:: database
.. tag:: Erlang

About

CouchDB

.. tag_list::

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 :manual:`CouchDB <database-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 :manual:`CouchDB <database-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

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.

Tested with CouchDB 3.3.3 and Uberspace 7.15.4.0

.. author_list::