summaryrefslogtreecommitdiff
path: root/README
blob: 9cbcd95df798030ee4cce925fe0fdddaafd57f6c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
Apache CouchDB Readme
=====================

Documentation
-------------

Visit the wiki <http://www.couchdbwiki.com/> for more documentation.

Building From Subversion
------------------------

Dependencies
~~~~~~~~~~~~

To build Apache CouchDB from checkout you need some of the following installed:

 * GNU Automake (>=1.6.3) <http://www.gnu.org/software/automake/> (required)
 * GNU Autoconf (>=2.59) <http://www.gnu.org/software/autoconf/> (required)
 * GNU Libtool <http://www.gnu.org/software/libtool/> (required)
 * svn2cl <http://ch.tudelft.nl/~arthur/svn2cl/> (optional)
 * xsltproc <http://xmlsoft.org/XSLT/xsltproc2.html> (optional)
 * help2man <http://www.gnu.org/software/help2man/> (optional)

If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
GNU/Linux) you can install these dependencies using the `apt-get' command:

--------------------------------------------------------------------------------
apt-get install automake autoconf libtool subversion-tools help2man
--------------------------------------------------------------------------------

If you are running OS X and have MacPorts <http://www.macports.org/> installed
you can install some of these dependencies by using the `port' command:

--------------------------------------------------------------------------------
port install automake autoconf libtool help2man
--------------------------------------------------------------------------------

Note: OS X users should already have Automake, Autoconf and Libtool installed.

Note: MacPorts users will need to install svn2cl by hand.

Bootstrapping
~~~~~~~~~~~~~

Note: You must repeat this step every time you update your Subversion checkout.

Bootstrap the pristine source by running the following command:

--------------------------------------------------------------------------------
./bootstrap
--------------------------------------------------------------------------------

You can use the `-C' option to generate a dummy `ChangeLog' file.

Installation And First Run
--------------------------

You will need the following installed:

 * Erlang OTP <http://erlang.org/> (required)
 * ICU <http://icu.sourceforge.net/> (required)
 * Mozilla SpiderMonkey <http://www.mozilla.org/js/spidermonkey/> (required)
 * GNU Make <http://www.gnu.org/software/make/> (required)
 * GNU Compiler Collection <http://gcc.gnu.org/> (required)

UNIX-like Operating Systems (inc. OS X)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Dependencies
^^^^^^^^^^^^

Debian-based (inc. Ubuntu) Systems
++++++++++++++++++++++++++++++++++

