Sometimes one extra character makes all the difference
[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 (>=R13B04, <R17)  (http://erlang.org/)
43  * ICU                          (http://icu-project.org/)
44  * OpenSSL                      (http://www.openssl.org/)
45  * Mozilla SpiderMonkey (1.7)   (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 libmozjs-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 groupinstall "Development Tools"
98     sudo yum install autoconf
99     sudo yum install autoconf-archive
100     sudo yum install automake
101     sudo yum install libtool
102     sudo yum install perl-Test-Harness
103     sudo yum install erlang-etap
104     sudo yum install erlang-erts
105     sudo yum install erlang-os_mon
106     sudo yum install erlang-eunit
107     sudo yum install libicu-devel
108     sudo yum install js-devel
109     sudo yum install curl-devel
110     sudo yum install pkg-config
111
112 While CouchDB builds against the default js-devel-1.7.0 included in
113 some distributions, it's recommended to use a more recent
114 js-devel-1.8.5.
115
116 Mac OS X
117 ~~~~~~~~
118
119 To build CouchDB from source on Mac OS X, you will need to install
120 Xcode.
121
122 You can install the other dependencies by running:
123
124     brew install autoconf
125     brew install autoconf-archive
126     brew install automake
127     brew install libtool
128     brew install erlang
129     brew install icu4c
130     brew install spidermonkey
131     brew install curl
132     brew install pkg-config
133
134 You will need Homebrew installed to use the `brew` command.
135
136 Learn more about Homebrew at:
137
138     http://mxcl.github.com/homebrew/
139
140 Some versions of Mac OS X ship a problematic OpenSSL library. If
141 you're experiencing troubles with CouchDB crashing intermittently with
142 a segmentation fault or a bus error, you will need to install your own
143 version of OpenSSL. See the troubleshooting guide, mentioned above,
144 for more information.
145
146 Installing
147 ----------
148
149 Once you have satisfied the dependencies you should run:
150
151     ./configure
152
153 This script will configure CouchDB to be installed into `/usr/local`
154 by default.
155
156 If you wish to customize the installation, pass `--help` to this
157 script.
158
159 If everything was successful you should see the following message:
160
161     You have configured Apache CouchDB, time to relax.
162
163 Relax.
164
165 To install CouchDB you should run:
166
167     make && sudo make install
168
169 You only need to use `sudo` if you're installing into a system directory.
170
171 Try `gmake` if `make` is giving you any problems.
172
173 If everything was successful you should see the following message:
174
175     You have installed Apache CouchDB, time to relax.
176
177 Relax.
178
179 First Run
180 ---------
181
182 You can start the CouchDB server by running:
183
184     sudo -i -u couchdb couchdb
185
186 This uses the `sudo` command to run the `couchdb` command as the
187 `couchdb` user.
188
189 When CouchDB starts it should eventually display the following
190 message:
191
192     Apache CouchDB has started, time to relax.
193
194 Relax.
195
196 To check that everything has worked, point your web browser to:
197
198     http://127.0.0.1:5984/_utils/index.html
199
200 From here you should run the test suite in Firefox.
201
202 Security Considerations
203 -----------------------
204
205 You should create a special `couchdb` user for CouchDB.
206
207 On many Unix-like systems you can run:
208
209     adduser --system \
210             --home /usr/local/var/lib/couchdb \
211             --no-create-home \
212             --shell /bin/bash \
213             --group --gecos \
214             "CouchDB Administrator" couchdb
215
216 On Mac OS X you can use the Workgroup Manager to create users:
217
218   http://www.apple.com/support/downloads/serveradmintools1047.html
219
220 You must make sure that:
221
222     * The user has a working POSIX shell
223
224     * The user's home directory is `/usr/local/var/lib/couchdb`
225
226 You can test this by:
227
228     * Trying to log in as the `couchdb` user
229
230     * Running `pwd` and checking the present working directory
231
232 Change the ownership of the CouchDB directories by running:
233
234     chown -R couchdb:couchdb /usr/local/etc/couchdb
235     chown -R couchdb:couchdb /usr/local/var/lib/couchdb
236     chown -R couchdb:couchdb /usr/local/var/log/couchdb
237     chown -R couchdb:couchdb /usr/local/var/run/couchdb
238
239 Change the permission of the CouchDB directories by running:
240
241     chmod 0770 /usr/local/etc/couchdb
242     chmod 0770 /usr/local/var/lib/couchdb
243     chmod 0770 /usr/local/var/log/couchdb
244     chmod 0770 /usr/local/var/run/couchdb
245
246 Update the permissions for your `default.ini` file:
247
248     chmod 0644 /usr/local/etc/couchdb/default.ini
249
250 Running as a Daemon
251 -------------------
252
253 SysV/BSD-style Systems
254 ~~~~~~~~~~~~~~~~~~~~~~
255
256 You can use the `couchdb` init script to control the CouchDB daemon.
257
258 On SysV-style systems, the init script will be installed into:
259
260     /usr/local/etc/init.d
261
262 On BSD-style systems, the init script will be installed into:
263
264     /usr/local/etc/rc.d
265
266 We use the `[init.d|rc.d]` notation to refer to both of these
267 directories.
268
269 You can control the CouchDB daemon by running:
270
271     /usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|status]
272
273 If you wish to configure how the init script works, you can edit:
274
275     /usr/local/etc/default/couchdb
276
277 Comment out the `COUCHDB_USER` setting if you're running as a
278 non-superuser.
279
280 To start the daemon on boot, copy the init script to:
281
282     /etc/[init.d|rc.d]
283
284 You should then configure your system to run the init script
285 automatically.
286
287 You may be able to run:
288
289     sudo update-rc.d couchdb defaults
290
291 If this fails, consult your system documentation for more information.
292
293 A `logrotate` configuration is installed into:
294
295     /usr/local/etc/logrotate.d/couchdb
296
297 Consult your `logrotate` documentation for more information.
298
299 It is critical that the CouchDB logs are rotated so as not to fill
300 your disk.
301
302 Mac OS X
303 ~~~~~~~~
304
305 You can use the `launchctl` command to control the CouchDB daemon.
306
307 You can load the configuration by running:
308
309     sudo launchctl load \
310          /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
311
312 You can stop the CouchDB daemon by running:
313
314     sudo launchctl unload \
315          /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
316
317 You can start CouchDB by running:
318
319     sudo launchctl start org.apache.couchdb
320
321 You can restart CouchDB by running:
322
323     sudo launchctl stop org.apache.couchdb
324
325 You can edit the launchd configuration by running:
326
327     open /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
328
329 To start the daemon on boot, copy the configuration file to:
330
331     /Library/LaunchDaemons
332
333 Consult your system documentation for more information.