Differences between revisions 77 and 78
Revision 77 as of 2012-07-23 21:34:16
Size: 16696
Editor: 85-125-58-169
Comment: improved formatting
Revision 78 as of 2012-09-13 09:22:49
Size: 17731
Editor: ip-62-143-168-154
Comment: Added instructions to install spidermonkey from source
Deletions are marked like this. Additions are marked like this.
Line 237: Line 237:
==== Installing spidermonkey from source ====

This has been tested on Ubuntu 8.04 Server, with couchdb 1.2.0, from source.

{{{
install_spidermonkey_ ( ) {
    cd /tmp
    SPIDERMONKEY_VER="js185-1.0.0"
    SPIDERMONKEY_DIR="js-1.8.5"
    wget http://ftp.mozilla.org/pub/mozilla.org/js/${SPIDERMONKEY_VER}.tar.gz
    tar xvzf ${SPIDERMONKEY_VER}.tar.gz
    cd ${SPIDERMONKEY_DIR}/js/src
    make distclean 2> /dev/null # Just in case it is dirty
    ./configure
    make clean
    make
    sudo make install
    sudo ldconfig # Make sure the new libraries are reachable
}
install_spidermonkey_
}}}

And then, to build couch:
{{{
JS_LIB="/usr/local/lib/libmozjs185.so"
JS_INCLUDE="/usr/local/include/js"
./configure --with-js-lib=${JS_LIB} --with-js-include=${JS_INCLUDE}
}}}

Note: because the libtools in Ubuntu 8.04 are old, the macro LT_INIT is not supported.
To install CouchDB 1.2.0, some hacking must be performed on the configure script:

{{{
sed -i -e 's/^LT_INIT/#LT_INIT/' configure
}}}

Batteries Included

Newer versions of Ubuntu have CouchDB included in their respective software repositories. You can install CouchDB with the Ubuntu Software Center, or from the command line with the apt-get or aptitude utilities, which ever you prefer. However, to get the newest version of CouchDB you may have to install from source, or other package repositories that have newer pre-built CouchDB packages.

As of July 2012 modern package repositories only have CouchDB v1.0.1 and not v1.2.0, which is highly recommend over 1.0.1. To install 1.2.0 please see the build-couchdb section below.

sudo apt-get install couchdb

Troubleshooting

If the aptitude/apt-get installation gives an error message then couchdb might not have access to its pid file.

Fix:

sudo chown -R couchdb /var/run/couchdb

Need to rerun the setup script:

sudo dpkg --configure couchdb

Installing From Source

Easiest: using build-couchdb

There is a project called build-couchdb that automates and simplifies the building of CouchDB and it's dependencies. If you want to build the newest version of Couch with the least amount of pain this is probably your best bet. See the project Readme for instructions.

Advanced: manual building

