How to Setup CouchDB v. 2.1.1 on your Linux Root Server
Enabling the Apache CouchDB package repository
CentOS: Place the following text into
[bintray--apache-couchdb-rpm] name=bintray--apache-couchdb-rpm baseurl=http://apache.bintray.com/couchdb-rpm/el$releasever/$basearch/ gpgcheck=0 repo_gpgcheck=0 enabled=1
Ubuntu: Run the command:
$ echo "deb https://apache.bintray.com/couchdb-deb xenial main" \ | sudo tee -a /etc/apt/sources.list
Installing the Apache CouchDB packages
RedHat/CentOS: Run the command:
$ sudo yum -y install epel-release && yum install couchdb
Be sure to complete the First-time Setup steps for a single node installation.
Debian/Ubuntu: First, install the repository key:
$ curl -L https://couchdb.apache.org/repo/bintray-pubkey.asc \ | sudo apt-key add -
Then update the repository cache and install the package:
$ sudo apt-get update && sudo apt-get install couchdb
Debian/Ubuntu installs from binaries will be pre-configured for single node or clustered installations.
CouchDB 2.0 can be used in a single-node or clustered configuration. Below are the first-time setup steps required for each of these configurations.
Single Node Setup
A single node CouchDB 2.0 installation is what most users will be using. It is roughly equivalent to the CouchDB 1.x-series. Note that a single-node setup obviously doesn’t take any advantage of the new scaling and fault-tolerance features in CouchDB 2.0.
After installation and initial startup, visit Fauxton at
http://YOURVPSIP:5984/_utils. You will be asked to set up CouchDB as a single-node instance or set up a cluster. Click on “Single-Node-Setup”, you will get asked for an admin username and password. Choose them well and remember them. The wizard then configures your admin username and password and creates the three system databases
_global_changes for you.
Follow the screen instructions to finish your CouchDB Setup
Enter your VPS IP or 0.0.0.0
Enter admin password and remember it
Repeat the password.
After CouchDB is installed open your browser and navigate to http://YOURVPSIP:5984/_utils/
Login with same login details you have created in setup
Go to Setup then select Single Node
Enter admin with same pass from earlier bind to 0.0.0.0
Click on Configure Node.
Relax! CouchDB is installed and running.
Running as a Daemon
CouchDB no longer ships with any daemonization scripts.
The CouchDB team recommends runit to run CouchDB persistently and reliably. According to official site:
runit is a cross-platform Unix init scheme with service supervision, a replacement for sysvinit, and other init schemes. It runs on GNU/Linux, *BSD, MacOSX, Solaris, and can easily be adapted to other Unix operating systems.
Let’s consider configuring runit on Ubuntu 16.04. The following steps should be considered only as an example. Details will vary by operating system and distribution. Check your system’s package management tools for specifics.
sudo apt-get install runit
Create a directory where logs will be written:
sudo mkdir /var/log/couchdb sudo chown couchdb:couchdb /var/log/couchdb
Create directories that will contain runit configuration for CouchDB:
sudo mkdir /etc/sv/couchdb sudo mkdir /etc/sv/couchdb/log
Create /etc/sv/couchdb/log/run script:
#!/bin/sh exec svlogd -tt /var/log/couchdb
Basically it determines where and how exactly logs will be written. See
man svlogd for more details.
#!/bin/sh export HOME=/home/couchdb exec 2>&1 exec chpst -u couchdb /home/couchdb/bin/couchdb
This script determines how exactly CouchDB will be launched. Feel free to add any additional arguments and environment variables here if necessary.
Make scripts executable:
sudo chmod u+x /etc/sv/couchdb/log/run sudo chmod u+x /etc/sv/couchdb/run
sudo ln -s /etc/sv/couchdb/ /etc/service/couchdb
In a few seconds runit will discover a new symlink and start CouchDB. You can control CouchDB service like this:
sudo sv status couchdb sudo sv stop couchdb sudo sv start couchdb
Naturally now CouchDB will start automatically shortly after system starts.
You can also configure systemd, launchd or SysV-init daemons to launch CouchDB and keep it running using standard configuration files. Consult your system documentation for more information.