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/) * 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. Optional dependencies: * libcurl (http://curl.haxx.se/libcurl/) This only affects the command line JavaScript test suite which most users do not use. Ubuntu ~~~~~~ See http://wiki.apache.org/couchdb/Installing_on_Ubuntu for updated instructions on how to install on Ubuntu. Debian-based 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.