diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 343 |
1 files changed, 343 insertions, 0 deletions
@@ -0,0 +1,343 @@ +Apache CouchDB Readme +===================== + +Documentation +------------- + +Visit the wiki <http://www.couchdbwiki.com/> for more documentation. + +Building From Subversion +------------------------ + +Dependencies +~~~~~~~~~~~~ + +To build Apache CouchDB from checkout you need some of the following installed: + + * GNU Automake (>=1.6.3) <http://www.gnu.org/software/automake/> (required) + * GNU Autoconf (>=2.59) <http://www.gnu.org/software/autoconf/> (required) + * GNU Libtool <http://www.gnu.org/software/libtool/> (required) + * svn2cl <http://ch.tudelft.nl/~arthur/svn2cl/> (optional) + * xsltproc <http://xmlsoft.org/XSLT/xsltproc2.html> (optional) + * help2man <http://www.gnu.org/software/help2man/> (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 +-------------------------------------------------------------------------------- + +If you are running OS X and have MacPorts <http://www.macports.org/> 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 must repeat this step every time you update your Subversion checkout. + +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 <http://erlang.org/> (required) + * ICU <http://icu.sourceforge.net/> (required) + * Mozilla SpiderMonkey <http://www.mozilla.org/js/spidermonkey/> (required) + * GNU Make <http://www.gnu.org/software/make/> (required) + * GNU Compiler Collection <http://gcc.gnu.org/> (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 libicu36 libicu36-dev libmozjs-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 +<http://www.macports.org/> 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 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 +<http://www.apple.com/support/downloads/serveradmintools1047.html>. + +You should set the home directory of the `couchdb' user 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> 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 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. |