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