Fetching latest commit…
Cannot retrieve the latest commit at this time
|Failed to load latest commit information.|
Apache CouchDB README ===================== Apache CouchDB is alpha software and still under heavy development. Please be aware that important areas such as the public API or internal database format may see backwards incompatible changes between versions. Building From Checkout ---------------------- You can skip this section if you are installing from a release tarball. 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/) * GNU Autoconf (>=2.59) (http://www.gnu.org/software/autoconf/) * GNU Libtool (http://www.gnu.org/software/libtool/) * GNU help2man (http://www.gnu.org/software/help2man/) Debian-based (inc. Ubuntu) Systems ++++++++++++++++++++++++++++++++++ You can install the dependencies by running: apt-get install automake autoconf libtool help2man Mac OS X ++++++++ You can install the dependencies using MacPorts by running: port install automake autoconf libtool help2man Bootstrapping ~~~~~~~~~~~~~ Note: You must repeat this step every time you update your checkout. Bootstrap the pristine source by running: ./bootstrap Installation and First Run -------------------------- UNIX-like Operating Systems (inc. Mac OS X) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Dependencies ^^^^^^^^^^^^ To build and install Apache CouchDB you will need the following installed: * Erlang OTP (>=R12B) (http://erlang.org/) * ICU (http://icu.sourceforge.net/) * OpenSSL (http://www.openssl.org/) * Mozilla SpiderMonkey (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-4 or above where possible. Debian-based (inc. Ubuntu) Systems ++++++++++++++++++++++++++++++++++ You can install the dependencies by running: apt-get install build-essential erlang libicu-dev libmozjs-dev libcurl4-openssl-dev If you get an error regarding the `libicu38` or `libicu-dev` be sure to check the version used by your distribution (using `apt-cache search libicu`) and install those packages instead. `libcurl4-openssl-dev` is the current version of `libcurl-dev` supplied by Ubuntu. You may need to specify an alternate package name for libcurl bindings. Mac OS X ++++++++ To install GNU Make and the GNU Compiler Collection on Mac OS X you should install the Xcode Tools metapackage by running: open /Applications/Installers/Xcode\ Tools/XcodeTools.mpkg You can install the dependencies using MacPorts by running: port install icu erlang spidermonkey curl Installing ^^^^^^^^^^ Once you have satisfied the dependencies you should run: ./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 Note: The 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. If you are having problems running `make` you may want to try running `gmake` if this is available on your system. 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: adduser --system --home /usr/local/var/lib/couchdb --no-create-home \ --shell /bin/bash --group --gecos "CouchDB Administrator" couchdb Mac 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 make sure that the `couchdb` user has a working POSIX shell and set the home directory to `/usr/local/var/lib/couchdb` which is the Apache CouchDB database directory. Change the ownership of the Apache 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 Change the permission of the Apache CouchDB directories by running: chmod -R 0770 /usr/local/etc/couchdb chmod -R 0770 /usr/local/var/lib/couchdb chmod -R 0770 /usr/local/var/log/couchdb Running Manually ^^^^^^^^^^^^^^^^ You can start the Apache CouchDB server by running: sudo -i -u couchdb couchdb -b 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://127.0.0.1:5984/_utils/index.html From here you should run the test suite. Troubleshooting ^^^^^^^^^^^^^^^ If you're getting a cryptic error message, visit the wiki: http://wiki.apache.org/couchdb/Error_messages For general troubleshooting, visit the wiki: http://wiki.apache.org/couchdb/Troubleshooting 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: /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 Apache 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. You may be able to configure your system using the following command: sudo update-rc.d couchdb defaults Consult your system documentation for more information. Mac OS X ++++++++ You can use the `launchctl` command to control the Apache CouchDB daemon. You can load the launchd configuration by running: sudo launchctl load /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist You can stop the Apache CouchDB daemon by running: sudo launchctl unload /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist You can start Apache CouchDB by running: sudo launchctl start org.apache.couchdb You can restart Apache CouchDB by running: sudo launchctl stop org.apache.couchdb You can change the launchd configuration by running: open /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist If you want the Apache CouchDB daemon to run at startup, copy the `/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist` file to your system `/Library/LaunchDaemons` directory. Windows ~~~~~~~ Windows documentation is incomplete. Please submit suggestions. To build on Windows, you need the following tools: * cygwin - it isn't clear exactly which tools you need - select all 'development' tools. * VS2008 * Erlang - a built source distro of erlang is preferred. A binary distribution of Erlang is OK, but you will also need a source distribution for the cc.sh/link.sh etc wrapper shell scripts used by erlang - couch reuses these scripts in its build process and the license isn't compatible enough for us to clone them. * Windows SDK Other tools: * Fetch the 'curl' sources and build them as per the instructions. The cygwin curl binaries are built with a different compiler so are no good. * Download the ICU binaries built with VS2008. * Download and build the hg trunk of seamonkey. Setup your environment: Execute the VC .bat files to setup your environment such that cl.exe etc are on your path. Start a cygwin shell (NOTE: If you are using Vista, you need to start an elevated shell script, otherwise cygwin will fail attempting to 'chmod +x filename'.) Check your environment: * which link -> should point at the MS linker. * which cl -> should point at the MS compiler. Set the following variables: * COUCHDB_TOP to the source directory. * ERL_TOP to the top of the erlang directory (if you built erlang from sources, that variable is probably already set) * WIN_SDK_TOP to the windows SDK directory Add a couple of directories to the PATH: $ export PATH=$PATH:$ERL_TOP/erts-5.6.5/bin:$WIN_SDK_TOP/bin If you are building with a binary distro of Erlang: You must also ensure the cc.sh etc scripts from the Erlang source tree is on your PATH. Use "which cc.sh" to ensure the path is set correctly. Then set more variables: $ export CC=cc.sh $ export LD=ld.sh $ export AR=ar.sh $ export RC=rc.sh If you are building Erlang from sources, then executing "eval `./otp_build env_win32`" as per the Erlang build instructions, will have set everything up, including the CC, LD etc variables. EXCEPT - PATH must be adjusted such what 'which erl' lists the erl.exe you built rather than the 'erl' script in the cygwin_tools directory. You must also set a CFLAGS environment variable to '-O2' - ie: # export CFLAGS=-O2 And we should be ready to bootstrap: $ cd $COUCHDB_TOP $ ./bootstrap You have bootstrapped Apache CouchDB, time to relax. Run `./configure' to configure the source before you install. $ Now we need to run a complicated configure command-line. $ ./configure \ --with-js-include=path_to_seamonkey_include \ --with-js-lib=path_to_seamonkey_lib \ --with-win32-icu-binaries=path/to/icu-binaries/include \ --with-erlang=path/to/erlang/erts-5.6.5/include \ --with-win32-curl=path/to/curl/root/directory Where: * 'path_to_seamonkey_include' will be the 'build-xxx/dist/include' dir under seamonkey in cygwin format (ie, /cygpath/...) * 'path_to_seamonkey_lib' is the 'build-xxx/dist/lib in cygwin format. * 'path/to/icu-binaries' should be in cygwin format. * The other paths should be somewhat obvious, but are in Windows format with forward slashes (eg, c:/...). * The --with-erlang option will need to point at a 'build' directory in the erlang tree if you built erlang from source (eg, c:/path/to/erlang-src/release/win32/usr/include' For reference, the following command-line is an example of a real command-line: ./configure --with-js-include=/cygdrive/o/src/mozilla-central/work/js/src/build-release/dist/include \ --with-js-lib=/cygdrive/o/src/mozilla-central/work/js/src/build-release/dist/lib \ --with-win32-icu-binaries=/cygdrive/o/src/mm/icu \ --with-erlang=o:/temp/erl5.6.5/erts-5.6.5/include \ --with-win32-curl=o:/src/mm/curl-7.19.5 \ --prefix=/cygdrive/c/src/mm/couch/otp_src_R13B01/release/win32/ Note: --prefix above - only used by 'make install' and assumes a source erlang distro. couch will be installed directly into the specified erlanf Status: * Most things currently build - notable exception is 'couch_erl_driver.dll'. Problems seem to be: - making libtool do the right thing wrt command-lines.