7
Visit the wiki <http://www.couchdbwiki.com/> for more documentation.
9
4
Building From Subversion
10
5
------------------------
15
To build CouchDB from Subversion you need some of the following installed:
17
* GNU Automake (>=1.6.3) <http://www.gnu.org/software/automake/> (required)
18
* GNU Autoconf (>=2.59) <http://www.gnu.org/software/autoconf/> (required)
19
* GNU Libtool <http://www.gnu.org/software/libtool/> (required)
20
* svn2cl <http://ch.tudelft.nl/~arthur/svn2cl/> (optional)
21
* xsltproc <http://xmlsoft.org/XSLT/xsltproc2.html> (optional)
22
* help2man <http://www.gnu.org/software/help2man/> (optional)
7
You can skip this section if you are installing from a release tarball.
11
To build Apache CouchDB from checkout you need some of the following installed:
13
* [GNU Automake][01] (>=1.6.3) (required)
14
* [GNU Autoconf][02] (>=2.59) (required)
15
* [GNU Libtool][03] (required)
16
* [svn2cl][04] (optional)
17
* [xsltproc][05] (optional)
18
* [help2man][06] (optional)
24
20
If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
25
GNU/Linux) you can install these dependencies using the `apt-get' command:
27
--------------------------------------------------------------------------------
28
apt-get install automake autoconf libtool subversion-tools help2man
29
--------------------------------------------------------------------------------
31
If you are running OS X and have MacPorts <http://www.macports.org/> installed
32
you can install some of these dependencies by using the `port' command:
34
--------------------------------------------------------------------------------
35
port install automake autoconf libtool help2man
36
--------------------------------------------------------------------------------
21
GNU/Linux) you can install these dependencies using the `apt-get` command:
23
apt-get install automake autoconf libtool subversion-tools help2man
25
If you are running OS X and have [MacPorts][07] installed you can install some of
26
these dependencies by using the `port` command:
28
port install automake autoconf libtool help2man
38
30
Note: OS X users should already have Automake, Autoconf and Libtool installed.
40
32
Note: MacPorts users will need to install svn2cl by hand.
45
36
Note: You must repeat this step every time you update your Subversion checkout.
47
Bootstrap the pristine source by running the following command:
49
--------------------------------------------------------------------------------
51
--------------------------------------------------------------------------------
53
You can use the `-C' option to generate a dummy `ChangeLog' file.
38
Follow the [check out instructions][08] and bootstrap the pristine source by
39
running the following command:
43
You can use the `-C` option to generate a dummy `ChangeLog` file.
55
45
Installation And First Run
56
46
--------------------------
58
48
You will need the following installed:
60
* GNU Make <http://www.gnu.org/software/make/> (required)
61
* GNU Compiler Collection <http://gcc.gnu.org/> (required)
62
* ICU <http://icu.sourceforge.net/> (required)
63
* Erlang OTP <http://erlang.org/download.html> (required)
64
* GNU Readline <http://directory.fsf.org/readline.html> (optional)
66
UNIX-like Operating Systems (inc. OS X)
67
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
72
Debian-based (inc. Ubuntu) Systems
73
++++++++++++++++++++++++++++++++++
50
* [Erlang OTP][09] (required)
51
* [ICU][10] (required)
52
* [Mozilla SpiderMonkey][11] (required)
53
* [GNU Make][12] (required)
54
* [GNU Compiler Collection][13] (required)
56
### UNIX-like Operating Systems (inc. OS X) ###
58
#### Dependencies ####
60
##### Debian-based (inc. Ubuntu) Systems #####
75
62
If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
76
GNU/Linux) you can install the dependencies using the `apt-get' command:
78
--------------------------------------------------------------------------------
79
apt-get install build-essential erlang libicu36 libicu36-dev libreadline5-dev
80
--------------------------------------------------------------------------------
82
If you get an error regarding the `libicu36' or `libicu36-dev' be sure to check
83
the version used by your distribution (using `apt-cache search libicu') and
63
GNU/Linux) you can install the dependencies using the `apt-get` command:
65
apt-get install build-essential erlang libicu36 libicu36-dev libmozjs-dev
67
If you get an error regarding the `libicu36` or `libicu36-dev` be sure to check
68
the version used by your distribution (using `apt-cache search libicu`) and
84
69
install those packages instead.
89
73
To install GNU Make and the GNU Compiler Collection on OS X you should install
90
74
the Xcode Tools metapackage by running the following command:
92
--------------------------------------------------------------------------------
93
open /Applications/Installers/Xcode\ Tools/XcodeTools.mpkg
94
--------------------------------------------------------------------------------
96
We recommend that you satisfy the other dependancies by installing MacPorts
97
<http://www.macports.org/> and running the following command:
99
--------------------------------------------------------------------------------
100
port install icu erlang
101
--------------------------------------------------------------------------------
76
open /Applications/Installers/Xcode\ Tools/XcodeTools.mpkg
78
We recommend that you satisfy the other dependancies by installing
79
[MacPorts][07] and running the following command:
81
port install icu erlang spidermonkey
103
83
Note: Don't forget to open a new terminal after you have installed MacPorts
104
as it updates your PATH and you will not be able to run the `port' command
84
as it updates your PATH and you will not be able to run the `port` command
105
85
without the effects of this change.
107
To update your `locate' database you may want to run the following command:
109
--------------------------------------------------------------------------------
110
sudo /usr/libexec/locate.updatedb
111
--------------------------------------------------------------------------------
87
To update your `locate` database you may want to run the following command:
89
sudo /usr/libexec/locate.updatedb
116
93
Once you have satisfied dependencies you should run the following command:
118
--------------------------------------------------------------------------------
120
--------------------------------------------------------------------------------
122
Note: CouchDB is installed into `/usr/local' by default. If you want to change
123
where CouchDB is installed (or where to find Erlang) be sure to read the output
124
from running the `./configure --help' command.
126
Note: All the examples assume you have installed into `/usr/local'.
97
Note: Apache CouchDB is installed into `/usr/local` by default. If you want to
98
change where Apache CouchDB is installed (or where to find Erlang) be sure to
99
read the output from running the `./configure --help` command.
101
Note: All the examples assume you have installed into `/usr/local`.
128
103
If everything was successful you should see the following message:
130
--------------------------------------------------------------------------------
131
You have configured CouchDB. Time to relax.
132
--------------------------------------------------------------------------------
105
You have configured Apache CouchDB. Time to relax.
136
To install CouchDB you should then run the following command:
138
--------------------------------------------------------------------------------
139
make && sudo make install
140
--------------------------------------------------------------------------------
142
If you do not wish to be prompted to overwrite any existing CouchDB
109
To install Apache CouchDB you should then run the following command:
111
make && sudo make install
113
If you do not wish to be prompted to overwrite any existing Apache CouchDB
143
114
configuration files you should run the following command:
145
--------------------------------------------------------------------------------
146
sudo make && yes | sudo make install
147
--------------------------------------------------------------------------------
116
sudo make && yes | sudo make install
149
Note: Use of the `sudo' command is only required if you are installing into a
118
Note: Use of the `sudo` command is only required if you are installing into a
150
119
system owned directory. You do not need to do this if you are installing
151
120
elsewhere, such as your home directory.
153
More options can be found by reading the `INSTALL' file.
155
Security Considerations
156
^^^^^^^^^^^^^^^^^^^^^^^
158
It is not advisable to run CouchDB as the superuser. We strongly recommend that
159
you create a specific user to run CouchDB and own the data/log directories.
161
You can use whatever tool your system provides to create a new `couchdb' user.
122
More options can be found by reading the `INSTALL` file.
124
#### Security Considerations ####
126
It is not advisable to run Apache CouchDB as the superuser. We strongly
127
recommend that you create a specific user to run Apache CouchDB and own the
128
data/log directories.
130
You can use whatever tool your system provides to create a new `couchdb` user.
163
132
On many UNIX-like systems you can run the following command:
165
--------------------------------------------------------------------------------
167
--------------------------------------------------------------------------------
169
136
OS X provides the standard Accounts option from the System Preferences
170
137
application or you can optionally use the Workgroup Manager application which
171
can be downloaded as part of the Server Admin Tools
172
<http://www.apple.com/support/downloads/serveradmintools1047.html>.
174
You should set the home directory of the `couchdb' user to
175
`/usr/local/var/lib/couchdb' which is the CouchDB database directory.
177
Make sure to change the ownership of the CouchDB data directories by running
178
the following commands:
180
--------------------------------------------------------------------------------
181
chown -R couchdb /usr/local/var/lib/couchdb
182
chown -R couchdb /usr/local/var/log/couchdb
183
--------------------------------------------------------------------------------
188
To start the CouchDB server you should run the following command:
190
--------------------------------------------------------------------------------
191
sudo -u couchdb couchdb
192
--------------------------------------------------------------------------------
194
This uses the `sudo' command to run the `couchdb' command as the `couchdb' user.
196
When CouchDB starts it should eventually display the following message:
198
--------------------------------------------------------------------------------
199
CouchDB has started. Time to relax.
200
--------------------------------------------------------------------------------
138
can be downloaded as part of the [Server Admin Tools][14].
140
You should set the home directory of the `couchdb` user to
141
`/usr/local/var/lib/couchdb` which is the Apache CouchDB database directory.
143
Make sure to change the ownership of the Apache CouchDB data directories by
144
running the following commands:
146
chown -R couchdb /usr/local/var/lib/couchdb
147
chown -R couchdb /usr/local/var/log/couchdb
149
#### Running Manually ####
151
To start the Apache CouchDB server you should run the following command:
153
sudo -u couchdb couchdb
155
This uses the `sudo` command to run the `couchdb` command as the `couchdb` user.
157
When Apache CouchDB starts it should eventually display the following message:
159
Apache CouchDB has started. Time to relax.
204
163
To check that everything has worked point your web browser to
205
<http://localhost:5984/_utils/index.html> and run the test suite.
210
If you get error when running CouchDB that look like the following:
212
--------------------------------------------------------------------------------
213
dyld: Library not loaded: libicuuc.38.dy
214
--------------------------------------------------------------------------------
216
You should make sure that your `~/.profile' file contains the following line:
218
--------------------------------------------------------------------------------
219
export DYLD_LIBRARY_PATH=/opt/local/lib:$DYLD_LIBRARY_PATH
220
--------------------------------------------------------------------------------
164
[http://localhost:5984/_utils/index.html][15] and run the test suite.
168
If you get error when running Apache CouchDB that look like the following:
170
dyld: Library not loaded: libicuuc.38.dy
172
You should make sure that your `~/.profile` file contains the following line:
174
export DYLD_LIBRARY_PATH=/opt/local/lib:$DYLD_LIBRARY_PATH
222
176
This should have been added for you by MacPorts but may be missing.
178
#### Running as a Daemon ####
227
Note: These instructions assume you have created the `couchdb' user. See the
180
Note: These instructions assume you have created the `couchdb` user. See the
228
181
specific system information included below to learn how to reconfigure this.
230
Note: If any of these methods report a failure you can run the `couchdb'
183
Note: If any of these methods report a failure you can run the `couchdb`
231
184
command manually to see the error messages it is displaying.
233
The `/usr/local/etc/logrotate.d/couchdb' file is provided as a logrotate
234
configuration that you can use to rotate CouchDB's logs.
236
SysV/BSD-style Systems
237
++++++++++++++++++++++
239
Depending on your system the `couchdb' init script will be installed into a
240
direcory called `init.d' (for SysV-style systems) or `rc.d' (for BSD-style
241
systems). These examples use the `[init.d|rc.d]' notation to indicate this.
243
You can control the CouchDB daemon by running the following command:
245
--------------------------------------------------------------------------------
246
/usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|force-reload|status]
247
--------------------------------------------------------------------------------
186
The `/usr/local/etc/logrotate.d/couchdb` file is provided as a logrotate
187
configuration that you can use to rotate Apache CouchDB's logs.
189
##### SysV/BSD-style Systems #####
191
Depending on your system the `couchdb` init script will be installed into a
192
direcory called `init.d` (for SysV-style systems) or `rc.d` (for BSD-style
193
systems). These examples use the `[init.d|rc.d]` notation to indicate this.
195
You can control the Apache CouchDB daemon by running the following command:
197
/usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|force-reload|status]
249
199
If you wish to configure how the init script works, such as which user to run
250
CouchDB as, you must edit the `/usr/local/etc/default/couchdb' file as
200
Apache CouchDB as, you must edit the `/usr/local/etc/default/couchdb` file as
251
201
appropriate. If you are running the init script as a non-superuser you need to
252
remove the line with the `COUCHDB_USER' setting.
202
remove the line with the `COUCHDB_USER` setting.
254
If you wish the CouchDB daemon to run as a system service you need to copy the
255
`/usr/local/etc/[init.d|rc.d]/couchdb' script into your system wide
256
`/etc/[init.d|rc.d]' directory and update your system configuration as
204
If you wish the ApacheCouchDB daemon to run as a system service you need to copy
205
the `/usr/local/etc/[init.d|rc.d]/couchdb` script into your system wide
206
`/etc/[init.d|rc.d]` directory and update your system configuration as
257
207
appropriate. Consult your system documentation for more information.
259
209
If you are running a Debian GNU/Linux system (or a derivative such as Ubuntu
260
210
GNU/Linux) you can configure your system using the following command:
262
--------------------------------------------------------------------------------
263
sudo update-rc.d couchdb defaults
264
--------------------------------------------------------------------------------
269
You can use the `launchctl' command to control the CouchDB daemon.
212
sudo update-rc.d couchdb defaults
216
You can use the `launchctl` command to control the Apache CouchDB daemon.
271
218
To load the launchd configuration you must run the following command:
273
--------------------------------------------------------------------------------
274
sudo launchctl load /usr/local/Library/LaunchDaemons/org.couchdb.couchdb
275
--------------------------------------------------------------------------------
277
You can stop the CouchDB daemon by running the following command:
279
--------------------------------------------------------------------------------
280
sudo launchctl unload /usr/local/Library/LaunchDaemons/org.couchdb.couchdb
281
--------------------------------------------------------------------------------
220
sudo launchctl load /usr/local/Library/LaunchDaemons/org.apache.couchdb
222
You can stop the Apache CouchDB daemon by running the following command:
224
sudo launchctl unload /usr/local/Library/LaunchDaemons/org.apache.couchdb
283
226
If you wish to change the launchd configuration, such as which user to run
284
CouchDB as, you must edit the
285
`/usr/local/Library/LaunchDaemons/org.couchdb.couchdb.plist' file as
227
Apache CouchDB as, you must edit the
228
`/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist` file as
288
If you wish the CouchDB daemon to run as a system service you need to copy the
289
`/usr/local/Library/LaunchDaemons/org.couchdb.couchdb.plist' file into your
290
system wide `/Library/LaunchDaemons' directory.
231
If you wish the Apache CouchDB daemon to run as a system service you need to
232
copy the `/usr/local/Library/LaunchDaemons/org.apache.couchdb.plist` file into
233
your system wide `/Library/LaunchDaemons` directory.
295
237
Windows documentation is incomplete. Please submit suggestions.
297
Development and Distribution
298
----------------------------
300
Reconfiguring the Build System
301
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
242
### Reconfiguring the Build System ###
303
244
If you have edited any of the files used by the build system, such as the
304
`Makefile.am' files, you will need to reconfigure your source.
245
`Makefile.am` files, you will need to reconfigure your source.
306
247
To reconfigure the source run the following command from the root directory:
308
--------------------------------------------------------------------------------
309
autoreconf && ./confgure
310
--------------------------------------------------------------------------------
249
autoreconf && ./confgure
251
### Checking In Changes ###
315
253
If your source directory has been configured or built you will need to clean
316
254
the generated files before checking into the repository by running the
317
255
following command:
319
--------------------------------------------------------------------------------
321
--------------------------------------------------------------------------------
323
259
If everything was successful you should now have a pristine checkout.
325
Preparing For Distribution
326
~~~~~~~~~~~~~~~~~~~~~~~~~~
261
### Preparing For Distribution ###
328
263
To build the source for distribution you should then run the following command:
330
--------------------------------------------------------------------------------
331
./configure && make distcheck
332
--------------------------------------------------------------------------------
265
./configure && make distcheck
334
If everything was successful you should see a `zip' file and/or a `tar.gz' file
267
If everything was successful you should see a `zip` file and/or a `tar.gz` file
335
268
sitting in the root directory ready for distribution.
340
1. Update this file with important information.
341
2. Update the `NEWS' file with change information.
342
3. Update the `acinclude.m4' file with version information.
270
### Release Checklist ###
272
1. Update the `README` file with important information.
273
2. Update the `NEWS` file with change information.
274
3. Update the `acinclude.m4` file with version information.
276
[01]: http://www.gnu.org/software/automake/
277
[02]: http://www.gnu.org/software/autoconf/
278
[03]: http://www.gnu.org/software/libtool/
279
[04]: http://ch.tudelft.nl/~arthur/svn2cl/
280
[05]: http://xmlsoft.org/XSLT/xsltproc2.html
281
[06]: http://www.gnu.org/software/help2man/
282
[07]: http://www.macports.org/
283
[08]: http://incubator.apache.org/couchdb/community/code.html
284
[09]: http://erlang.org/
285
[10]: http://icu.sourceforge.net/
286
[11]: http://www.mozilla.org/js/spidermonkey/
287
[12]: http://www.gnu.org/software/make/
288
[13]: http://gcc.gnu.org/
289
[14]: http://www.apple.com/support/downloads/serveradmintools1047.html
290
[15]: http://localhost:5984/_utils/index.html
added
removed
README