This is a basic outline of the steps required to build CouchDB from source on Ubuntu. Like many things, there are multiple ways to achieve the same task. With that in mind, these steps may or may not be the best method for you (Example #2 below uses a javascript engine that is installed from source, which may be preffered for minimal Ubuntu systems).

  • Install first set of dependencies: sudo apt-get build-dep couchdb

  • Install second set of dependencies:
    • Ubuntu up to 9.10: sudo apt-get install libmozjs-dev libicu-dev libcurl4-gnutls-dev libtool

    • Ubuntu 10.04 and later when building CouchDB-1.1.x or less: sudo apt-get install xulrunner-1.9.2-dev libicu-dev libcurl4-gnutls-dev libtool erlang-eunit

      • Note that in 11.10 and later, xulrunner-1.9.2 includes the development files, so xulrunner-1.9.2-dev does not exist (install xulrunner-1.9.2 instead).
      • Then create /etc/ld.so.conf.d/xulrunner.conf.

    • Ubuntu 11.04 and later when building CouchDB-1.2 or greater: sudo apt-get install libmozjs-dev libicu-dev libcurl4-gnutls-dev libtool

  • Download CouchDB from http://couchdb.apache.org/downloads.html.

  • Untar (decompress) the source file: tar -zxvf apache-couchdb-*.*.*.tar.gz

  • Change into the expanded directory: cd apache-couchdb-*.*.*

  • Configure the build: ./configure

    • On Ubuntu 10.04 and later when building CouchDB-1.1.x or less:

      • ./configure --with-js-include=/usr/lib/xulrunner-devel-w.x.y.z/include --with-js-lib=/usr/lib/xulrunner-devel-w.x.y.z/lib

      • or
      • LDFLAGS="$(pkg-config mozilla-js --libs-only-L)" CFLAGS="$(pkg-config mozilla-js --cflags)" ./configure

    • On Ubuntu 11.04 and later when building CouchDB-1.2 or greater: No special flags should be necessary to build. Simply run ./configure

    • You may want to specify build options like the installation directory, etc. Please reference the examples below.
  • Build or Compile the source: make

  • Fix any error before moving to the next step.
  • Install your newly built CouchDB: sudo make install

  • Once the installation completes successfully, you will need to make sure that there is a CouchDB user, and that the CouchDB user owns the necessary files and directories.
  • Now you can run CouchDB manually by changing into the bin/ folder of the installation directory, and running: sudo -u couchdb ./couchdb

  • Once the server is running you can browse to http://localhost:5984/_utils. This should take you to the Futon Web GUI.

  • To be thorough, you should run the built in tests to ensure that CouchDB is working properly. To run the tests, click on the Test Suite link on the right hand side of the Futon Web GUI, then click on "Run All" to execute all of the built in tests. All of tests should run without error on Ubuntu.

  • Once CouchDB is working properly you can add CouchDB to your startup scripts if desired.

Note: If you installed all the dependencies of CouchDB from the Ubuntu Software Center, but not CouchDB itself, some of the dependencies may think they are not required and the update manager may suggest that they are removed. Should you remove these dependencies, CouchDB may fail to start, perhaps with an error such as:

{"init terminating in do_boot",{undef,[{crypto,start,[]},{erl_eval,do_apply,5},{init,start_it,1},{init,start_em,1}]}}

If this happens simply re-install the dependencies (possibly erlang-nox but it could vary).

Example 1

Please see below in links for complete instructions on how to install CouchDB.

sudo su
# Install dependencies required to build couchdb from source
apt-get build-dep couchdb
cd /opt
# download the latest release from http://couchdb.apache.org/downloads.html
# wget <url>
tar xvzf apache-couchdb-x.xx.x.tar.gz
cd apache-couchdb-x.xx.x

# Note: To install couchdb in the default location use --prefix= in the configure statement
# Note: To check what XULRunner version you have installed use xulrunner -v. CouchDB-1.1.x and older will not work with XULRunner 2.0+.

# Note: See Additional Notes (below) for additional, necessary information about using CouchDB-1.1.x and older on Ubuntu versions less than 11.04.
# Note: The extra --with-js-* options should not be used with CouchDB-1.2 (current trunk) and newer on Ubuntu 11.04+, where building against libmozjs185-dev is preferred.

./configure --prefix= --with-js-lib=/usr/lib/xulrunner-devel-1.9.x.y/lib --with-js-include=/usr/lib/xulrunner-devel-1.9.x.y/include

# Now you can compile and install couchdb
make && make install
# Add couchdb user account
useradd -d /var/lib/couchdb couchdb
chown -R couchdb: /var/lib/couchdb /var/log/couchdb

# next two steps fix problems where adding admin hangs or setting admins in local.ini hangs the start. Also fixes problems with reader_acl test.
chown -R root:couchdb /etc/couchdb
chmod 664 /etc/couchdb/*.ini
chmod 775 /etc/couchdb/*.d

# start couchdb
/etc/init.d/couchdb start
# Start couchdb on system start
update-rc.d couchdb defaults

# Verify couchdb is running
curl http://127.0.0.1:5984/
# {"couchdb":"Welcome","version":"1.0.1"}

Example 1 (Alternate)

The default installation of Ubuntu desktop 10.04 has a lot of version 0.10.0 CouchDB files and I did not want to worry about having them mixed with my source installed files.

This set of install instructions is modified from Example 1 and places all current CouchDB files within the /usr/local/ tree. Any other CouchDB related files outside of /usr/local/ can be deleted or ignored.

sudo su
# Install dependencies required to build couchdb from source
apt-get build-dep couchdb
cd /opt
# download the latest release from http://couchdb.apache.org/downloads.html
# wget <url>
tar xvzf apache-couchdb-x.xx.x.tar.gz
cd apache-couchdb-x.xx.x


# Note: To install couchdb in the default location use --prefix= in the configure statement
# Note: To check what XULRunner version you have installed use xulrunner -v. CouchDB-1.1.x and older will not work with XULRunner 2.0+.

# Note: See Additional Notes (below) for additional, necessary information about using CouchDB-1.1.x and older on Ubuntu versions less than 11.04.
# Note: The extra --with-js-* options should not be used with CouchDB-1.2 (current trunk) and newer on Ubuntu 11.04+, where building against libmozjs185-dev is preferred.

./configure --prefix=/usr/local/ --with-js-lib=/usr/lib/xulrunner-devel-1.9.x.y/lib --with-js-include=/usr/lib/xulrunner-devel-1.9.x.y/include

# Test installation, you will have problems regarding libmozjs and xulrunner here if you have not already corrected them
make check

# Now you can compile and install couchdb
make && make install

# vi /etc/passwd here and change home directory to /usr/local/var/lib/couchdb/, couchdb user is created during make && make install

# change file ownership from root to couchdb user and adjust permissions
chown -R couchdb: /usr/local/var/{lib,log,run}/couchdb /usr/local/etc/couchdb
chmod 0770 /usr/local/var/{lib,log,run}/couchdb/
chmod 664 /usr/local/etc/couchdb/*.ini
chmod 775 /usr/local/etc/couchdb/*.d

# start couchdb
cd /etc/init.d
ln -s /usr/local/etc/init.d/couchdb couchdb
/etc/init.d/couchdb start
# Start couchdb on system start
update-rc.d couchdb defaults

# Verify couchdb is running
curl http://127.0.0.1:5984/
# {"couchdb":"Welcome","version":"1.0.1"}

# run test suite in firefox at http://127.0.0.1:5984/_utils/couch_tests.html?script/couch_tests.js

Example 2 (with minimal dependencies)

Tested with CouchDB versions: 0.11.0, 1.0.0

This example is especially useful when using a minimal Ubuntu, rather than a full desktop one, as it won't install as many packages as the previous example.

Dependencies:

First, install SpiderMonkey from source, as described here (this should prevent the possible xulrunner issues described later).

Second, install the rest of the dependencies:

sudo apt-get install libicu-dev libcurl4-gnutls-dev libtool erlang-dev erlang

Note: Without the 'erlang' package, couchdb could still be installed, but would be missing important erlang libraries and won't run properly.

Installation:

couch_v='1.0.0'
prefix='/usr/local'

# install:
tar zxvf apache-couchdb-${couch_v}.tar.gz
cd apache-couchdb-${couch_v}
./configure --prefix=${prefix}
make && sudo make install

# add couchdb user:
sudo useradd -d ${prefix}/var/lib/couchdb couchdb

# correct permissions:
sudo chown -R couchdb: ${prefix}/var/{lib,log,run}/couchdb ${prefix}/etc/couchdb
sudo chmod 0770 ${prefix}/var/{lib,log,run}/couchdb ${prefix}/etc/couchdb

Additional Notes

Problems after upgrading from source

If you have previously built and installed from source it is likely that there will be a previous version of the Erlang libraries (couch-x.x.x, erlang-oauth, etap, ibrowse-x.x.x, mochiweb-xxx) in /usr/local/lib/couchdb/erlang/lib. These should be removed before doing sudo make install for the new version. If you only discover a problem (e.g., CouchDB crashes) after doing the new install, the problem might be solved by manually removing everything in /usr/local/lib/couchdb/erlang/lib and redoing sudo make install.

Problems with libmozjs and xulrunner?

In Ubuntu 10.04 you may get an error similar to this:

OS Process Error <0.4649.0> :: {os_process_error,{exit_status,127}}
/opt/couchdb/lib/couchdb/bin/couchjs: error while loading shared libraries: libmozjs.so: cannot open shared object file: No such file or directory

This is can be resolved by creating an xulrunner configuration as follows:

sudo vi /etc/ld.so.conf.d/xulrunner.conf

Note: To check what XULRunner version you have installed use xulrunner -v

Then add the following lines to the file (You may need to change the library version to match whats installed):

/usr/lib/xulrunner-x.x.x.x
/usr/lib/xulrunner-devel-x.x.x.x

Once the configuration files is created and saved, you will need to run ldconfig:

sudo /sbin/ldconfig

This solution is referenced in bug report #557275.

Installing spidermonkey from source

This has been tested on Ubuntu 8.04 Server, with couchdb 1.2.0, from source.

install_spidermonkey_ ( ) {
    cd /tmp
    SPIDERMONKEY_VER="js185-1.0.0"
    SPIDERMONKEY_DIR="js-1.8.5"
    wget http://ftp.mozilla.org/pub/mozilla.org/js/${SPIDERMONKEY_VER}.tar.gz
    tar xvzf ${SPIDERMONKEY_VER}.tar.gz
    cd ${SPIDERMONKEY_DIR}/js/src
    make distclean 2> /dev/null # Just in case it is dirty
    ./configure
    make clean
    make
    sudo make install
    sudo ldconfig # Make sure the new libraries are reachable
}
install_spidermonkey_

And then, to build couch:

JS_LIB="/usr/local/lib/libmozjs185.so"
JS_INCLUDE="/usr/local/include/js"
./configure --with-js-lib=${JS_LIB} --with-js-include=${JS_INCLUDE}

Note: because the libtools in Ubuntu 8.04 are old, the macro LT_INIT is not supported. To install CouchDB 1.2.0, some hacking must be performed on the configure script:

sed -i -e 's/^LT_INIT/#LT_INIT/' configure

System updates

When performing system updates (using apt-get or package manager) please keep in mind that the /etc/ld.so.conf.d/xulrunner.conf file is not maintained by the system and will not be updated if a new version of xulrunner is deployed!

So please check the update content in order to determine if the xulrunner package is being updated, then make sure that you update the configuration file with new version number.

You can use the following command line in order to update your xulrunner configuration:

find /usr/lib -maxdepth 1 -type d -name "xulrunner-*" | grep -v 'addons' > /tmp/new.xulrunner.conf && sudo cp /tmp/new.xulrunner.conf /etc/ld.so.conf.d/xulrunner.conf && sudo /sbin/ldconfig

You need to re-start your couchdb server after the library configuration update!

Don't forget to configure logging!

Setup log rotate

First off, a lot of people run CouchDB from source which means that in 99% of all installs, the log rotation is not activated.

To fix this (on Ubuntu/Debian), do the following:

sudo ln -s /usr/local/etc/logrotate.d/couchdb /etc/logrotate.d/couchdb

Don't forget to change the path to match your installation.

Make sure to familiarize yourself with log rotate. Depending on the space requirements and business of your installation, you should adjust your configuration so that you don't run out of disk space. If CouchDB is unable to log, it will crash.

Adjust the log level

In most cases it's more than alright to just run with a log level of error.

Add the following to your local.ini (in [log]): level = error Log directory

If you are still running out of diskspace? Add the following to your local.ini (in [log]):

file = /path/to/more/diskspace/couch.log

... if you adjusted the above, you will need to correct the config for logrotate.d as well.

No logging

Last but not least — if no logs are needed, just turn them off completely.

These logging tips are based on the recommendations found on Till Klampäckel's Blog article Operating CouchDB.

Note on installing on Ubuntu Desktop flavors

If you're not running Ubuntu server, but rather running some variant of Ubuntu desktop, I'd strongly recommend compiling from source and keeping the default prefix of /usr/local. Ubuntu comes standard with couchdb-bin, and uses desktop-couch with tools like Ubuntu One, gwibber, and evolution. But, Lucid Lynx ships with version 0.10.0. This is a long-term support item, but that doesn't mean Canonical will be releasing 0.11 anytime soon.

So, to install a parallel version of current CouchDB on an Ubuntu desktop system, you should download build from source, being careful to keep the default install prefix of /usr/local, and following all of the above instructions about libraries and dependencies.

Then, after installing CouchDB, you can still get it to start at boot as normal, but because 0.11.x is in /usr/local, just running

sudo update-rc.d couchdb defaults

is probably not going to do the right thing. What is seems to do is look in the /etc/init.d directory, where it will likely find the 0.10 version of CouchDB.

Instead, you have force the system to use the version of CouchDB installed in /usr/local. There should be an option to update-rc.d that will tell it to look in /usr/local/etc rather than /etc, but I couldn't find it.

A brute force way to make it work is to do something like:

sudo mv /etc/init.d/couchdb /etc/init.d/couchdb.0.10.donotuse
sudo ln -sf /usr/local/etc/init.d/couchdb /etc/init.d/couchdb
sudo update-rc.d couchdb defaults

External Articles