HOWTO Install CouchDB 3.1.1 on Opalstack

This is a WIP.

At this time, the latest stable version of CouchDB is 3.1.1. The CouchDB Unix Installation doc assumes the installer can use sudo, which is not the case for regular Opalstack users, so the process will be slightly different on Opalstack.

Fortunately, the folks at Webfaction wrote a tutorial on installing CouchDB 1.1.1 on Webfaction. This tutorial borrows liberally from that one.

First, we need to install some dependencies. Although Opalstack has Erlang and OTP installed on its servers, the version (OTP 23) is incompatible with CouchDB 3.1.1. OTP 22.3 is the latest OTP version that will work for us.

Also, we could install firefox 60.9.0, but it requires a newer version of gcc than Opalstack has installed, so we'll use spidermonkey 1.8.5.

You may want to put the following in a file called buildcouch1of2.sh:

export PATH="$HOME/bin:$PATH"
mkdir -p $HOME/src
mkdir -p $HOME/opt

# erlang & otp 22.3 - source: https://erlang.org/download/otp_src_22.3.tar.gz
cd $HOME/src
wget 'https://erlang.org/download/otp_src_22.3.tar.gz'
tar -xzf otp_src_22.3.tar.gz
cd otp_src_22.3
./configure --prefix=$HOME
make
make install

# spidermonkey 1.8.5 - source: https://ftp.mozilla.org/pub/mozilla.org/js/js185-1.0.0.tar.gz
cd $HOME/src
wget 'https://ftp.mozilla.org/pub/mozilla.org/js/js185-1.0.0.tar.gz'
tar -xzf js185-1.0.0.tar.gz
cd js-1.8.5/js/src
./configure --prefix=$HOME
make
make install

# couchdb 3.1.1 - source: https://downloads.apache.org/couchdb/source/3.1.1/apache-couchdb-3.1.1.tar.gz
cd $HOME/src
wget 'https://downloads.apache.org/couchdb/source/3.1.1/apache-couchdb-3.1.1.tar.gz'
tar -xzf apache-couchdb-3.1.1.tar.gz
cd apache-couchdb-3.1.1

echo Step 1 of 2 complete
echo Edit line 111 of ~/src/apache-couchdb-3.1.1/src/couch/rebar.config.script before running step 2 of 2

Run the preceding commands. They will install OTP 22.3 and Spidermonkey 1.8.5 and download and unzip the CouchDB 3.1.1 source. Unfortunately, I was not able to get CouchDB to find Spidermonkey via any of multiple combinations of command line options, even after asking in #couchdb on freenode and couchdb.slack.com. I tried variations using the -ERL_CFLAGS and -ERL_LDFLAGS options without any luck.

The only way I was able to get it to work was to manually modify a configuration file, first. Fortunately, the modification is pretty simple:

# you can use nano or whichever text editor you prefer here. I used vim.
vi ~/src/apache-couchdb-3.1.1/src/couch/rebar.config.script
# change line 111 of this file from:
# -L/usr/local/lib -lmozjs185 -lm
# to:
# -L$HOME/lib -lmozjs185 -lm
# save the file and exit the text editor

This line tells CouchDB to look for Spidermonkey where we installed it in the first step.

Now we can proceed to install CouchDB. You may want to put the following commands into a file called buildcouch2of2.sh:

cd $HOME/src/apache-couchdb-3.1.1
export LD_LIBRARY_PATH=$HOME/lib:$LD_LIBRARY_PATH
./configure
make
make release ERL_CFLAGS="-I $HOME/include/js -I $HOME/lib/erlang"
cp -r ./rel/couchdb $HOME/opt/

Run these commands. Congratulations! You've just built and installed CouchDB 3.1.1 and its dependencies. CouchDB now lives at ~/opt/couchdb.

In order to actually use couchdb, you'll need to create one or more admin users and complete some additional configuration steps. Admin users can be specified in ~/opt/couchdb/etc/local.ini - scroll to the last line and change it to admin = yourSecurePassword (don't forget to remove the semicolon prefixing this line, and you should actually use a secure password in place of 'yourSecurePassword' above).

You should set up a 'Proxy Port' application in Opalstack for couchdb. Set the port in the [chttpd] section of ~/opt/couchdb/etc/default.ini to the port assigned to this application.

You should now be able to start couchdb by executing the following command: ~/opt/couchdb/bin/couchdb. Assuming you want a single node setup, rather than a cluster, you can execute the following three commands to create the initial system databases. You'll need to have couch running in order to do this, so you may want to be in a tmux or screen session, and you should replace 'YOURPORT' with the port assigned to your Proxy Port application):

# you'll need to enter the password you assigned to your admin user after each of these commands
curl -u admin -X PUT http://127.0.0.1:YOURPORT/_users
curl -u admin -X PUT http://127.0.0.1:YOURPORT/_replicator
curl -u admin -X PUT http://127.0.0.1:YOURPORT/_global_changes

Now, assuming couch is running, and you have set up a site route pointing to the Proxy Port application, you should be able to visit yourcouchdomain.com/_utils in your web browser and interact with CouchDB's 'fauxton' web GUI. Log in to fauxton with the admin user you created earlier, and you're good to go!

Things to add:

1. Instructions on running couch as a daemon and restarting it automatically if it crashes.

Useful links:

1. https://docs.couchdb.org/en/stable/install/unix.html#installation-from-source
2. https://docs.couchdb.org/en/stable/config/auth.html#config-admins
3. https://docs.couchdb.org/en/stable/setup/single-node.html
4. https://community.webfaction.com/questions/557/installing-couchdb