Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 269 lines (153 sloc) 7.108 kb
f3303f2 @nslater documentation improvements
nslater authored
1 Apache CouchDB README.Unix
2 ==========================
3
4 A high-level guide to Unix-like systems, inc. Mac OS X and Ubuntu.
df02faf @nslater initial round of documentation changes
nslater authored
5
cc48641 @nslater improved documentation with regard to troublshooting, wiki, and maili…
nslater authored
6 Troubleshooting
7 ---------------
8
9 There is a troubleshooting guide:
10
11 http://wiki.apache.org/couchdb/Troubleshooting
12
13 There is a wiki for general documentation:
14
15 http://wiki.apache.org/couchdb/
16
17 There are collection of friendly mailing lists:
18
19 http://couchdb.apache.org/community/lists.html
20
21 Please work through these in order if you experience any problems.
22
df02faf @nslater initial round of documentation changes
nslater authored
23 Dependencies
24 ------------
25
cc48641 @nslater improved documentation with regard to troublshooting, wiki, and maili…
nslater authored
26 You should have the following installed:
df02faf @nslater initial round of documentation changes
nslater authored
27
f3303f2 @nslater documentation improvements
nslater authored
28 * Erlang OTP (>=R12B5) (http://erlang.org/)
29 * ICU (http://icu.sourceforge.net/)
30 * OpenSSL (http://www.openssl.org/)
ee00d81 @tilgovi Minor doc and configure fixes for old JS engines
tilgovi authored
31 * Mozilla SpiderMonkey (1.7) (http://www.mozilla.org/js/spidermonkey/)
f3303f2 @nslater documentation improvements
nslater authored
32 * GNU Make (http://www.gnu.org/software/make/)
33 * GNU Compiler Collection (http://gcc.gnu.org/)
df7ac13 @davisp CouchDB no longer requires cURL to build.
davisp authored
34 * libcurl (http://curl.haxx.se/libcurl/)
cc48641 @nslater improved documentation with regard to troublshooting, wiki, and maili…
nslater authored
35 * help2man (http://www.gnu.org/s/help2man/)
df7ac13 @davisp CouchDB no longer requires cURL to build.
davisp authored
36
cc48641 @nslater improved documentation with regard to troublshooting, wiki, and maili…
nslater authored
37 It is recommended that you install Erlang OTP R12B-5 or above where possible.
38 You will only need libcurl if you plan to run the JavaScript test suite. And
39 help2man is only need if you plan on installing the CouchDB man pages.
df02faf @nslater initial round of documentation changes
nslater authored
40
5fc1e70 @janl add link to the wiki about the messed up ubuntu install situation. Cl…
janl authored
41 Ubuntu
42 ~~~~~~
43
cc48641 @nslater improved documentation with regard to troublshooting, wiki, and maili…
nslater authored
44 For up to date instructions, please see:
5fc1e70 @janl add link to the wiki about the messed up ubuntu install situation. Cl…
janl authored
45
46 http://wiki.apache.org/couchdb/Installing_on_Ubuntu
47
cc48641 @nslater improved documentation with regard to troublshooting, wiki, and maili…
nslater authored
48 Unfortunately, it seems that installing dependancies on Ubuntu is troublesome.
5fc1e70 @janl add link to the wiki about the messed up ubuntu install situation. Cl…
janl authored
49
50 Debian-based Systems
51 ~~~~~~~~~~~~~~~~~~~~
df02faf @nslater initial round of documentation changes
nslater authored
52
53 You can install the build tools by running:
54
55 sudo apt-get install build-essential
56
57 You can install the other dependencies by running:
58
59 sudo apt-get install erlang libicu-dev libmozjs-dev libcurl4-openssl-dev
60
61 Be sure to update the version numbers to match your system's available packages.
62
63 Mac OS X
64 ~~~~~~~~
65
66 You can install the build tools by running:
67
68 open /Applications/Installers/Xcode\ Tools/XcodeTools.mpkg
69
70 You can install the other dependencies by running:
71
6b19905 @janl recommend Homebrew over MacPorts
janl authored
72 brew install erlang icu4c spidermonkey curl
df02faf @nslater initial round of documentation changes
nslater authored
73
d7cbddc @nslater updated INSTALL.Unix instructions for homebrew on Mac OS X
nslater authored
74 You may want to link ICU so that CouchDB can find the header files automatically:
75
76 brew link icu4c
77
78 The same is true for recent versions of Erlang:
79
80 brew link erlang
81
6b19905 @janl recommend Homebrew over MacPorts
janl authored
82 You will need Homebrew installed to use the `brew` command.
83
cc48641 @nslater improved documentation with regard to troublshooting, wiki, and maili…
nslater authored
84 Learn more about Homebrew at:
85
86 http://mxcl.github.com/homebrew/
87
88 Some versions of Mac OS X ship a problematic OpenSSL library. If you're
89 experiencing troubles with CouchDB crashing intermittently with a segmentation
90 fault or a bus error, you will need to install your own version of OpenSSL. See
91 the troubleshooting guide, mentioned above, for more information.
df02faf @nslater initial round of documentation changes
nslater authored
92
93 Installing
94 ----------
95
96 Once you have satisfied the dependencies you should run:
97
98 ./configure
99
100 This script will configure CouchDB to be installed into `/usr/local` by default.
101
102 If you wish to customise the installation, pass `--help` to this script.
103
104 If everything was successful you should see the following message:
105
106 You have configured Apache CouchDB, time to relax.
107
108 Relax.
109
110 To install CouchDB you should run:
111
112 make && sudo make install
113
114 You only need to use `sudo` if you're installing into a system directory.
115
116 Try `gmake` if `make` is giving you any problems.
117
118 If everything was successful you should see the following message:
119
120 You have installed Apache CouchDB, time to relax.
121
122 Relax.
123
f3303f2 @nslater documentation improvements
nslater authored
124 First Run
125 ---------
126
127 You can start the CouchDB server by running:
128
129 sudo -i -u couchdb couchdb
130
131 This uses the `sudo` command to run the `couchdb` command as the `couchdb` user.
132
133 When CouchDB starts it should eventually display the following message:
134
135 Apache CouchDB has started, time to relax.
136
137 Relax.
138
139 To check that everything has worked, point your web browser to:
140
141 http://127.0.0.1:5984/_utils/index.html
142
cc48641 @nslater improved documentation with regard to troublshooting, wiki, and maili…
nslater authored
143 From here you should run the test suite in Firefox.
f3303f2 @nslater documentation improvements
nslater authored
144
df02faf @nslater initial round of documentation changes
nslater authored
145 Security Considerations
146 -----------------------
147
148 You should create a special `couchdb` user for CouchDB.
149
150 On many Unix-like systems you can run:
151
152 adduser --system \
153 --home /usr/local/var/lib/couchdb \
154 --no-create-home \
155 --shell /bin/bash \
156 --group --gecos \
157 "CouchDB Administrator" couchdb
158
159 On Mac OS X you can use the Workgroup Manager to create users:
160
161 http://www.apple.com/support/downloads/serveradmintools1047.html
162
163 You must make sure that:
164
165 * The user has a working POSIX shell
166
167 * The user's home directory is `/usr/local/var/lib/couchdb`
168
169 You can test this by:
170
171 * Trying to log in as the `couchdb` user
172
173 * Running `pwd` and checking the present working directory
174
175 Change the ownership of the CouchDB directories by running:
176
177 chown -R couchdb:couchdb /usr/local/etc/couchdb
178 chown -R couchdb:couchdb /usr/local/var/lib/couchdb
179 chown -R couchdb:couchdb /usr/local/var/log/couchdb
180 chown -R couchdb:couchdb /usr/local/var/run/couchdb
181
182 Change the permission of the CouchDB directories by running:
183
184 chmod 0770 /usr/local/etc/couchdb
185 chmod 0770 /usr/local/var/lib/couchdb
186 chmod 0770 /usr/local/var/log/couchdb
187 chmod 0770 /usr/local/var/run/couchdb
188
189 Running as a Daemon
190 -------------------
191
192 SysV/BSD-style Systems
193 ~~~~~~~~~~~~~~~~~~~~~~
194
195 You can use the `couchdb` init script to control the CouchDB daemon.
196
197 On SysV-style systems, the init script will be installed into:
198
199 /usr/local/etc/init.d
200
201 On BSD-style systems, the init script will be installed into:
202
203 /usr/local/etc/rc.d
204
205 We use the `[init.d|rc.d]` notation to refer to both of these directories.
206
207 You can control the CouchDB daemon by running:
208
209 /usr/local/etc/[init.d|rc.d]/couchdb [start|stop|restart|status]
210
211 If you wish to configure how the init script works, you can edit:
212
213 /usr/local/etc/default/couchdb
214
215 Comment out the `COUCHDB_USER` setting if you're running as a non-superuser.
216
217 To start the daemon on boot, copy the init script to:
218
219 /etc/[init.d|rc.d]
220
221 You should then configure your system to run the init script automatically.
222
223 You may be able to run:
224
225 sudo update-rc.d couchdb defaults
226
227 If this fails, consult your system documentation for more information.
228
229 A `logrotate` configuration is installed into:
230
231 /usr/local/etc/logrotate.d/couchdb
232
233 Consult your `logrotate` documentation for more information.
234
235 It is critical that the CouchDB logs are rotated so as not to fill your disk.
236
237 Mac OS X
238 ~~~~~~~~
239
240 You can use the `launchctl` command to control the CouchDB daemon.
241
242 You can load the configuration by running:
243
244 sudo launchctl load \
245 /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
246
247 You can stop the CouchDB daemon by running:
248
249 sudo launchctl unload \
250 /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
251
252 You can start CouchDB by running:
253
254 sudo launchctl start org.apache.couchdb
255
256 You can restart CouchDB by running:
257
258 sudo launchctl stop org.apache.couchdb
259
260 You can edit the launchd configuration by running:
261
262 open /usr/local/Library/LaunchDaemons/org.apache.couchdb.plist
263
264 To start the daemon on boot, copy the configuration file to:
265
266 /Library/LaunchDaemons
267
268 Consult your system documentation for more information.
Something went wrong with that request. Please try again.