-
Notifications
You must be signed in to change notification settings - Fork 8
/
starting-resin-install.xtp
399 lines (368 loc) · 13.3 KB
/
starting-resin-install.xtp
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
<document>
<header>
<product>resin</product>
<version>Resin 4.0</version>
<title>Resin Installation</title>
<description>
<p><b><em>Resin Step-by-Step Installation Guide</em></b>
If you've decided that you're ready to deploy Resin for
production, this page will guide you through the steps
to install this powerful application server system-wide.
You'll see where we recommend installing the various components
of Resin as well as some basic production tuning tips.
</p>
</description>
</header>
<body>
<localtoc/>
<s1 title="Resin Server Installation">
<p><b>This page is for you if you: </b></p>
<ul>
<li>Are evaluating Resin</li>
<li>Want to do local application development with Resin</li>
<li>Have evaluated Resin and are ready to install system-wide</li>
</ul>
<p>
This page leads you step-by-step through the installation of Resin.
After going through these steps, you'll have a full Java and PHP
Application Server able to serve even the most demanding web sites.
</p>
<p><b>You'll learn:</b></p>
<ul>
<li>How to install Resin system-wide</li>
<li>The recommended installation locations for Resin</li>
<li>How to run the Resin administration application</li>
</ul>
<s2 title="Preparing for installation">
<ol>
<li>Install JDK 1.5 or later. You'll need to set the JAVA_HOME
variable in your shell or link /usr/java to the Java home
directory.</li>
<li>Download the latest version of Resin 4 from the <a
href="http://www.caucho.com/download">Resin download page</a>.
Grab the Professional version if:
<ul>
<li>You have purchased a Resin Professional license.</li>
<li>You have obtained an evaluation Resin Professional license.</li>
<li>
You are considering purchasing Resin Professional (without
a license, Resin Professional simply downgrades to the open
source functionality). This will make it easier to upgrade in the
future.
</li>
</ul>
</li>
<li>Unzip or untar the Resin download. If you downloaded Resin
Professional, it will unzip into resin-pro-4.x.x/, otherwise it
will download into resin-4.x.x/.</li>
</ol>
</s2>
<s2 title="Installing Resin on Unix or Mac OS X">
<p>
If you're installing Resin on Windows, you can skip to the next section.
If you're installing Resin on Ubuntu or Debian and want to use the .deb
packaged version of Resin, skip to the end of this section.
</p>
<s3 title="Configuring the build process for Resin">
<p>
Next we'll change into the Resin directory we just unpacked to
configure and build the server. The Java portions of Resin are
already compiled, but this step will build additional C-based
components of Resin that provide additional functionality such as:
</p>
<ul>
<li>A faster IO library, including massive keepalive support *</li>
<li>Support for OpenSSL *</li>
<li>The ability to run as a non-priviledged user for security</li>
<li>Connector modules for Apache</li>
</ul>
<p>
(* only available in Resin Professional)
</p>
<p>
The following command installs Resin and its files into the recommended
locations on the file system:
</p>
<example>
./configure --prefix=/usr/local/resin \
--with-resin-root=/var/www \
--with-resin-log=/var/log/resin \
--with-resin-conf=/etc/resin
</example>
<p>
This will configure Resin to install in <var>/usr/local/resin</var>,
with support for OpenSSL if it was detected, but without support
for Apache. If you want to use Apache or another 3rd party HTTP
server in front of Resin (unrecommended), please take a look
at our <a href="install-3rd-party.xtp">third-party HTTP server
setup documentation</a>. If you need to configure other options
with Resin, now is the time to do it. Please consult the <a
href="reference.xtp">reference to all the configuration options</a>.
</p>
<p>
Once you've run the configuration successfully, the configure script
will display a summary like the following:
</p>
<example>
Resin Configuration summary:
RESIN_HOME: /usr/local/resin
root: /var/www
conf: /etc/resin/conf
log : /var/log/resin
init: /etc/init.d/resin
+ epoll() for keepalives
+ OpenSSL 0.9.8g 19 Oct 2007
OpenSSL include: /usr/include
OpenSSL lib: /usr/lib
OpenSSL libraries: -lssl -lcrypto
JAVA_HOME: /usr/lib/jvm/java-6-sun
+ 32-bit JNI in -I/usr/lib/jvm/java-6-sun/include -I/usr/lib/jvm/java-6-sun/include/linux
JNI CFLAGS: -g -O2 -DPOLL -DEPOLL -D_POSIX_PTHREAD_SEMANTICS -DHAS_SOCK_TIMEOUT -DHAS_JVMTI
</example>
</s3>
<s3 title="Building and Installing Resin">
<p>Now that you've configured the Resin build process, all you need to
do is build and install! To build, just run</p>
<example>
make
</example>
<p>If this step went well, you'll now need to install the Resin files as
the root user:</p>
<example>
sudo make install
</example>
<p>Where ever you install Resin to, we'll refer to that directory as
<b>resin.home</b>.</p>
<p>
If you have a license file for Resin, save it in <var>/usr/local/resin/licenses</var>
</p>
</s3>
<s3 title="Installing Resin using the .deb package on Ubuntu and Debian">
<p>
We provide a Debian packaged version of Resin that Debian and Ubuntu
users can take advantage of. It performs all of the installation
steps above for you and creates all the recommended server and
content directories. Simply download from the <a
href="http://caucho.com/download">Resin download page</a> and install
using dpkg.
</p>
<p>
Alternatively, you can add Caucho's Debian repository to your system's
repositories to use automated update tools like Synaptic and apt-get.
To do this, add the following line to your <var>/etc/apt/sources.list</var>
</p>
<example>
deb http://caucho.com/download/debian unstable multiverse
</example>
<p>
After adding this line, update your local repository cache by running:
</p>
<example>
apt-get update
</example>
<p>
Finally, install Resin Professional using the following:
</p>
<example>
apt-get resin-pro
</example>
<p>
If you have a license file for Resin, save it in <var>/usr/local/resin/licenses</var>
</p>
<p>
Or install Resin Open Source with this command:
</p>
<example>
apt-get resin
</example>
</s3>
</s2>
<s2 title="Installing Resin on Windows">
<p>
The native libraries that are included with Resin are precompiled
for Windows in both 32-bit and 64-bit mode. These libraries provide:
</p>
<ul>
<li>A faster IO library, including massive keepalive support *</li>
<li>Support for OpenSSL *</li>
<li>Connector modules for Apache/IIS</li>
</ul>
<p>
(* only available in Resin Professional)
</p>
<ol>
<li>Download the latest version of Resin 4 from the <a
href="http://www.caucho.com/download">Resin download page</a>.
Grab the Professional version if:
<ul>
<li>You have purchased a Resin Professional license.</li>
<li>You have obtained an evaluation Resin Professional license.</li>
<li>
You are considering purchasing Resin Professional (without
a license, Resin Professional simply downgrades to the open
source functionality). This will make it easier to upgrade in the
future.
</li>
</ul>
</li>
<li>Unzip or untar the Resin download. If you downloaded Resin
Professional, it will unzip into resin-pro-4.x.x\, otherwise it
will download into resin-4.x.x\.
</li>
<li>Move the directory from the previous step to <var>C:\Resin</var>
</li>
<li>Run <var>C:\Resin\setup.exe</var></li>
<li>If you have a license file for Resin, save it in <var>C:\Resin\licenses</var></li>
</ol>
</s2>
</s1>
<s1 title="Resin Content Installation">
<p>Once your have the Resin server installed, you can start installing your
content.</p>
<s2 title="Content from the top down">
<p>Resin and JavaEE organize content into "web applications" or
webapps. As an administrator, your developers have probably provided
you with a webapp in the form of a .war file or a webapp directory.
In the Resin root directory is a special subdirectory named
<code>webapps</code> which is a <b>webapp deploy directory</b>.
Deploying applications in Resin is as easy as copying a .war
file or web application directory to one of these webapp deploy
directories. Resin detects the applications and deploys them
automatically.</p>
<figure src="content-directories.png"/>
<p>
In the directory structure above, notice the special webapp
directories named "ROOT". These will map to the "/" (root)
application. Other webapps will map to their name. For example,
"wordpress" will map to "http://www.example.com/wordpress".
</p>
</s2>
<s2 title="Permanent content locations">
<p>Resin is configured to use the content directory structure show above
by default. In the examples, the Resin <b>root directory</b> is
<var>/var/www</var>. This directory is also the recommended content root
for Unix. For Windows, the recommended content root is <var>C:\www</var>.
To specify the root directory to Resin, you pass it on the
command line when starting the server. For example:
</p>
<example>
java -jar ${resin.home}/lib/resin.jar --root-directory /var/www
</example>
<p>
If you use the Unix startup scripts mentioned in the next section, they
automatically specify the root and log directories.
</p>
</s2>
</s1>
<s1 title="Starting Resin">
<s2 title="Creating Unix startup scripts for Resin">
<p>When you installed using the .deb package or when you ran "make install"
earlier, the installer created a file named <var>/etc/init.d/resin</var>
which contains a standard Unix init.d startup file. This file will start
Resin when invoked as:
</p>
<example>
/etc/init.d/resin start
</example>
<p>Use the tools that came with your system to execute the script
on startup.
</p>
</s2>
<s2 title="Installing Resin as a Windows Service">
<p>
Resin can install itself as a Windows Service by executing the
<var>resin.exe</var> with the <var>-install</var> command line
option. If you pass other options to <var>resin.exe</var> along
with the <var>-install</var> option, such as specifying a server or
content directory, these will be used when the service is started.
To install Resin as a Windows Service using the default options,
simply run:
</p>
<example>
C:\Resin\resin.exe -install
</example>
<p>
You can also install Resin using a specific service name or install
multiple Resin services using the <var>-install-as</var> option:
</p>
<example>
C:\Resin\resin.exe -install-as ResinA
</example>
</s2>
</s1>
<s1 title="Creating a password for the Resin Administration Console">
<p>
One of the most useful tools provided with Resin is the built-in,
web-based administration console. This tool provides detailed
information about the operation of the server, a feature that is
very useful to administrators, but one which must be kept secure from
unauthorized users. </p>
<p>
If you are deploying Resin to a production machine, it's likely
that you won't be running your browser on the same system as the
server. In this case, you'll need to configure Resin to allow
you to access the server remotely.
</p>
<ol>
<li>Edit <var>/etc/resin/resin.xml</var></li>
<li>Change the line:
<example>
<resin:set var="resin_admin_external" value="false"/>
</example>
<p>to</p>
<example>
<resin:set var="resin_admin_external" value="true"/>
</example>
</li>
<li>Save <var>/etc/resin/resin.xml</var> and restart the server.</li>
<li>Replace "localhost" with the name of your host in the URLs below.</li>
</ol>
<p>
Now that you're able to access the administration application,
you have to set up a password and install it. In order to prove
that you have access to the machine on which Resin is running,
the only way to change the password is to create a file with the
authentication information on that machine.
</p>
<ol>
<li>Browse to <var>http://localhost:8080/resin-admin/</var><br/><br/>
</li>
<li>Enter a username and password in the lower half of the page, then
click "Create Configuration File". The recommended username is "admin".
<figure src="admin-password-create.png"/>
</li>
<li>After going to the next page, a new "admin-users.xml.generated"
file has been created for you in the same directory as your
resin.xml file is located. (If you followed the directions above,
this should be in /etc/resin for Unix and C:\Resin\conf for Windows.)
Just rename this file to admin-users.xml and Resin will use it to
<figure src="admin-password-save.png"/>
</li>
<li>Browse back to <var>http://localhost:8080/resin-admin/</var>. The
change you made should force Resin to restart and return a 503 error.
Just hit refresh in a few moments to bring up the page again.</li>
<li>You should now be able to login using the username and password
that you gave above.</li>
</ol>
</s1>
<s1 title="Troubleshooting">
<p>If something went wrong above, the first place to check for problems is
the log.</p>
<ul>
<li>If you are using Unix, look in <var>/var/log/resin/jvm_default.log</var></li>
<li>If you are using Windows, look in <var>C:\Resin\log\jvm_default.log</var></li>
</ul>
<p>Hopefully, the log message will be clear enough for you to figure out the
problem. If not, you have a number of resources available to you to help
you figure out what's going wrong:</p>
<ul>
<li>The <a href="http://maillist.caucho.com/">Resin mailing list</a>.</li>
<li>The <a href="http://forum.caucho.com/">Resin Forums</a>.</li>
<li><a href="mailto:presales@caucho.com">Presales technical support</a> for
those considering purchasing Resin Professional.</li>
<li><a href="http://store.caucho.com/">Paid technical support</a> directly
from the Resin developers.</li>
</ul>
</s1>
</body>
</document>