forked from apache/couchdb
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
266 lines (171 loc) · 9.24 KB
/
README
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
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.
Apache CouchDB is an effort undergoing incubation at the Apache Software
Foundation (ASF), sponsored by the Apache Incubator PMC. Incubation is required
of all newly accepted projects until a further review indicates that the
infrastructure, communications, and decision making process have stabilized in a
manner consistent with other successful ASF projects. While incubation status is
not necessarily a reflection of the completeness or stability of the code, it
does indicate that the project has yet to be fully endorsed by the ASF.
Building From Subversion
------------------------
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) (required) (http://www.gnu.org/software/automake/)
* GNU Autoconf (>=2.59) (required) (http://www.gnu.org/software/autoconf/)
* GNU Libtool (required) (http://www.gnu.org/software/libtool/)
* help2man (optional) (http://www.gnu.org/software/help2man/)
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 help2man
The OS X version of these dependencies may be out of date so it is recommended
that you use MacPorts (http://www.macports.org/) to install newer versions using
the `port` command:
port install automake autoconf libtool help2man
Bootstrapping
~~~~~~~~~~~~~
Note: You must repeat this step every time you update your Subversion checkout.
Bootstrap the pristine source by running the following command:
./bootstrap
Installation And First Run
--------------------------
You will need the following installed:
* Erlang OTP (>=R11B) (required) (http://erlang.org/)
* ICU (required) (http://icu.sourceforge.net/)
* OpenSSL (required) (http://www.openssl.org/)
* Mozilla SpiderMonkey (required) (http://www.mozilla.org/js/spidermonkey/)
* GNU Make (required) (http://www.gnu.org/software/make/)
* GNU Compiler Collection (required) (http://gcc.gnu.org/)
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 libicu38 libicu-dev libmozjs-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.
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][07] 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.
If you are having problems running `make` you may want to try running `gmake` if
it 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 the following command:
adduser --system --home /usr/local/var/lib/couchdb --no-create-home \
--shell /bin/bash --group --gecos "CouchDB Administrator" 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 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.
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 -i -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. See http://127.0.0.1:5984/_utils/index.html
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.
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.