CouchDB¶
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.
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
.
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 ~]$
Tested with CouchDB 3.3.3 and Uberspace 7.15.4.0
Written by: Lukas Wolfsteiner <lukas@wolfsteiner.media>