README - couchdb - Git at Google

 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
     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.

 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.
	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
	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.

	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.