summaryrefslogtreecommitdiff
path: root/INSTALL.Unix
diff options
context:
space:
mode:
Diffstat (limited to 'INSTALL.Unix')
-rw-r--r--INSTALL.Unix231
1 files changed, 231 insertions, 0 deletions
diff --git a/INSTALL.Unix b/INSTALL.Unix
new file mode 100644
index 00000000..768e3846
--- /dev/null
+++ b/INSTALL.Unix
@@ -0,0 +1,231 @@
+Apache CouchDB README.Unix
+==========================
+
+A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu.
+
+Dependencies
+------------
+
+You will need the following installed:
+
+ * Erlang OTP (>=R12B5) (http://erlang.org/)
+ * ICU (http://icu.sourceforge.net/)
+ * OpenSSL (http://www.openssl.org/)
+ * Mozilla SpiderMonkey (1.8) (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-5 or above where possible.
+
+Ubuntu
+~~~~~~
+
+See
+
+ http://wiki.apache.org/couchdb/Installing_on_Ubuntu
+
+for updated instructions on how to install on Ubuntu.
+
+Debian-based Systems
+~~~~~~~~~~~~~~~~~~~~
+
+You can install the build tools by running:
+
+ sudo apt-get install build-essential
+
+You can install the other dependencies by running:
+
+ sudo apt-get install erlang libicu-dev libmozjs-dev libcurl4-openssl-dev
+
+Be sure to update the version numbers to match your system's available packages.
+
+Mac OS X
+~~~~~~~~
+
+You can install the build tools by running:
+
+ open /Applications/Installers/Xcode\ Tools/XcodeTools.mpkg
+
+You can install the other dependencies by running:
+
+ sudo port install icu erlang spidermonkey curl
+
+You will need MacPorts installed to use the `port` command.
+
+Installing
+----------
+
+Once you have satisfied the dependencies you should run:
+
+ ./configure
+
+This script will configure CouchDB to be installed into `/usr/local` by default.
+
+If you wish to customise the installation, pass `--help` to this script.
+
+If everything was successful you should see the following message:
+
+ You have configured Apache CouchDB, time to relax.
+
+Relax.
+
+To install CouchDB you should run:
+
+ make && sudo make install
+
+You only need to use `sudo` if you're installing into a system directory.
+
+Try `gmake` if `make` is giving you any problems.
+
+If everything was successful you should see the following message:
+
+ You have installed Apache CouchDB, time to relax.
+
+Relax.
+
+First Run
+---------
+
+You can start the CouchDB server by running:
+
+ sudo -i -u couchdb couchdb
+
+This uses the `sudo` command to run the `couchdb` command as the `couchdb` user.
+
+When 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.
+
+Security Considerations
+-----------------------
+
+You should create a special `couchdb` user for CouchDB.
+
+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
+
+On Mac OS X you can use the Workgroup Manager to create users:
+
+ http://www.apple.com/support/downloads/serveradmintools1047.html
+
+You must make sure that:
+
+ * The user has a working POSIX shell
+
+ * The user's home directory is `/usr/local/var/lib/couchdb`
+
+You can test this by:
+
+ * Trying to log in as the `couchdb` user
+
+ * Running `pwd` and checking the present working directory
+
+Change the ownership of the 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 CouchDB directories by running:
+
+ chmod 0770 /usr/local/etc/couchdb
+ chmod 0770 /usr/local/var/lib/couchdb
+ chmod 0770 /usr/local/var/log/couchdb
+ chmod 0770 /usr/local/var/run/couchdb
+
+Running as a Daemon
+-------------------
+
+SysV/BSD-style Systems
+~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the `couchdb` init script to control the CouchDB daemon.
+
+On SysV-style systems, the init script will be installed into:
+
+ /usr/local/etc/init.d
+
+On BSD-style systems, the init script will be installed into:
+
+ /usr/local/etc/rc.d
+
+We use the `[init.d|rc.d]` notation to refer to both of these directories.
+
+You can control the CouchDB daemon by running:
+
+ /usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|status]
+
+If you wish to configure how the init script works, you can edit:
+
+ /usr/local/etc/default/couchdb
+
+Comment out the `COUCHDB_USER` setting if you're running as a non-superuser.
+
+To start the daemon on boot, copy the init script to:
+
+ /etc/[init.d|rc.d]
+
+You should then configure your system to run the init script automatically.
+
+You may be able to run:
+
+ sudo update-rc.d couchdb defaults
+
+If this fails, consult your system documentation for more information.
+
+A `logrotate` configuration is installed into:
+
+ /usr/local/etc/logrotate.d/couchdb
+
+Consult your `logrotate` documentation for more information.
+
+It is critical that the CouchDB logs are rotated so as not to fill your disk.
+
+Mac OS X
+~~~~~~~~
+
+You can use the `launchctl` command to control the CouchDB daemon.
+
+You can load the configuration by running:
+
+ sudo launchctl load \
+ /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
+
+You can stop the CouchDB daemon by running:
+
+ sudo launchctl unload \
+ /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
+
+You can start CouchDB by running:
+
+ sudo launchctl start org.apache.couchdb
+
+You can restart CouchDB by running:
+
+ sudo launchctl stop org.apache.couchdb
+
+You can edit the launchd configuration by running:
+
+ open /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
+
+To start the daemon on boot, copy the configuration file to:
+
+ /Library/LaunchDaemons
+
+Consult your system documentation for more information.