Reorder installation steps
[couchdb.git] / INSTALL.Unix
1 Apache CouchDB INSTALL.Unix
2 ==========================
3
4 A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu.
5
6 Community installation guides are available on the wiki:
7
8     http://wiki.apache.org/couchdb/Installation
9
10 If you are trying to build CouchDB from a git checkout rather than
11 a .tar.gz, see the `DEVELOPERS` file.
12
13 This document is the canonical source of installation
14 information. However, many systems have gotchas that you need to be
15 aware of. In addition, dependencies frequently change as distributions
16 update their archives. If you're running into trouble, be sure to
17 check out the wiki. If you have any tips to share, please also update
18 the wiki so that others can benefit from your experience.
19
20 Troubleshooting
21 ---------------
22
23 There is a troubleshooting guide:
24
25     http://wiki.apache.org/couchdb/Troubleshooting
26
27 There is a wiki for general documentation:
28
29     http://wiki.apache.org/couchdb/
30
31 There are collection of friendly mailing lists:
32
33     http://couchdb.apache.org/community/lists.html
34
35 Please work through these in order if you experience any problems.
36
37 Dependencies
38 ------------
39
40 You should have the following installed:
41
42  * Erlang OTP (>=R14B01, =<R17) (http://erlang.org/)
43  * ICU                          (http://icu-project.org/)
44  * OpenSSL                      (http://www.openssl.org/)
45  * Mozilla SpiderMonkey (1.8.5) (http://www.mozilla.org/js/spidermonkey/)
46  * GNU Make                     (http://www.gnu.org/software/make/)
47  * GNU Compiler Collection      (http://gcc.gnu.org/)
48  * libcurl                      (http://curl.haxx.se/libcurl/)
49  * help2man                     (http://www.gnu.org/s/help2man/)
50  * Python (>=2.7) for docs      (http://python.org/)
51  * Python Sphinx (>=1.1.3)      (http://pypi.python.org/pypi/Sphinx)
52
53 It is recommended that you install Erlang OTP R13B-4 or above where
54 possible.  You will only need libcurl if you plan to run the
55 JavaScript test suite. And help2man is only need if you plan on
56 installing the CouchDB man pages.  Python and Sphinx are only required
57 for building the online documentation.
58
59 Debian-based Systems
60 ~~~~~~~~~~~~~~~~~~~~
61
62 You can install the dependencies by running:
63
64     sudo apt-get install build-essential
65     sudo apt-get install erlang-base-hipe
66     sudo apt-get install erlang-dev
67     sudo apt-get install erlang-manpages
68     sudo apt-get install erlang-eunit
69     sudo apt-get install erlang-nox
70     sudo apt-get install libicu-dev
71     sudo apt-get install libmozjs185-dev
72     sudo apt-get install libcurl4-openssl-dev
73     sudo apt-get install pkg-config
74
75 There are lots of Erlang packages. If there is a problem with your
76 install, try a different mix. There is more information on the
77 wiki. Additionally, you might want to install some of the optional
78 Erlang tools which may also be useful.
79
80 Be sure to update the version numbers to match your system's available
81 packages.
82
83 For up to date instructions, please see:
84
85   http://wiki.apache.org/couchdb/Installing_on_Debian
86
87   http://wiki.apache.org/couchdb/Installing_on_Ubuntu
88
89 Unfortunately, it seems that installing dependencies on Ubuntu is
90 troublesome.
91
92 RedHat-based (Fedora, Centos, RHEL) Systems
93 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
94
95 You can install the dependencies by running:
96
97     sudo yum install autoconf
98     sudo yum install autoconf-archive
99     sudo yum install automake
100     sudo yum install curl-devel
101     sudo yum install erlang-asn1
102     sudo yum install erlang-erts
103     sudo yum install erlang-eunit
104     sudo yum install erlang-os_mon
105     sudo yum install erlang-xmerl
106     sudo yum install erlang-rebar
107     sudo yum install help2man
108     sudo yum install js-devel
109     sudo yum install libicu-devel
110     sudo yum install libtool
111     sudo yum install perl-Test-Harness
112
113 While CouchDB builds against the default js-devel-1.7.0 included in
114 some distributions, it's recommended to use a more recent
115 js-devel-1.8.5.
116
117 Mac OS X
118 ~~~~~~~~
119
120 To build CouchDB from source on Mac OS X, you will need to install
121 the Command Line Tools:
122
123     xcode-select --install
124
125 You can then install the other dependencies by running:
126
127     brew install autoconf
128     brew install autoconf-archive
129     brew install automake
130     brew install libtool
131     brew install erlang
132     brew install icu4c
133     brew install spidermonkey
134     brew install curl
135     brew install pkg-config
136     brew install rebar
137
138 You will need Homebrew installed to use the `brew` command.
139
140 Learn more about Homebrew at:
141
142     http://mxcl.github.com/homebrew/
143
144 Some versions of Mac OS X ship a problematic OpenSSL library. If
145 you're experiencing troubles with CouchDB crashing intermittently with
146 a segmentation fault or a bus error, you will need to install your own
147 version of OpenSSL. See the troubleshooting guide, mentioned above,
148 for more information.
149
150 Installing
151 ----------
152
153 Once you have satisfied the dependencies you should run:
154
155     ./configure
156
157 This script will configure CouchDB to be installed into `/usr/local`
158 by default.
159
160 If you wish to customize the installation, pass `--help` to this
161 script.
162
163 If everything was successful you should see the following message:
164
165     You have configured Apache CouchDB, time to relax.
166
167 Relax.
168
169 To install CouchDB you should run:
170
171     make && sudo make install
172
173 You only need to use `sudo` if you're installing into a system directory.
174
175 Try `gmake` if `make` is giving you any problems.
176
177 If everything was successful you should see the following message:
178
179     You have installed Apache CouchDB, time to relax.
180
181 Relax.
182
183 User Registration
184 -----------------
185
186 You should create a special `couchdb` user for CouchDB.
187
188 On many Unix-like systems you can run:
189
190     adduser --system \
191             --home /usr/local/var/lib/couchdb \
192             --no-create-home \
193             --shell /bin/bash \
194             --group --gecos \
195             "CouchDB Administrator" couchdb
196
197 On Mac OS X you can use the Workgroup Manager to create users:
198
199   http://www.apple.com/support/downloads/serveradmintools1047.html
200
201 You must make sure that:
202
203     * The user has a working POSIX shell
204
205     * The user's home directory is `/usr/local/var/lib/couchdb`
206
207 You can test this by:
208
209     * Trying to log in as the `couchdb` user
210
211     * Running `pwd` and checking the present working directory
212
213 Change the ownership of the CouchDB directories by running:
214
215     chown -R couchdb:couchdb /usr/local/etc/couchdb
216     chown -R couchdb:couchdb /usr/local/var/lib/couchdb
217     chown -R couchdb:couchdb /usr/local/var/log/couchdb
218     chown -R couchdb:couchdb /usr/local/var/run/couchdb
219
220 Change the permission of the CouchDB directories by running:
221
222     chmod 0770 /usr/local/etc/couchdb
223     chmod 0770 /usr/local/var/lib/couchdb
224     chmod 0770 /usr/local/var/log/couchdb
225     chmod 0770 /usr/local/var/run/couchdb
226
227 Update the permissions for your `default.ini` file:
228
229     chmod 0644 /usr/local/etc/couchdb/default.ini
230
231 First Run
232 ---------
233
234 You can start the CouchDB server by running:
235
236     sudo -i -u couchdb couchdb
237
238 This uses the `sudo` command to run the `couchdb` command as the
239 `couchdb` user.
240
241 When CouchDB starts it should eventually display the following
242 message:
243
244     Apache CouchDB has started, time to relax.
245
246 Relax.
247
248 To check that everything has worked, point your web browser to:
249
250     http://127.0.0.1:5984/_utils/index.html
251
252 From here you should run the test suite in Firefox.
253
254 Running as a Daemon
255 -------------------
256
257 SysV/BSD-style Systems
258 ~~~~~~~~~~~~~~~~~~~~~~
259
260 You can use the `couchdb` init script to control the CouchDB daemon.
261
262 On SysV-style systems, the init script will be installed into:
263
264     /usr/local/etc/init.d
265
266 On BSD-style systems, the init script will be installed into:
267
268     /usr/local/etc/rc.d
269
270 We use the `[init.d|rc.d]` notation to refer to both of these
271 directories.
272
273 You can control the CouchDB daemon by running:
274
275     /usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|status]
276
277 If you wish to configure how the init script works, you can edit:
278
279     /usr/local/etc/default/couchdb
280
281 Comment out the `COUCHDB_USER` setting if you're running as a
282 non-superuser.
283
284 To start the daemon on boot, copy the init script to:
285
286     /etc/[init.d|rc.d]
287
288 You should then configure your system to run the init script
289 automatically.
290
291 You may be able to run:
292
293     sudo update-rc.d couchdb defaults
294
295 If this fails, consult your system documentation for more information.
296
297 A `logrotate` configuration is installed into:
298
299     /usr/local/etc/logrotate.d/couchdb
300
301 Consult your `logrotate` documentation for more information.
302
303 It is critical that the CouchDB logs are rotated so as not to fill
304 your disk.
305
306 Mac OS X
307 ~~~~~~~~
308
309 You can use the `launchctl` command to control the CouchDB daemon.
310
311 You can load the configuration by running:
312
313     sudo launchctl load \
314          /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
315
316 You can stop the CouchDB daemon by running:
317
318     sudo launchctl unload \
319          /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
320
321 You can start CouchDB by running:
322
323     sudo launchctl start org.apache.couchdb
324
325 You can restart CouchDB by running:
326
327     sudo launchctl stop org.apache.couchdb
328
329 You can edit the launchd configuration by running:
330
331     open /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
332
333 To start the daemon on boot, copy the configuration file to:
334
335     /Library/LaunchDaemons
336
337 Consult your system documentation for more information.