Generally speaking, you should avoid installing from source. Many operating systems provide package managers that will allow you to download and install CouchDB with a single command. These package managers usually take care of setting things up correctly, handling security, and making sure that the CouchDB database is started and stopped correctly by your system. The first few appendixes showed you how to install CouchDB packages for Unix-like, Mac OS X, and Windows operating systems. If you are unable to follow those instructions, or you need to install by hand for other reasons, this chapter is for you.
To build and install CouchDB, you will need to install a collection of other software that CouchDB depends on. Without this software properly installed on your system, CouchDB will refuse to work. You’ll need to download and install the following:
It is recommended that you install Erlang OTP R12B-5 or above if possible.
Each of these software packages should provide custom installation instructions, either on the website or in the archive you download. If you’re lucky, however, you may be able to use a package manager to install these dependencies.
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 about any of these packages, be sure to check for the current version offered by your distribution. It may be the case that a newer version has been released and the package name has been changed. For example, you can search for the newest ICU package by running:
apt-cache search libicu
Select and install the highest version from the list available.
You will need to install the Xcode Tools metapackage by running:
open /Applications/Installers/Xcode\ Tools/XcodeTools.mpkg
If this is unavailable on your system, you will need to install it from your Mac OS X installation CD. Alternatively, you can download a copy.
You can then install the other dependencies using MacPorts by running:
port install icu erlang spidermonkey curl
See Appendix B for more details.
Once you have installed all of the dependencies, you should download a copy of the CouchDB source. This should give you an archive that you’ll need to unpack. Open up a terminal and change directory to your newly unpacked archive.
Configure the source by running:
./configure
We’re going to be installing CouchDB into /usr/local, which is the default location for user-installed software. A ton of options are available for this command, and you can customize everything from the installation location, such as your home directory, to the location of your Erlang or SpiderMonkey installation.
To see what’s available, you can run:
./configure --help
Generally, you can ignore this step if you didn’t get any errors the first time you ran it. You’ll only need to pass extra options if your setup is a bit weird and the script is having trouble finding one of the dependencies you installed in the last section.
If everything was successful, you should see the following message:
You have configured Apache CouchDB, time to relax.
Relax.
Build and install the source by running:
make && sudo make install
If you changed the installation location to somewhere temporary, you
may not want to use the sudo command here. If you are
having problems running make, you may want to try
running gmake if it is available on your system. More
options can be found by reading the INSTALL
file.
It is not advisable to run the CouchDB server as the super user. If the CouchDB server is compromised by an attacker while it is being run by a super user, the attacker will get super user access to your entire system. That’s not what we want!
We strongly recommend that you create a specific user for CouchDB. This user should have as few privileges on your system as possible, preferably the bare minimum needed to run the CouchDB server, read the configuration files, and write to the data and 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" couchdbMac OS X provides the standard Accounts option from the System Preferences application, or you can use the Workgroup Manager application, which can be downloaded as part of the Server Admin Tools.
You should make sure that the couchdb user has a
working login shell. You can test this by logging into a terminal as the
couchdb user. You should also make sure to set the home
directory to /usr/local/var/lib/couchdb, which is the
CouchDB database 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 -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
This isn’t the final word in securing your CouchDB setup. If you’re deploying CouchDB on the Web, or any place where untrusted parties can access your sever, it behooves you to research the recommended security measures for your operating system and take any additional steps needed. Keep in mind the network security adage that the only way to properly secure a computer system is to unplug it from the network.
You can start the 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 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
This is Futon, the CouchDB web administration console. We covered the basics of Futon in our early chapters. Once you have it loaded, you should select and run the CouchDB Test Suite from the righthand menu. This will make sure that everything is behaving as expected, and it may save you some serious headaches if things turn out to be a bit wonky.
Once you’ve got CouchDB running nicely, you’ll probably want to run it as daemon. A daemon is a software application that runs continually in the background, waiting to handle requests. This is how most production database servers run, and you can configure CouchDB to run like this, too.
When you run CouchDB as a daemon, it logs to a number of files that
you’ll want to clean up from time to time. Letting your log files fill up
a disk is a good way to break your server! Some operating systems come
with software that does this for you, and it is important for you to
research your options and take the necessary steps to make sure that this
doesn’t become a problem. CouchDB ships with a
logrotate configuration that may be useful.
Depending on your operating system, the couchdb
daemon script could be installed into a directory called
init.d (for SysV-style systems) or
rc.d (for BSD-style systems) under the
/usr/local/etc directory. The following examples
use [init.d|rc.d] to indicate this choice, and you
must replace it with your actual directory before running any of these
commands.
You can start the CouchDB daemon by running:
sudo /usr/local/etc/[init.d|rc.d]/couchdb start
You can stop the CouchDB daemon by running:
sudo /usr/local/etc/[init.d|rc.d]/couchdb stop
You can get the status of the CouchDB daemon by running:
sudo /usr/local/etc/[init.d|rc.d]/couchdb status
If you want to configure how the daemon script works, you will find a bunch of options you can edit in the /usr/local/etc/default/couchdb file.
If you want to run the script without the sudo
command, you will need to remove the COUCHDB_USER
setting from this file.
Your operating system will probably provide a way to control the CouchDB daemon automatically, starting and stopping it as a system service. To do this, you will need to copy the daemon script into your system /etc/[init.d|rc.d] directory, and run a command such as:
sudo update-rc.d couchdb defaults
Consult your system documentation for more information.
You can use the launchd system to control the
CouchDB daemon.
You can load the launchd configuration by
running:
sudo launchctl load /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
You can unload the launchd configuration by
running:
sudo launchctl unload /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
You can start the CouchDB daemon by running:
sudo launchctl start org.apache.couchdb
You can stop the CouchDB daemon by running:
sudo launchctl stop org.apache.couchdb
The launchd system can control the CouchDB
daemon automatically, starting and stopping it as a system service. To
do this, you will need to copy the plist file into your system
/Library/LaunchDaemons directory.
Software being software, you can count on something going wrong every now and then. No need to panic; CouchDB has a great community full of people who will be able to answer your questions and help you get started. Here are a few resources to help you on your way:
If you’re getting a weird error message, see the Error Messages wiki page.
For general troubleshooting, try out the Troubleshooting steps.
For other general support, you should visit the mailing lists.
Don’t forget to use your favorite search engine when diagnosing problems. If you look around a bit, you’re likely to find something. It’s very possible that a bunch of other people have had exactly the same problem as you and a solution has been posted somewhere on the Web. Good luck, and remember to relax!
Get CouchDB: The Definitive Guide now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
