summaryrefslogtreecommitdiff
path: root/README
blob: 3d81bfaf7afa6b2e6627954a25d973132721cd6b (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
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
Apache CouchDB README
=====================

Apache CouchDB is alpha software and still under heavy development. Please be
aware that important areas such as the public API or internal database format
may see backwards incompatible changes between versions.

Building From Checkout
----------------------

You can skip this section if you are installing from a release tarball.

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/)
 * GNU Autoconf (>=2.59)  (http://www.gnu.org/software/autoconf/)
 * GNU Libtool            (http://www.gnu.org/software/libtool/)
 * GNU help2man           (http://www.gnu.org/software/help2man/)

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

You can install the dependencies by running:

    apt-get install automake autoconf libtool help2man

Mac OS X
++++++++

You can install the dependencies using MacPorts by running:

    port install automake autoconf libtool help2man

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

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

Bootstrap the pristine source by running:

    ./bootstrap

Installation and First Run
--------------------------

Unix-like Operating Systems (inc. Mac OS X)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

To build and install Apache CouchDB you will need the following installed:

 * Erlang OTP (>=R12B5)    (http://erlang.org/)
 * ICU                     (http://icu.sourceforge.net/)
 * OpenSSL                 (http://www.openssl.org/)
 * Mozilla SpiderMonkey    (http://www.mozilla.org/js/spidermonkey/)
 * libcurl                 (http://curl.haxx.se/libcurl/)
 * GNU Make                (http://www.gnu.org/software/make/)
 * GNU Compiler Collection (http://gcc.gnu.org/)

It is recommended that you install Erlang OTP R12B-5 or above where possible.

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

You can install the dependencies by running:

    apt-get install build-essential erlang libicu-dev libmozjs-dev libcurl4-openssl-dev

If you get an error regarding the `libicu38` or `libicu-dev` be sure to check
the version used by your distribution (using `apt-cache search libicu`) and
install those packages instead. `libcurl4-openssl-dev` is the current version of
`libcurl-dev` supplied by Ubuntu. You may need to specify an alternate package
name for libcurl bindings.

Mac OS X
++++++++

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

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

You can install the dependencies using MacPorts by running:

    port install icu erlang spidermonkey curl

Installing
^^^^^^^^^^

Once you have satisfied the dependencies you should run:

    ./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

Note: The 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.

If you are having problems running `make` you may want to try running `gmake` if
this is available on your system.

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:

    adduser --system --home /usr/local/var/lib/couchdb --no-create-home \
            --shell /bin/bash --group --gecos "CouchDB Administrator" couchdb

Mac 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 make sure that the `couchdb` user has a working POSIX shell and set
the home directory to `/usr/local/var/lib/couchdb` which is the Apache CouchDB
database directory.

Change the ownership of the Apache CouchDB directories by running:

    chown -R couchdb:couchdb /usr/local/etc/couchdb
    chown -R couchdb:couchdb /usr/local/var/lib/couchdb
    chown -R couchdb:couchdb /usr/local/var/log/couchdb
    chown -R couchdb:couchdb /usr/local/var/run/couchdb

Change the permission of the Apache CouchDB directories by running:

    chmod -R 0770 /usr/local/etc/couchdb
    chmod -R 0770 /usr/local/var/lib/couchdb
    chmod -R 0770 /usr/local/var/log/couchdb
    chmod -R 0770 /usr/local/var/run/couchdb

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

You can start the Apache CouchDB server by running:

    sudo -i -u couchdb couchdb -b

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://127.0.0.1:5984/_utils/index.html

From here you should run the test suite.

Troubleshooting
^^^^^^^^^^^^^^^

If you're getting a cryptic error message, visit the wiki:

  http://wiki.apache.org/couchdb/Error_messages

For general troubleshooting, visit the wiki:

  http://wiki.apache.org/couchdb/Troubleshooting

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:

    /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 Apache CouchDB 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.

You may be able to configure your system using the following command:

    sudo update-rc.d couchdb defaults

Consult your system documentation for more information.

Mac OS X
++++++++

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

You can load the launchd configuration by running:

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

You can stop the Apache CouchDB daemon by running:

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

You can start Apache CouchDB by running:

    sudo launchctl start org.apache.couchdb

You can restart Apache CouchDB by running:

    sudo launchctl stop org.apache.couchdb

You can change the launchd configuration by running:

    open /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist

If you want the Apache CouchDB daemon to run at startup, copy the
`/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist` file to your system
`/Library/LaunchDaemons` directory.

Windows
~~~~~~~

The Windows build process is very similar to the erlang build process;
indeed, we re-use some of their shell-scripts.  Therefore, it is recommended
you build erlang itself from sources - this will ensure that you have all the
tools and environment necessary to build couch itself.  A binary build of
erlang should work for those in a hurry (see below), but it isn't really
supported.  See the end of these notes or information on building erlang
which is relevant to couch.

Build Tools
-----------

To build on Windows, you need the following tools:

* cygwin - it isn't clear exactly which tools you need - select all
  'development' tools.  As mentioned above, if you can build erlang itself
  you have everything you need.

* VS2008

* Erlang - a built source distro of erlang is preferred.  A binary
  distribution of Erlang is OK, but you will also need a source distribution
  for the cc.sh/link.sh etc wrapper shell scripts used by erlang - couch
  reuses these scripts in its build process and the license isn't compatible
  enough for us to clone them.

Other tools:

* Fetch the 'curl' sources and build them as per the instructions.  The cygwin
  curl binaries are built with a different compiler so are no good.

* Download the ICU binaries built with VS2008.

* Download and build the same version of spidermonkey the version of couch
  requires - at time of writing this is 1.8.  Different versions will not
  work (ie, at time of writing, 1.8.1 does not work with couch).

Build Environment
-----------------

Setup your environment:

For the sake of everything you find sacred:
  set CYGWIN=nontsec
BEFORE starting any cygwin environments.  Set this variable globally.  Without
it you can expect all kinds of permissions-related problems.

Execute the VC .bat files to setup your environment such that cl.exe etc are
on your path.  Start a cygwin shell.

Check your environment:
  * which link -> should point at the MS linker.
  * which cl -> should point at the MS compiler.

If you are building from a source version of erlang:

  Executing  "eval `./otp_build env_win32`" as per the Erlang build
  instructions, will have set everything up, including the CC, LD etc
  variables.  Do this even if erlang is already built and you are just
  building couch.  This will have set the variables ERL_TOP, CC, LD, AD
  and a number of others.

  Then, PATH must be adjusted such what 'which erl' lists the erl.exe
  you built rather than the 'erl' script in the erts/etc/win32/cygwin_tools
  directory - eg:

  $ export PATH=$ERL_TOP/release/win32/erts-5.7.2/bin:$PATH

If you are building from a binary version of erlang:

  * set ERL_TOP to the top of the erlang directory

  Add to the PATH such that 'which erl' points at your erl.exe - eg:

  $ export PATH=$ERL_TOP/erts-5.6.5/bin

  You must also ensure the cc.sh etc scripts from the Erlang source tree is
  on your PATH.  Use "which cc.sh" to ensure the path is set correctly.

  Then set more variables:
    $ export CC=cc.sh
    $ export LD=ld.sh
    $ export AR=ar.sh
    $ export RC=rc.sh

Set COUCHDB_TOP to the source directory.

And we should be ready to bootstrap and build.

Building
--------

We start by bootstrapping:

  $ cd $COUCHDB_TOP
  $ ./bootstrap
  You have bootstrapped Apache CouchDB, time to relax.

  Run `./configure' to configure the source before you install.
  $

Relax.

Now we need to run a complicated configure command-line.

  $ ./configure \
      --with-js-include=/cygdrive/c/path_to_seamonkey_include \
      --with-js-lib=/cygdrive/c/path_to_seamonkey_lib \
      --with-win32-icu-binaries=/cygdrive/c/path_to_icu_binaries_root \
      --with-erlang=$ERL_TOP/release/win32/usr/include \
      --with-win32-curl=/cygdrive/c/path/to/curl/root/directory
      --prefix=$ERL_TOP/release/win32

Note that all paths must be in cygwin format.  Those starting with $ERL_TOP
can be entered literally, assuming ERL_TOP is set as described above.

Relax on your new couch:

  The $ERL_TOP/win32/release directory is now ready to .zip up, be packaged
  by an installer, etc.  To test it in-place, execute:
  
  $ $ERL_TOP/win32/release/bin/couchdb.bat
  
  and everything should work fine.  

Additional Notes:

Building erlang: 
* Follow the instructions as described.  You do need openssl, but don't need
  the GUI tools.  You may like to execute:

    echo "skipping gs" > lib/gs/SKIP
    echo "skipping ic" > lib/ic/SKIP

  To skip them.

* Ensure 'which link' points at the ms linker; one in /usr/bin may be found
  instead.

* After executing './otp_build release -a', be sure to execute Install.exe in
  the release/win32 directory to setup the release/win32/bin dir correctly.

Testing with Erlang
^^^^^^^^^^^^^^^^^^^

First, we need to get a copy of etap to run the tests.

    $ git clone git://github.com/ngerakines/etap.git
    $ cd etap
    $ make && sudo make install

Now we should be able to run the etap test suite:

    $ cd /path/to/couchdb/
    $ make check
    ...
    prove test/etap/*.t
    test/etap/001-load........................ok
    test/etap/010-file-basics.................ok
    ...
    All tests successful.
    Files=28, Tests=363, 41 wallclock secs (...)

Tests are also available to be run individually like such:

    $ ./test/etap/001-load.t
    # Current time local 2009-09-26 23:47:44
    # Using etap version "0.3.4"
    1..39
    ok 1  - Loaded: couch_batch_save
    ...

Cryptographic Software Notice
-----------------------------

   This distribution includes cryptographic software.  The country in 
   which you currently reside may have restrictions on the import, 
   possession, use, and/or re-export to another country, of 
   encryption software.  BEFORE using any encryption software, please 
   check your country's laws, regulations and policies concerning the
   import, possession, or use, and re-export of encryption software, to 
   see if this is permitted.  See <http://www.wassenaar.org/> for more
   information.

   The U.S. Government Department of Commerce, Bureau of Industry and
   Security (BIS), has classified this software as Export Commodity 
   Control Number (ECCN) 5D002.C.1, which includes information security
   software using or performing cryptographic functions with asymmetric
   algorithms.  The form and manner of this Apache Software Foundation
   distribution makes it eligible for export under the License Exception
   ENC Technology Software Unrestricted (TSU) exception (see the BIS 
   Export Administration Regulations, Section 740.13) for both object 
   code and source code.

   The following provides more details on the included cryptographic
   software:
   
   CouchDB includes a HTTP client (ibrowse) with SSL functionality.