If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
GNU/Linux) you can install the dependencies using the `apt-get' command:

--------------------------------------------------------------------------------
apt-get install build-essential erlang libicu36 libicu36-dev libmozjs-dev
--------------------------------------------------------------------------------

If you get an error regarding the `libicu36' or `libicu36-dev' be sure to check
the version used by your distribution (using `apt-cache search libicu') and
install those packages instead.

OS X
++++

To install GNU Make and the GNU Compiler Collection on OS X you should install
the Xcode Tools metapackage by running the following command:

--------------------------------------------------------------------------------
open /Applications/Installers/Xcode\ Tools/XcodeTools.mpkg
--------------------------------------------------------------------------------

We recommend that you satisfy the other dependancies by installing MacPorts
<http://www.macports.org/> and running the following command:

--------------------------------------------------------------------------------
port install icu erlang spidermonkey
--------------------------------------------------------------------------------

Note: Don't forget to open a new terminal after you have installed MacPorts
as it updates your PATH and you will not be able to run the `port' command
without the effects of this change.

To update your `locate' database you may want to run the following command:

--------------------------------------------------------------------------------
sudo /usr/libexec/locate.updatedb
--------------------------------------------------------------------------------

Installing
^^^^^^^^^^

Once you have satisfied dependencies you should run the following command:

--------------------------------------------------------------------------------
./configure
--------------------------------------------------------------------------------

Note: Apache CouchDB is installed into `/usr/local' by default. If you want to
change where Apache CouchDB is installed (or where to find Erlang) be sure to
read the output from running the `./configure --help' command.

Note: All the examples assume you have installed into `/usr/local'.

If everything was successful you should see the following message:

--------------------------------------------------------------------------------
You have configured Apache CouchDB. Time to relax.
--------------------------------------------------------------------------------

Relax.

To install Apache CouchDB you should then run the following command:

--------------------------------------------------------------------------------
make && sudo make install
--------------------------------------------------------------------------------

If you do not wish to be prompted to overwrite any existing Apache CouchDB
configuration files you should run the following command:

--------------------------------------------------------------------------------
sudo make && yes | sudo make install
--------------------------------------------------------------------------------

Note: Use of the `sudo' command is only required if you are installing into a
system owned directory. You do not need to do this if you are installing
elsewhere, such as your home directory.

More options can be found by reading the `INSTALL' file.

Security Considerations
^^^^^^^^^^^^^^^^^^^^^^^

It is not advisable to run Apache CouchDB as the superuser. We strongly
recommend that you create a specific user to run Apache CouchDB and own the
data/log directories.

You can use whatever tool your system provides to create a new `couchdb' user.

On many UNIX-like systems you can run the following command:

--------------------------------------------------------------------------------
adduser couchdb
--------------------------------------------------------------------------------

OS X provides the standard Accounts option from the System Preferences
application or you can optionally use the Workgroup Manager application which
can be downloaded as part of the Server Admin Tools
<http://www.apple.com/support/downloads/serveradmintools1047.html>.

You should set the home directory of the `couchdb' user to
`/usr/local/var/lib/couchdb' which is the Apache CouchDB database directory.

Make sure to change the ownership of the Apache CouchDB data directories by
running the following commands:

--------------------------------------------------------------------------------
chown -R couchdb /usr/local/var/lib/couchdb
chown -R couchdb /usr/local/var/log/couchdb
--------------------------------------------------------------------------------

Running Manually
^^^^^^^^^^^^^^^^

To start the Apache CouchDB server you should run the following command:

--------------------------------------------------------------------------------
sudo -u couchdb couchdb
--------------------------------------------------------------------------------

This uses the `sudo' command to run the `couchdb' command as the `couchdb' user.

When Apache 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://localhost:5984/_utils/index.html> and run the test suite.

OS X
++++

If you get error when running Apache CouchDB that look like the following:

--------------------------------------------------------------------------------
dyld: Library not loaded: libicuuc.38.dy
--------------------------------------------------------------------------------

You should make sure that your `~/.profile' file contains the following line:

--------------------------------------------------------------------------------
export DYLD_LIBRARY_PATH=/opt/local/lib:$DYLD_LIBRARY_PATH
--------------------------------------------------------------------------------

This should have been added for you by MacPorts but may be missing.

Running as a Daemon
^^^^^^^^^^^^^^^^^^^

Note: These instructions assume you have created the `couchdb' user. See the
specific system information included below to learn how to reconfigure this.

Note: If any of these methods report a failure you can run the `couchdb'
command manually to see the error messages it is displaying.

The `/usr/local/etc/logrotate.d/couchdb' file is provided as a logrotate
configuration that you can use to rotate Apache CouchDB's logs.

SysV/BSD-style Systems
++++++++++++++++++++++

Depending on your system the `couchdb' init script will be installed into a
direcory called `init.d' (for SysV-style systems) or `rc.d' (for BSD-style
systems). These examples use the `[init.d|rc.d]' notation to indicate this.

You can control the Apache CouchDB daemon by running the following command:

--------------------------------------------------------------------------------
/usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|force-reload|status]
--------------------------------------------------------------------------------

If you wish to configure how the init script works, such as which user to run
Apache CouchDB as, you must edit the `/usr/local/etc/default/couchdb' file as
appropriate. If you are running the init script as a non-superuser you need to
remove the line with the `COUCHDB_USER' setting.

If you wish the ApacheCouchDB daemon to run as a system service you need to copy
the `/usr/local/etc/[init.d|rc.d]/couchdb' script into your system wide
`/etc/[init.d|rc.d]' directory and update your system configuration as
appropriate.  Consult your system documentation for more information.

If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
GNU/Linux) you can configure your system using the following command:

--------------------------------------------------------------------------------
sudo update-rc.d couchdb defaults
--------------------------------------------------------------------------------

OS X
++++

You can use the `launchctl' command to control the Apache CouchDB daemon.

To load the launchd configuration you must run the following command:

--------------------------------------------------------------------------------
sudo launchctl load /usr/local/Library/LaunchDaemons/org.apache.couchdb
--------------------------------------------------------------------------------

You can stop the Apache CouchDB daemon by running the following command:

--------------------------------------------------------------------------------
sudo launchctl unload /usr/local/Library/LaunchDaemons/org.apache.couchdb
--------------------------------------------------------------------------------

If you wish to change the launchd configuration, such as which user to run
Apache CouchDB as, you must edit the
`/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist' file as
appropriate.

If you wish the Apache CouchDB daemon to run as a system service you need to
copy the `/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist' file into
your system wide `/Library/LaunchDaemons' directory.

Windows
~~~~~~~

Windows documentation is incomplete. Please submit suggestions.

Development and Distribution
----------------------------

Reconfiguring the Build System
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have edited any of the files used by the build system, such as the
`Makefile.am' files, you will need to reconfigure your source.

To reconfigure the source run the following command from the root directory:

--------------------------------------------------------------------------------
autoreconf && ./confgure
--------------------------------------------------------------------------------

Checking In Changes
~~~~~~~~~~~~~~~~~~~

If your source directory has been configured or built you will need to clean
the generated files before checking into the repository by running the
following command:

--------------------------------------------------------------------------------
make local-clean
--------------------------------------------------------------------------------

If everything was successful you should now have a pristine checkout.

Preparing For Distribution
~~~~~~~~~~~~~~~~~~~~~~~~~~

To build the source for distribution you should then run the following command:

--------------------------------------------------------------------------------
./configure && make distcheck
--------------------------------------------------------------------------------

If everything was successful you should see a `zip' file and/or a `tar.gz' file
sitting in the root directory ready for distribution.

Release Checklist
~~~~~~~~~~~~~~~~~

 1. Update this file with important information.
 2. Update the `NEWS' file with change information.
 3. Update the `acinclude.m4' file with version information.