root/docs/resin-guide.xml

Revision 2512, 11.0 kB (checked in by nelchael, 2 years ago)

Fixes by rane :)

Line 
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link="/proj/en/java/resin-guide.xml">
6 <title>Resin Guide</title>
7
8 <author title="Author">
9   <mail link="nelchael@gentoo.org">Krzysiek Pawlik</mail>
10 </author>
11
12 <abstract>
13 This guide provides some basic information about how Resin server is handled on
14 Gentoo.
15 </abstract>
16
17 <!-- The content of this document is licensed under the CC-BY-SA license -->
18 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
19 <license/>
20
21 <version>1.0</version>
22 <date>2006-07-18</date>
23
24 <chapter>
25 <title>Introduction</title>
26 <section>
27 <body>
28
29 <p>
30 Resin is now installed on Gentoo in a different way than it used to be. This
31 document will describe how to install a new version of Resin, configure it and
32 finally run it. This guide is based on version 3.0.19 of Resin, older server
33 versions should not be used.
34 </p>
35
36 <p>
37 Resin is installed on Gentoo in multiple directories due to Gentoo trying to
38 comply with FHS.
39 </p>
40
41 <p>
42 New Java system is required for compiling and running Resin due to its
43 requirement of JDK 1.5. <uri link="/proj/en/java/java-upgrade.xml">Upgrade
44 guide</uri> can be found on Java Project pages.
45 </p>
46
47 </body>
48 </section>
49 </chapter>
50
51 <chapter>
52 <title>Layout</title>
53 <section>
54 <title>Standard Resin layout</title>
55 <body>
56
57 <p>
58 Resin binary distribution has following directory structure:
59 </p>
60
61 <pre caption="Resin directory structure">
62 /opt/resin/bin
63 /opt/resin/conf
64 /opt/resin/lib
65 /opt/resin/libexec
66 /opt/resin/log
67 /opt/resin/logs
68 /opt/resin/webapps
69 </pre>
70
71 </body>
72 </section>
73 <section>
74 <title>Gentoo Resin layout</title>
75 <body>
76
77 <p>
78 To comply with FHS, Resin on Gentoo is installed in the following directories:
79 </p>
80
81 <pre caption="Resin directory structure">
82 /usr/lib/resin/bin
83 /etc/resin
84 /usr/share/resin/lib
85 /usr/lib/resin/libexec
86 /var/log/resin
87 /var/lib/resin/webapps
88 </pre>
89
90 </body>
91 </section>
92 <section>
93 <title>Configuration Files</title>
94 <body>
95
96 <p>
97 In addition to <path>/etc/resin</path>, where server's main configuration file
98 is kept (<path>resin.xml</path>), on Gentoo Resin has also the
99 <path>/etc/conf.d/resin</path> file which contains variables used by
100 <path>/etc/init.d/resin</path> during server startup. These variables are:
101 </p>
102
103 <ul>
104   <li><c>JAVA_HOME</c>: allows to change VM under which Resin will be run</li>
105   <li>
106     <c>JAVA_OPTS</c>: additional parameters passed to VM (like memory settings)
107   </li>
108   <li>
109     <c>RESIN_HOME</c>: server root, default is <path>/usr/lib/resin</path>
110   </li>
111   <li>
112     <c>RESIN_OUT</c>: location of Resin stdout log, default is
113     <path>/var/log/resin/resin_out.log</path>
114   </li>
115   <li>
116     <c>RESIN_ERR</c>: location of Resin error log, default is
117     <path>/var/log/resin/resin_err.log</path>
118   </li>
119   <li>
120     <c>CLASSPATH</c>: default is <c>$(java-config -p
121     resin,iso-relax,aopalliance-1)</c>
122   </li>
123   <li><c>RESIN_START</c>: default is "start"</li>
124   <li><c>RESIN_STOP</c>: default is "stop"</li>
125 </ul>
126
127 </body>
128 </section>
129 <section>
130 <title>Web Applications</title>
131 <body>
132
133 <p>
134 By default, web applications are located in
135 <path>/var/lib/resin/webapps</path>, but <path>resin.xml</path> allows to
136 specify different paths for different web applications.
137 </p>
138
139 </body>
140 </section>
141 <section>
142 <title>Runtime Files</title>
143 <body>
144
145 <p>
146 These directories are used by Resin in the run time:
147 </p>
148
149 <ul>
150   <li><path>/var/log/resin</path></li>
151   <li><path>/var/run/resin</path></li>
152 </ul>
153
154 <p>
155 Resin expects to be able to create directories in <path>WEB-INF</path>
156 directory in each web application. These directories are used to cache compiled
157 JSP pages and temporary files.
158 </p>
159
160 </body>
161 </section>
162 </chapter>
163
164 <chapter>
165 <title>Installation</title>
166 <section>
167 <title>Documentation</title>
168 <body>
169
170 <p>
171 Documentation for Resin will be installed in the default web applications
172 location only if the <c>doc</c> USE flag is set.
173 </p>
174
175 </body>
176 </section>
177 <section>
178 <title>Installing Resin</title>
179 <body>
180
181 <p>
182 Resin can be installed using <c>emerge</c>, just like any other package in
183 Gentoo:
184 </p>
185
186 <pre caption="Installing Resin">
187 # <i>emerge resin</i>
188 </pre>
189
190 <warn>
191 If previous version of Resin was installed, it is recommended to uninstall it
192 and remove <e>resin</e> user with <c>userdel</c> command before installing
193 newer version. Home directory for user <e>resin</e> should to be set to
194 <path>/usr/lib/resin</path> and not to <path>/opt/resin</path>.
195 </warn>
196
197 </body>
198 </section>
199 </chapter>
200
201 <chapter>
202 <title>Usage</title>
203 <section>
204 <title>Configuring Resin</title>
205 <body>
206
207 <p>
208 Default <path>resin.xml</path> is enough to run Resin and be able to browse
209 http://localhost:8080/. Resin in Gentoo has two main configuration files:
210 <path>/etc/conf.d/resin</path> and <path>/etc/resin/resin.xml</path>.
211 </p>
212
213 </body>
214 </section>
215 <section>
216 <title>/etc/conf.d/resin</title>
217 <body>
218
219 <p>
220 This file allows to tune Resin startup parameters. The most important for now
221 is the <c>JAVA_HOME</c> variable which has to be set to any version 1.5 JDK:
222 </p>
223
224 <pre caption="Setting JAVA_HOME">
225 JAVA_HOME=/opt/sun-jdk-1.5.0.07/
226 </pre>
227
228 </body>
229 </section>
230 <section>
231 <title>/etc/resin/resin.xml</title>
232 <body>
233
234 <p>
235 Every tag used in resin.xml is very well documented in <uri
236 link="http://www.caucho.com/resin-3.0/index.xtp">Resin documentation</uri>.
237 Only one tag will be described here, as complete documentation for Resin is
238 beyond scope of this document.
239 </p>
240
241 <p>
242 To configure additional web applications following tag has to be added to
243 &lt;host&gt;:
244 </p>
245
246 <pre caption="Adding web application">
247 &lt;web-app
248 id="/mywebapp"
249 document-directory="/home/me/webapps/mywebapp"
250 redeploy-mode="automatic" /&gt;
251 </pre>
252
253 <p>
254 What it means:
255 </p>
256
257 <ul>
258   <li>
259     id: web application id, it will be available under http://localhost:8080/id
260   </li>
261   <li>
262     document-directory: specifies where to look for directory containing web
263     application
264   </li>
265   <li>
266     redeploy-mode: specifies if the web application should be automatically
267     restarted after any of its files are changed, be sure to turn it off on
268     production servers
269   </li>
270 </ul>
271
272 <warn>
273 <path>WEB-INF</path> directory in web application should be writable by
274 <e>resin</e> user.
275 </warn>
276
277 </body>
278 </section>
279 <section>
280 <title>Starting/Stopping Resin</title>
281 <body>
282
283 <p>
284 After Resin was configured, it is ready to be started:
285 </p>
286
287 <pre caption="Starting Resin">
288 # <i>/etc/init.d/resin start</i>
289 </pre>
290
291 <p>
292 If, after a few seconds, web page at <uri>http://localhost:8080/</uri> is not
293 available, you should check <path>/var/log/resin/resin_err.log</path> for
294 errors.
295 </p>
296
297 <p>
298 Resin's init script supports standard actions like <c>start</c>, <c>stop</c>,
299 <c>restart</c> and <c>status</c>.
300 </p>
301
302 </body>
303 </section>
304 </chapter>
305
306 <chapter>
307 <title>Resin with Apache</title>
308 <section>
309 <title>Why use Resin with Apache</title>
310 <body>
311
312 <p>
313 Using Resin with Apache allows many new possibilities:
314 </p>
315
316 <ul>
317   <li>Clustering and load balancing</li>
318   <li>Faster SSL using OpenSSL in Apache</li>
319   <li>Running web services on port 80</li>
320 </ul>
321
322 </body>
323 </section>
324 <section>
325 <title>Requirements</title>
326 <body>
327
328 <p>
329 mod_caucho requires Apache 2 and will install it as a dependency if it wasn't
330 already installed:
331 </p>
332
333 <pre caption="Installing mod_caucho">
334 # <i>emerge mod_caucho</i>
335 </pre>
336
337 </body>
338 </section>
339 <section>
340 <title>Configuring Resin</title>
341 <body>
342
343 <p>
344 In <path>/etc/resin/resin.xml</path> look for <e>&lt;cluster&gt;</e> tag. If
345 Resin is running on different machine than Apache, be sure to set the
346 <c>host</c> attribute in <c>&lt;srun&gt;</c> tag to bind to public IP address,
347 not the loopback interface (127.0.0.1).
348 </p>
349
350 <pre caption="&lt;cluster&gt; example">
351 &lt;http server-id="" host="*" port="8001"/&gt;
352
353 &lt;cluster&gt;
354 &lt;srun server-id="" host="10.0.0.1" port="6801"/&gt;
355 &lt;/cluster&gt;
356 </pre>
357
358 </body>
359 </section>
360 <section>
361 <title>Configuring Apache</title>
362 <body>
363
364 <p>
365 To enable mod_caucho, add <c>-D CAUCHO</c> to <c>APACHE2_OPTS</c> in
366 <path>/etc/conf.d/resin</path>.
367 </p>
368
369 <p>
370 To add Resin servers to mod_caucho, edit the
371 <path>/etc/apache2/modules.d/88_mod_caucho.conf</path> file and add one
372 <c>ResinConfigServer</c> for each server. After restarting Apache check
373 <uri>http://localhost/caucho-status</uri> to see cluster status.
374 </p>
375
376 <pre caption="88_mod_caucho.conf example">
377 LoadModule caucho_module modules/mod_caucho.so
378
379 ResinConfigServer 10.0.0.1 6801
380
381 CauchoStatus yes
382 </pre>
383
384 </body>
385 </section>
386 </chapter>
387
388 <chapter>
389 <title>JNDI</title>
390 <section>
391 <title>Setting up JNDI for database access</title>
392 <body>
393
394 <p>
395 Main difference in setting up JNDI for database access in Resin is the
396 <c>&lt;driver&gt;</c> tag which must specify a driver class, not the generic
397 <path>javax.sql</path> interface.
398 </p>
399
400 <pre caption="Example of JNDI configuration">
401 &lt;database&gt;
402 &lt;jndi-name&gt;jdbc/project&lt;/jndi-name&gt;
403 &lt;driver type="org.postgresql.Driver"&gt;
404 &lt;url&gt;jdbc:postgresql://127.0.0.1/project_database&lt;/url&gt;
405 &lt;user&gt;nelchael&lt;/user&gt;
406 &lt;password&gt;&lt;/password&gt;
407 &lt;/driver&gt;
408 &lt;prepared-statement-cache-size&gt;8&lt;/prepared-statement-cache-size&gt;
409 &lt;max-connections&gt;20&lt;/max-connections&gt;
410 &lt;max-idle-time&gt;30s&lt;/max-idle-time&gt;
411 &lt;/database
412 </pre>
413
414 <p>
415 Tomcat users should specify the type to be <e>javax.sql.DataSource</e>. For
416 more information about database access and JNDI see the <uri
417 link="http://www.caucho.com/resin-3.0/db/config.xtp#Basic-Configuration">Database
418 Configuration</uri> chapter in Resin documentation.
419 </p>
420
421 </body>
422 </section>
423 </chapter>
424
425 <chapter>
426 <title>JMX</title>
427 <section>
428 <title>What is JMX</title>
429 <body>
430
431 <p>
432 JMX is a Java Management Extensions. From Sun's <uri
433 link="http://java.sun.com/products/JavaManagement/">JMX page</uri>:
434 </p>
435
436 <p by="Sun">
437 Java Management Extensions (JMX) technology provides the tools for building
438 distributed, Web-based, modular and dynamic solutions for managing and
439 monitoring devices, applications, and service-driven networks. By design, this
440 standard is suitable for adapting legacy systems, implementing new management
441 and monitoring solutions, and plugging into those of the future.
442 </p>
443
444 <p>
445 In other words: JMX allows server administration from web applications or from
446 JConsole.
447 </p>
448
449 </body>
450 </section>
451 <section>
452 <title>Running Resin with JMX</title>
453 <body>
454
455 <p>
456 To enable JMX in resin, the following parameter should be added to the
457 <c>JAVA_OPTS</c> variable:
458 </p>
459
460 <pre caption="Enabling JMX">
461 -Dcom.sun.management.jmxremote
462 </pre>
463
464 <p>
465 After that start JConsole will test JMX in Resin:
466 </p>
467
468 <pre caption="Starting JConsole">
469 # <i>$(java-config --jdk-home)/bin/jconsole</i>
470 </pre>
471
472 <p>
473 The <e>Connect to Agent</e> window should list Resin.
474 </p>
475
476 </body>
477 </section>
478 </chapter>
479
480 <chapter>
481 <title>Problems</title>
482 <section>
483 <title>How to report bugs?</title>
484 <body>
485
486 <p>
487 Please start with the Gentoo Java community and Team, which can be
488 reached via the <uri link="/main/en/lists.xml">gentoo-java@gentoo.org</uri>
489 mailing list, or the <uri link="/main/en/irc.xml">#gentoo-java</uri> IRC
490 channel in the <uri link="http://freenode.net">irc.freenode.net</uri>. Please
491 file and report Gentoo related bugs, feature enhancement requests to the
492 <uri link="http://bugs.gentoo.org">Gentoo Bugzilla</uri>.
493 </p>
494
495 </body>
496 </section>
497 </chapter>
498 </guide>
Note: See TracBrowser for help on using the browser.