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