Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…
Cannot retrieve contributors at this time
450 lines (292 sloc) 14.8 KB
Apache CouchDB README
Apache CouchDB is beta 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.
To build Apache CouchDB from checkout, you need some of the following installed:
* GNU Automake (>=1.6.3) (
* GNU Autoconf (>=2.59) (
* GNU Libtool (
* GNU 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
Note: You must repeat this step every time you update your checkout.
Bootstrap the pristine source by running:
Installation and First Run
Unix-like Operating Systems (inc. Mac OS X)
To build and install Apache CouchDB, you will need the following installed:
* Erlang OTP (>=R12B5) (
* ICU (
* OpenSSL (
* Mozilla SpiderMonkey (=1.8) (
* libcurl (
* GNU Make (
* GNU Compiler Collection (
It is recommended that you install Erlang OTP R12B-5 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
Once you have satisfied the dependencies you should run:
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.
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:
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
chown -R couchdb:couchdb /usr/local/var/run/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
chmod -R 0770 /usr/local/var/run/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.
To check that everything has worked, point your web browser to:
From here you should run the test suite.
If you're getting a cryptic error message, visit the wiki:
For general troubleshooting, visit the wiki:
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.
The Windows build process is very similar to the Erlang build process. It is
therefore recommended you build erlang itself from sources, as this will ensure
that you have all of the tools necessary to build CouchDB itself. A binary build
of Erlang should work for those in a hurry, but it may cause problems. See the
end of these notes for more information on building Erlang.
Build Tools
To build on Windows, you will need the following installed:
* Erlang OTP (>=R12B5) (
* ICU (
* OpenSSL (
* Mozilla SpiderMonkey (=1.8) (
* libcurl (
* Cygwin (
* Visual Studio 2008 (
Please note:
* When installing Erlang, you must build it from source. The CouchDB build
makes use of a number of the Erlang build scripts. While using an Erlang
binary should work, if these Erlang build scripts cannot be found, the
CouchDB build itself will break.
* When installing ICU, select the binaries built with Visual Studio 2008.
* When installing Cygwin, be sure to select all the `development` tools.
* When installing libcurl, be sure to install by hand as the Cygwin binaries
are built with an incompatible compiler and will not work with Erlang.
Build Environment
Once you have satisfied the dependencies you should run:
set CYGWIN=nontsec
Close and restart all Cygwin terminals for this to take effect globally.
Execute the VC .bat files to setup your environment such that cl.exe etc are
on your path. Start a cygwin shell.
Check your environment:
* which link -> should point at the MS linker.
* which cl -> should point at the MS compiler.
If you are building from a source version of erlang:
Executing "eval `./otp_build env_win32`" as per the Erlang build
instructions, will have set everything up, including the CC, LD etc
variables. Do this even if erlang is already built and you are just
building couch. This will have set the variables ERL_TOP, CC, LD, AD
and a number of others.
Then, PATH must be adjusted such what 'which erl' lists the erl.exe
you built rather than the 'erl' script in the erts/etc/win32/cygwin_tools
directory - eg:
$ export PATH=$ERL_TOP/release/win32/erts-5.7.2/bin:$PATH
If you are building from a binary version of erlang:
* set ERL_TOP to the top of the erlang directory
Add to the PATH such that 'which erl' points at your erl.exe - eg:
$ export PATH=$ERL_TOP/erts-5.6.5/bin
You must also ensure the etc scripts from the Erlang source tree is
on your PATH. Use "which" to ensure the path is set correctly.
Then set more variables:
$ export
$ export
$ export
$ export
Set COUCHDB_TOP to the source directory.
And we should be ready to bootstrap and build.
We start by bootstrapping:
$ ./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=/cygdrive/c/path_to_seamonkey_include \
--with-js-lib=/cygdrive/c/path_to_seamonkey_lib \
--with-win32-icu-binaries=/cygdrive/c/path_to_icu_binaries_root \
--with-erlang=$ERL_TOP/release/win32/usr/include \
--with-win32-curl=/cygdrive/c/path/to/curl/root/directory \
--with-openssl-bin-dir=c:/openssl/bin \
--with-msvc-redist-dir=c:/dir/with/vcredist_platform_executable \
Relax, then relax some more, then get a beer and relax some more; the
above command may take many many minutes to complete...
Note that all paths must be in cygwin format. Those starting with $ERL_TOP
can be entered literally, assuming ERL_TOP is set as described above.
When building the installer, the necessary openssl binaries are pulled from
the directory pointed to --with-openssl-bin-dir.
Now we can build it and "install" it into the $ERL_TOP/release/win32 (or
wherever you set --prefix to above) directory:
$ make install
Relax on your new couch:
The $ERL_TOP/release/win32 directory is now ready to .zip up, be packaged
by an installer, etc. To test it in-place, execute:
$ $ERL_TOP/release/win32/bin/couchdb.bat
and everything should work fine.
To create an installer, execute:
$ make dist
and look for etc/windows/setup-couch*.exe. Note - only do this after
a clean build, not after testing in-place - otherwise your test database and
log files will be shipped!
Building Erlang
* Follow the instructions as described. You do need openssl, but don't need
the GUI tools. You can skip them with the following command:
echo "skipping gs" > lib/gs/SKIP
echo "skipping ic" > lib/ic/SKIP
* Ensure `which link` points at the Microsoft linker. If you do not do this,
the one in /usr/bin may be found instead.
* After executing `./otp_build release -a`, be sure to execute Install.exe in
the release/win32 directory to setup the release/win32/bin dir correctly.
Cryptographic Software Notice
This distribution includes cryptographic software. The country in which you
currently reside may have restrictions on the import, possession, use, and/or
re-export to another country, of encryption software. BEFORE using any
encryption software, please check your country's laws, regulations and policies
concerning the import, possession, or use, and re-export of encryption software,
to see if this is permitted. See <> for more
The U.S. Government Department of Commerce, Bureau of Industry and Security
(BIS), has classified this software as Export Commodity Control Number (ECCN)
5D002.C.1, which includes information security software using or performing
cryptographic functions with asymmetric algorithms. The form and manner of this
Apache Software Foundation distribution makes it eligible for export under the
License Exception ENC Technology Software Unrestricted (TSU) exception (see the
BIS Export Administration Regulations, Section 740.13) for both object code and
source code.
The following provides more details on the included cryptographic software:
CouchDB includes a HTTP client (ibrowse) with SSL functionality.
Jump to Line
Something went wrong with that request. Please try again.