| Apache CouchDB README.Unix |
| ========================== |
| |
| A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu. |
| |
| Community installation guides are available on the wiki: |
| |
| http://wiki.apache.org/couchdb/Installation |
| |
| This document is the canonical source of installation information. However, many |
| systems have gotchas that you need to be aware of. In addition, dependencies |
| frequently change as distributions update their archives. If you're running into |
| trouble, be sure to check out the wiki. If you have any tips to share, please |
| also update the wiki so that others can benefit from your experience. |
| |
| Troubleshooting |
| --------------- |
| |
| There is a troubleshooting guide: |
| |
| http://wiki.apache.org/couchdb/Troubleshooting |
| |
| There is a wiki for general documentation: |
| |
| http://wiki.apache.org/couchdb/ |
| |
| There are collection of friendly mailing lists: |
| |
| http://couchdb.apache.org/community/lists.html |
| |
| Please work through these in order if you experience any problems. |
| |
| Dependencies |
| ------------ |
| |
| You should have the following installed: |
| |
| * Erlang OTP (>=R13B04, <R17) (http://erlang.org/) |
| * ICU (http://icu-project.org/) |
| * OpenSSL (http://www.openssl.org/) |
| * Mozilla SpiderMonkey (1.7) (http://www.mozilla.org/js/spidermonkey/) |
| * GNU Make (http://www.gnu.org/software/make/) |
| * GNU Compiler Collection (http://gcc.gnu.org/) |
| * libcurl (http://curl.haxx.se/libcurl/) |
| * help2man (http://www.gnu.org/s/help2man/) |
| * Python (>=2.7) for docs (http://python.org/) |
| * Python Sphinx (>=1.1.3) (http://pypi.python.org/pypi/Sphinx) |
| |
| It is recommended that you install Erlang OTP R13B-4 or above where possible. |
| You will only need libcurl if you plan to run the JavaScript test suite. And |
| help2man is only need if you plan on installing the CouchDB man pages. |
| Python and Sphinx are only required for building the online documentation. |
| |
| Debian-based Systems |
| ~~~~~~~~~~~~~~~~~~~~ |
| |
| You can install the dependencies by running: |
| |
| sudo apt-get install build-essential |
| sudo apt-get install erlang-base-hipe |
| sudo apt-get install erlang-dev |
| sudo apt-get install erlang-manpages |
| sudo apt-get install erlang-eunit |
| sudo apt-get install erlang-nox |
| sudo apt-get install libicu-dev |
| sudo apt-get install libmozjs-dev |
| sudo apt-get install libcurl4-openssl-dev |
| sudo apt-get install pkg-config |
| |
| There are lots of Erlang packages. If there is a problem with your install, try |
| a different mix. There is more information on the wiki. Additionally, you might |
| want to install some of the optional Erlang tools which may also be useful. |
| |
| Be sure to update the version numbers to match your system's available packages. |
| |
| For up to date instructions, please see: |
| |
| http://wiki.apache.org/couchdb/Installing_on_Debian |
| |
| http://wiki.apache.org/couchdb/Installing_on_Ubuntu |
| |
| Unfortunately, it seems that installing dependencies on Ubuntu is troublesome. |
| |
| RedHat-based (Fedora, Centos, RHEL) Systems |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| |
| You can install the dependencies by running: |
| |
| sudo yum groupinstall "Development Tools" |
| sudo yum install autoconf |
| sudo yum install autoconf-archive |
| sudo yum install automake |
| sudo yum install libtool |
| sudo yum install perl-Test-Harness |
| sudo yum install erlang-etap |
| sudo yum install erlang-erts |
| sudo yum install erlang-os_mon |
| sudo yum install erlang-eunit |
| sudo yum install libicu-devel |
| sudo yum install js-devel |
| sudo yum install curl-devel |
| sudo yum install pkg-config |
| |
| While CouchDB builds against the default js-devel-1.7.0 included in some |
| distributions, it's recommended to use a more recent js-devel-1.8.5. |
| |
| Mac OS X |
| ~~~~~~~~ |
| |
| To build CouchDB from source on Mac OS X, you will need to install Xcode. |
| |
| You can install the other dependencies by running: |
| |
| brew install autoconf |
| brew install autoconf-archive |
| brew install automake |
| brew install libtool |
| brew install erlang |
| brew install icu4c |
| brew install spidermonkey |
| brew install curl |
| brew install pkg-config |
| |
| You will need Homebrew installed to use the `brew` command. |
| |
| Learn more about Homebrew at: |
| |
| http://mxcl.github.com/homebrew/ |
| |
| Some versions of Mac OS X ship a problematic OpenSSL library. If you're |
| experiencing troubles with CouchDB crashing intermittently with a segmentation |
| fault or a bus error, you will need to install your own version of OpenSSL. See |
| the troubleshooting guide, mentioned above, for more information. |
| |
| 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 in Firefox. |
| |
| 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 |
| |
| Update the permissions for your `default.ini` file: |
| |
| chmod 0644 /usr/local/etc/couchdb/default.ini |
| |
| 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. |