Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: b76dd4d426
Fetching contributors…

Cannot retrieve contributors at this time

289 lines (181 sloc) 9.87 kb
Apache CouchDB README
=====================
Building From Subversion
------------------------
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][01] (>=1.6.3) (required)
* [GNU Autoconf][02] (>=2.59) (required)
* [GNU Libtool][03] (required)
* [svn2cl][04] (optional)
* [xsltproc][05] (optional)
* [help2man][06] (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
The OS X version of these dependencies may be out of date so it is recommended
that you use [MacPorts][07] to install newer versions using the `port` command:
port install automake autoconf libtool help2man
Note: MacPorts users will need to install svn2cl by hand if they wish to use it.
### Bootstrapping ###
Note: You must repeat this step every time you update your Subversion checkout.
Follow the [check out instructions][08] and 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][09] (>=R11B) (required)
* [ICU][10] (required)
* [Mozilla SpiderMonkey][11] (required)
* [GNU Make][12] (required)
* [GNU Compiler Collection][13] (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 libicu38 libicu-dev libmozjs-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.
##### 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][07] 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][14].
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][15] 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
-----------
### 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 the `README` file with important information.
2. Update the `NEWS` file with change information.
3. Update the `acinclude.m4` file with version information.
[01]: http://www.gnu.org/software/automake/
[02]: http://www.gnu.org/software/autoconf/
[03]: http://www.gnu.org/software/libtool/
[04]: http://ch.tudelft.nl/~arthur/svn2cl/
[05]: http://xmlsoft.org/XSLT/xsltproc2.html
[06]: http://www.gnu.org/software/help2man/
[07]: http://www.macports.org/
[08]: http://incubator.apache.org/couchdb/community/code.html
[09]: http://erlang.org/
[10]: http://icu.sourceforge.net/
[11]: http://www.mozilla.org/js/spidermonkey/
[12]: http://www.gnu.org/software/make/
[13]: http://gcc.gnu.org/
[14]: http://www.apple.com/support/downloads/serveradmintools1047.html
[15]: http://localhost:5984/_utils/index.html
Jump to Line
Something went wrong with that request. Please try again.