path: root/README

Apache CouchDB README
=====================

Building From Subversion
------------------------

You can skip this section if you are installing from a release tarball.

### Dependencies ###

To build Apache CouchDB from checkout you need some of the following installed:

 * [GNU Automake][01] (>=1.6.3) (required)
 * [GNU Autoconf][02] (>=2.59) (required)
 * [GNU Libtool][03] (required)
 * [svn2cl][04] (optional)
 * [xsltproc][05] (optional)
 * [help2man][06] (optional)

If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
GNU/Linux) you can install these dependencies using the `apt-get` command:

    apt-get install automake autoconf libtool subversion-tools help2man

The OS X version of these dependencies may be out of date so it is recommended
that you use [MacPorts][07] to install newer versions using the `port` command:

    port install automake autoconf libtool help2man

Note: MacPorts users will need to install svn2cl by hand if they wish to use it.

### Bootstrapping ###

Note: You must repeat this step every time you update your Subversion checkout.

Follow the [check out instructions][08] and bootstrap the pristine source by
running the following command:

    ./bootstrap

You can use the `-C` option to generate a dummy `ChangeLog` file.

Installation And First Run
--------------------------

You will need the following installed:

 * [Erlang OTP][09] (>=R11B) (required)
 * [ICU][10] (required)
 * [Mozilla SpiderMonkey][11] (required)
 * [GNU Make][12] (required)
 * [GNU Compiler Collection][13] (required)

### UNIX-like Operating Systems (inc. OS X) ###

#### Dependencies ####

##### Debian-based (inc. Ubuntu) Systems #####

If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
GNU/Linux) you can install the dependencies using the `apt-get` command:

    apt-get install build-essential erlang libicu38 libicu-dev libmozjs-dev

If you get an error regarding the `libicu38` or `libicu-dev` be sure to check
the version used by your distribution (using `apt-cache search libicu`) and
install those packages instead.

##### OS X #####

To install GNU Make and the GNU Compiler Collection on OS X you should install
the Xcode Tools metapackage by running the following command:

    open /Applications/Installers/Xcode\ Tools/XcodeTools.mpkg

We recommend that you satisfy the other dependancies by installing
[MacPorts][07] and running the following command:

    port install icu erlang spidermonkey

Note: Don't forget to open a new terminal after you have installed MacPorts
as it updates your PATH and you will not be able to run the `port` command
without the effects of this change.

To update your `locate` database you may want to run the following command:

    sudo /usr/libexec/locate.updatedb

#### Installing ####

Once you have satisfied dependencies you should run the following command:

    ./configure

Note: Apache CouchDB is installed into `/usr/local` by default. If you want to
change where Apache CouchDB is installed (or where to find Erlang) be sure to
read the output from running the `./configure --help` command.

Note: All the examples assume you have installed into `/usr/local`.

If everything was successful you should see the following message:

    You have configured Apache CouchDB. Time to relax.

Relax.

To install Apache CouchDB you should then run the following command:

    make && sudo make install

If you do not wish to be prompted to overwrite any existing Apache CouchDB
configuration files you should run the following command:

    sudo make && yes | sudo make install

Note: Use of the `sudo` command is only required if you are installing into a
system owned directory. You do not need to do this if you are installing
elsewhere, such as your home directory.

More options can be found by reading the `INSTALL` file.

#### Security Considerations ####

It is not advisable to run Apache CouchDB as the superuser. We strongly
recommend that you create a specific user to run Apache CouchDB and own the
data/log directories.

You can use whatever tool your system provides to create a new `couchdb` user.

On many UNIX-like systems you can run the following command:

    adduser --system --home /var/lib/couchdb --no-create-home \
            --shell /bin/bash --group --gecos "CouchDB Administrator" couchdb

OS X provides the standard Accounts option from the System Preferences
application or you can optionally use the Workgroup Manager application which
can be downloaded as part of the [Server Admin Tools][14].

You should make sure that the `couchdb` user has a working POSIX shell and set
the home directory to `/usr/local/var/lib/couchdb` which is the Apache CouchDB
database directory.

Make sure to change the ownership of the Apache CouchDB data directories by
running the following commands:

    chown -R couchdb /usr/local/var/lib/couchdb
    chown -R couchdb /usr/local/var/log/couchdb

#### Running Manually ####

To start the Apache CouchDB server you should run the following command:

    sudo -u couchdb couchdb

