CouchDB Readme ============== Documentation ------------- Visit the wiki for more documentation. Building From Source -------------------- Dependencies ~~~~~~~~~~~~ To build CouchDB from source you need some of the following installed: * GNU Automake (>=1.6.3) (required) * GNU Autoconf (>=2.59) (required) * GNU Libtool (required) * svn2cl (optional) * help2man (optional) Note: svn2cl and help2man are NOT NEEDED if you're building an official release. 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 -------------------------------------------------------------------------------- If you are running OS X and have MacPorts installed you can install some of these dependencies by using the `port' command: -------------------------------------------------------------------------------- port install automake autoconf libtool help2man -------------------------------------------------------------------------------- Note: OS X users should already have Automake, Autoconf and Libtool installed. Note: MacPorts users will need to install svn2cl by hand. Bootstrapping ~~~~~~~~~~~~~ Note: You can skip this step if you're building an official release. 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: * GNU Make (required) * GNU Compiler Collection (required) * ICU (required) * Erlang OTP (required) * GNU Readline (optional) 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 libicu36 libicu36-dev libreadline5-dev -------------------------------------------------------------------------------- If you get an error regarding the `libicu36' or `libicu36-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 and running the following command: -------------------------------------------------------------------------------- port install icu erlang -------------------------------------------------------------------------------- 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: CouchDB is installed into `/usr/local' by default. If you want to change where 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 CouchDB. Time to relax. -------------------------------------------------------------------------------- Relax. To install CouchDB you should then run the following command: -------------------------------------------------------------------------------- make && 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 CouchDB as the superuser. We strongly recommend that you create a specific user to run 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 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 . You should set the home directory of the `couchdb' user to `/usr/local/var/lib/couchdb' which is the CouchDB database directory. Make sure to change the ownership of the 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 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 CouchDB starts it should eventually display the following message: -------------------------------------------------------------------------------- CouchDB has started. Time to relax. -------------------------------------------------------------------------------- Relax. To check that everything has worked point your web browser to and run the test suite. OS X ++++ If you get error when running 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. 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 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 CouchDB as, you must edit the `/usr/local/etc/default/couchdb' file as appropriate. If you wish the CouchDB 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 CouchDB daemon. To load the launchd configuration you must run the following command: -------------------------------------------------------------------------------- sudo launchctl load -w /usr/local/Library/LaunchDaemons/ -------------------------------------------------------------------------------- You can now control the CouchDB daemon by running the following command: -------------------------------------------------------------------------------- sudo launchctl [start|stop] org.couchdb.couchdb -------------------------------------------------------------------------------- If you wish to change the launchd configuration, such as which user to run CouchDB as, you must edit the `/usr/local/Library/LaunchDaemons/org.couchdb.couchdb.plist' file as appropriate. If you wish the CouchDB daemon to run as a system service you need to copy the `/usr/local/Library/LaunchDaemons/org.couchdb.couchdb.plist' file into your system wide `/Library/LaunchDaemons' directory. Windows ~~~~~~~ Windows documentation is incomplete. Please submit suggestions. Development and Distribution ---------------------------- 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 this file with important information. 2. Update the `NEWS' file with change information. 3. Update the `acinclude.m4' file with version information. Legal _____ Copyright (C) 2007 Damien Katz . Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.