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