This uses the `sudo` command to run the `couchdb` command as the `couchdb` user.

When Apache CouchDB starts it should eventually display the following message:

    Apache CouchDB has started. Time to relax.

Relax.

To check that everything has worked point your web browser to
[http://localhost:5984/_utils/index.html][15] and run the test suite.

##### OS X #####

If you get error when running Apache CouchDB that look like the following:

    dyld: Library not loaded: libicuuc.38.dy

You should make sure that your `~/.profile` file contains the following line:

    export DYLD_LIBRARY_PATH=/opt/local/lib:$DYLD_LIBRARY_PATH

This should have been added for you by MacPorts but may be missing.

#### Running as a Daemon ####

Note: These instructions assume you have created the `couchdb` user. See the
specific system information included below to learn how to reconfigure this.

Note: If any of these methods report a failure you can run the `couchdb`
command manually to see the error messages it is displaying.

The `/usr/local/etc/logrotate.d/couchdb` file is provided as a logrotate
configuration that you can use to rotate Apache CouchDB's logs.

##### SysV/BSD-style Systems #####

Depending on your system the `couchdb` init script will be installed into a
direcory called `init.d` (for SysV-style systems) or `rc.d` (for BSD-style
systems). These examples use the `[init.d|rc.d]` notation to indicate this.

You can control the Apache CouchDB daemon by running the following command:

    /usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|force-reload|status]

If you wish to configure how the init script works, such as which user to run
Apache CouchDB as, you must edit the `/usr/local/etc/default/couchdb` file as
appropriate. If you are running the init script as a non-superuser you need to
remove the line with the `COUCHDB_USER` setting.

If you wish the ApacheCouchDB daemon to run as a system service you need to copy
the `/usr/local/etc/[init.d|rc.d]/couchdb` script into your system wide
`/etc/[init.d|rc.d]` directory and update your system configuration as
appropriate.  Consult your system documentation for more information.

If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
GNU/Linux) you can configure your system using the following command:

    sudo update-rc.d couchdb defaults

##### OS X #####

You can use the `launchctl` command to control the Apache CouchDB daemon.

To load the launchd configuration you must run the following command:

    sudo launchctl load /usr/local/Library/LaunchDaemons/org.apache.couchdb

You can stop the Apache CouchDB daemon by running the following command:

    sudo launchctl unload /usr/local/Library/LaunchDaemons/org.apache.couchdb

If you wish to change the launchd configuration, such as which user to run
Apache CouchDB as, you must edit the
`/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist` file as
appropriate.

If you wish the Apache CouchDB daemon to run as a system service you need to
copy the `/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist` file into
your system wide `/Library/LaunchDaemons` directory.

### Windows ###

Windows documentation is incomplete. Please submit suggestions.

Development
-----------

### Reconfiguring the Build System ###

If you have edited any of the files used by the build system, such as the
`Makefile.am` files, you will need to reconfigure your source.

To reconfigure the source run the following command from the root directory:

    autoreconf && ./confgure

### Checking In Changes ###

If your source directory has been configured or built you will need to clean
the generated files before checking into the repository by running the
following command:

    make local-clean

If everything was successful you should now have a pristine checkout.

### Preparing For Distribution ###

To build the source for distribution you should then run the following command:

    ./configure && make distcheck

If everything was successful you should see a `zip` file and/or a `tar.gz` file
sitting in the root directory ready for distribution.

### Release Checklist ###

 1. Update the `README` file with important information.
 2. Update the `NEWS` file with change information.
 3. Update the `acinclude.m4` file with version information.

[01]: http://www.gnu.org/software/automake/
[02]: http://www.gnu.org/software/autoconf/
[03]: http://www.gnu.org/software/libtool/
[04]: http://ch.tudelft.nl/~arthur/svn2cl/
[05]: http://xmlsoft.org/XSLT/xsltproc2.html
[06]: http://www.gnu.org/software/help2man/
[07]: http://www.macports.org/
[08]: http://incubator.apache.org/couchdb/community/code.html
[09]: http://erlang.org/
[10]: http://icu.sourceforge.net/
[11]: http://www.mozilla.org/js/spidermonkey/
[12]: http://www.gnu.org/software/make/
[13]: http://gcc.gnu.org/
[14]: http://www.apple.com/support/downloads/serveradmintools1047.html
[15]: http://localhost:5984/_utils/index.html