Skip to content
Browse files

improve README copy

git-svn-id: https://svn.apache.org/repos/asf/couchdb/trunk@737712 13f79535-47bb-0310-9956-ffa450edef68
  • Loading branch information...
1 parent 9e0610b commit 60be7c2a8f3d88f47be7eef5cf0a973c868cfcbc @nslater nslater committed Jan 26, 2009
Showing with 45 additions and 73 deletions.
  1. +45 −73 README
View
118 README
@@ -28,14 +28,17 @@ To build Apache CouchDB from checkout you need some of the following installed:
* GNU Libtool (http://www.gnu.org/software/libtool/)
* GNU help2man (http://www.gnu.org/software/help2man/)
-If you are running a Debian GNU/Linux based system you can install these
-dependencies using the `apt-get` command:
+Debian-based (inc. Ubuntu) Systems
+++++++++++++++++++++++++++++++++++
+
+You can install the dependencies by running:
apt-get install automake autoconf libtool help2man
-The Mac OS X version of these dependencies may be out of date so it is recommended
-that you use MacPorts (http://www.macports.org/) to install newer versions using
-the `port` command:
+Mac OS X
+++++++++
+
+You can install the dependencies using MacPorts by running:
port install automake autoconf libtool help2man
@@ -44,20 +47,20 @@ Bootstrapping
Note: You must repeat this step every time you update your checkout.
-Bootstrap the pristine source by running the following command:
+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:
+To build and install Apache CouchDB you will need the following installed:
* Erlang OTP (>=R12B) (http://erlang.org/)
* ICU (http://icu.sourceforge.net/)
@@ -72,8 +75,7 @@ It is recommended that you install Erlang OTP R12B-4 or above where possible.
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:
+You can install the dependencies by running:
apt-get install build-essential erlang libicu38 libicu-dev libmozjs-dev \
libcurl4-openssl-dev
@@ -87,28 +89,19 @@ 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 the following command:
+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
-We recommend that you satisfy the other dependancies by installing
-[MacPorts][07] and running the following command:
+You can install the dependencies using MacPorts by running:
port install icu erlang spidermonkey curl
-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 the dependencies you should run the following command:
+Once you have satisfied the dependencies you should run:
./configure
@@ -128,11 +121,6 @@ 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: 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.
@@ -151,7 +139,7 @@ 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:
+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
@@ -166,16 +154,15 @@ 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.
-Make sure to change the ownership of the Apache CouchDB data directories by
-running the following commands:
+Change the ownership of the Apache CouchDB data directories by running:
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:
+You can start the Apache CouchDB server by running:
sudo -i -u couchdb couchdb
@@ -193,39 +180,25 @@ To check that everything has worked, point your web browser to:
From here you should run the test suite.
-Mac OS X
-++++++++
-
-If you get error when running Apache CouchDB that look like the following:
+Troubleshooting
+^^^^^^^^^^^^^^^
- dyld: Library not loaded: libicuuc.38.dylib
+If you're getting a cryptic error message, visit the wiki:
-It seems that your installation is messed up. The dynamically linked object
-file usually contains the path to the dynamic library it was linked against.
-Invoke the command:
+ http://wiki.apache.org/couchdb/Error_messages
- otool -L /usr/local/lib/couchdb/erlang/lib/couch-0.9.0a708993-incubating/priv/lib/couch_erl_driver.so
-
-e.g. to see where CouchDB expects the ICU libraries. In that case you should
-invoke:
-
- make distclean
- ./configure
- make
- sudo make install
+For general troubleshooting, visit the wiki:
-It is not necessary to set dyld(1) environment variables like
-DYLD_LIBARY_PATH. These are necessary only for debugging or testing binary
-compatibility.
+ 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.
+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.
@@ -237,7 +210,7 @@ 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:
+You can control the Apache CouchDB daemon by running:
/usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|force-reload|status]
@@ -248,43 +221,42 @@ 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 as
-appropriate. Consult your system documentation for more information.
+`/etc/[init.d|rc.d]` directory and update your system configuration.
-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:
+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.
-To load the launchd configuration you must run the following command:
+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 the following command:
+You can stop the Apache CouchDB daemon by running:
sudo launchctl unload /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
-You can change the launchd configuration, such as which user to run
-Apache CouchDB as, by running the command
-`open /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist`. It will open
-Apple's `Property List Editor'. See launchd.plist(5) for available options in
-launchd property lists. One is the `OnDemand' property, which makes it possible
-to start and stop the service using launchctl if set to `true'. By default,
-launchd immediately restarts a stopped service and makes the `launchctl stop'
-behave effectively like a restart. If set to `true', use these commands to start
-and stop Apache CouchDB:
+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
-If you wish the Apache CouchDB daemon to run at startup, you need to copy or
-symlink the `/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist` file
-into your system wide `/Library/LaunchDaemons` directory.
+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
~~~~~~~

0 comments on commit 60be7c2

Please sign in to comment.
Something went wrong with that request. Please try again.