INSTALL.Unix

Apache CouchDB README.Unix
==========================

A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu.

Dependencies
------------

You will need the following installed:

 * Erlang OTP (>=R12B5)       (http://erlang.org/)
 * ICU                        (http://icu.sourceforge.net/)
 * OpenSSL                    (http://www.openssl.org/)
 * Mozilla SpiderMonkey (1.8) (http://www.mozilla.org/js/spidermonkey/)
 * libcurl                    (http://curl.haxx.se/libcurl/)
 * GNU Make                   (http://www.gnu.org/software/make/)
 * GNU Compiler Collection    (http://gcc.gnu.org/)

It is recommended that you install Erlang OTP R12B-5 or above where possible.

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

You can install the build tools by running:

    sudo apt-get install build-essential

You can install the other dependencies by running:

    sudo apt-get install erlang libicu-dev libmozjs-dev libcurl4-openssl-dev

Be sure to update the version numbers to match your system's available packages.

Mac OS X
~~~~~~~~

You can install the build tools by running:

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

You can install the other dependencies by running:

    sudo port install icu erlang spidermonkey curl

You will need MacPorts installed to use the `port` command.

Installing
----------

Once you have satisfied the dependencies you should run:

    ./configure

This script will configure CouchDB to be installed into `/usr/local` by default.

If you wish to customise the installation, pass `--help` to this script.

If everything was successful you should see the following message:

    You have configured Apache CouchDB, time to relax.

Relax.

To install CouchDB you should run:

    make && sudo make install

You only need to use `sudo` if you're installing into a system directory.

Try `gmake` if `make` is giving you any problems.

If everything was successful you should see the following message:

    You have installed Apache CouchDB, time to relax.

Relax.

First Run
---------

You can start the CouchDB server by running:

    sudo -i -u couchdb couchdb

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

When 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://127.0.0.1:5984/_utils/index.html

From here you should run the test suite.

Security Considerations
-----------------------

You should create a special `couchdb` user for CouchDB.

On many Unix-like systems you can run:

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

On Mac OS X you can use the Workgroup Manager to create users:

  http://www.apple.com/support/downloads/serveradmintools1047.html

You must make sure that:

    * The user has a working POSIX shell

    * The user's home directory is `/usr/local/var/lib/couchdb`

You can test this by:

    * Trying to log in as the `couchdb` user

    * Running `pwd` and checking the present working directory

Change the ownership of the CouchDB directories by running:

    chown -R couchdb:couchdb /usr/local/etc/couchdb
    chown -R couchdb:couchdb /usr/local/var/lib/couchdb
    chown -R couchdb:couchdb /usr/local/var/log/couchdb
    chown -R couchdb:couchdb /usr/local/var/run/couchdb

Change the permission of the CouchDB directories by running:

    chmod 0770 /usr/local/etc/couchdb
    chmod 0770 /usr/local/var/lib/couchdb
    chmod 0770 /usr/local/var/log/couchdb
    chmod 0770 /usr/local/var/run/couchdb

Running as a Daemon
-------------------

SysV/BSD-style Systems
~~~~~~~~~~~~~~~~~~~~~~

You can use the `couchdb` init script to control the CouchDB daemon.

On SysV-style systems, the init script will be installed into:

    /usr/local/etc/init.d

On BSD-style systems, the init script will be installed into:

    /usr/local/etc/rc.d

We use the `[init.d|rc.d]` notation to refer to both of these directories.

You can control the CouchDB daemon by running:

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

If you wish to configure how the init script works, you can edit:

    /usr/local/etc/default/couchdb

Comment out the `COUCHDB_USER` setting if you're running as a non-superuser.

To start the daemon on boot, copy the init script to:

    /etc/[init.d|rc.d]

You should then configure your system to run the init script automatically.

You may be able to run:

    sudo update-rc.d couchdb defaults

If this fails, consult your system documentation for more information.

A `logrotate` configuration is installed into:

    /usr/local/etc/logrotate.d/couchdb

Consult your `logrotate` documentation for more information.

It is critical that the CouchDB logs are rotated so as not to fill your disk.

Mac OS X
~~~~~~~~

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

You can load the configuration by running:

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

You can stop the CouchDB daemon by running:

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

You can start CouchDB by running:

    sudo launchctl start org.apache.couchdb

You can restart CouchDB by running:

    sudo launchctl stop org.apache.couchdb

You can edit the launchd configuration by running:

    open /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist

To start the daemon on boot, copy the configuration file to:

    /Library/LaunchDaemons

Consult your system documentation for more information.