Resin web server

From Resin 3.0

(Difference between revisions)
Jump to: navigation, search
(migration)
m (Protected "Resin web server" [edit=sysop:move=sysop])
 
(13 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
 
== Unix (including MacOS-X) ==
 
== Unix (including MacOS-X) ==
  
Line 22: Line 23:
  
 
The following steps will start Resin for development:
 
The following steps will start Resin for development:
−
 
+
<ol>
−
# Install JDK 1.4 or later and link <tt>/usr/java</tt> to the Java home ''or'' set environment variable [[JAVA_HOME]].
+
<li>Install JDK 1.4 or later and link <tt>/usr/java</tt> to the Java home ''or'' set environment variable [[JAVA_HOME]].
−
# Download Resin from the [[http://www.caucho.com/download download]] page
+
<li>Download Resin from the [[http://www.caucho.com/download download]] page
−
# Untar <tt>resin-pro-3.0.x.tar.gz</tt>
+
<li>Untar <tt>resin-pro-3.0.x.tar.gz</tt>
−
# Change directory to <tt>resin-pro-3.0.x</tt>
+
<li>Change directory to <tt>resin-pro-3.0.x</tt>
−
# Build Resin <tt>./configure; make; make install</tt>
+
<li>Build Resin <tt>./configure; make; make install</tt>
−
# Execute <tt>bin/httpd.sh</tt>
+
<ul>
−
# Browse <tt>http://localhost:8080</tt>
+
<li>This was a problem with 3.1.6, but seems to have been fixed in 3.2.0. <s>Please note that on OS X, the above will <i>not</i> copy the JNI libraries anywhere such that they will be loaded when resin starts. What results is a message in one of resin's log files along the lines of, "Socket JNI library is not available. To compile the Socket JNI library on Unix, use ./configure; make; make install." To address this, copy the .jnilib files, which should be in the resin/libexec directory, to /Library/Java/Extensions in order for any user, including root, to pick them up. If you're running resin with a particular user, i.e. for local development, you can put them into that user's local ~/Library/Java/Extensions.</s></li>
 +
</ul>
 +
<li>Execute <tt>bin/httpd.sh</tt>
 +
<li>Browse <tt>http://localhost:8080</tt>
 +
</ol>
  
 
=== ./configure options ===
 
=== ./configure options ===
 +
 
{{main|configure script}}
 
{{main|configure script}}
  
Line 42: Line 48:
 
The <tt>--enable-64bit</tt> compiles the JNI code as 64 bit.
 
The <tt>--enable-64bit</tt> compiles the JNI code as 64 bit.
 
When starting Resin with [[httpd.sh]], pass the [[-J-d64]] option.
 
When starting Resin with [[httpd.sh]], pass the [[-J-d64]] option.
 +
 +
=== bin/httpd.sh ===
 +
 +
{{main|httpd.sh}}
 +
 +
<tt>bin/httpd.sh</tt> is the script for starting the web server.
 +
 +
Developers commonly execute httpd.sh in a '''cmd''' window and log messages
 +
are displayed on the console.
 +
 +
<!-- pre -->
 +
  (prompt) bin/httpd.sh
 +
<!-- /pre -->
  
 
=== Deploying ===
 
=== Deploying ===
Line 47: Line 66:
 
{{See also|site structure}}
 
{{See also|site structure}}
  
−
When deploying, it's a good idea to create a bit of structure to
+
It is a good idea to create a bit of structure to make Resin and website
−
make Resin and website upgrades easier and more maintainable.
+
upgrades easier and more maintainable. In particular the [[-server-root]]
−
In particular the [[-server-root]] option provides the ability to create
+
option provides the ability to create a maintainable file structure for your
−
structure for your website.
+
website.
  
 
# Create a user to run Resin (e.g. resin or another non-root user)
 
# Create a user to run Resin (e.g. resin or another non-root user)
Line 62: Line 81:
 
# [[Virtual host]]s are created by adding directories in <tt>/var/www/hosts/</tt>, e.g. <tt>/var/www/hosts/gryffindor.hogwarts.com/</tt> and <tt>/var/www/hosts/slytherin.hogwarts.com/</tt>
 
# [[Virtual host]]s are created by adding directories in <tt>/var/www/hosts/</tt>, e.g. <tt>/var/www/hosts/gryffindor.hogwarts.com/</tt> and <tt>/var/www/hosts/slytherin.hogwarts.com/</tt>
 
# Create a [[daemon]] startup script and configure the server to start it when the machine reboots.
 
# Create a [[daemon]] startup script and configure the server to start it when the machine reboots.
−
 
−
=== bin/httpd.sh ===
 
−
 
−
{{main|httpd.sh}}
 
−
 
−
<tt>bin/httpd.sh</tt> uses a perl script, <tt>resin-3.0.x/bin/wrapper.pl</tt>,
 
−
to control the Java process (bin/httpd.sh is a tiny shell script
 
−
that calls wrapper.pl).  You can modify <tt>bin/httpd.sh</tt>.
 
−
 
−
If you need to stop Resin with <tt>kill</tt>, you'll need to kill
 
−
the wrapper.pl process to make sure it doesn't restart Resin.
 
−
<tt>httpd.sh stop</tt> works by killing the wrapper.pl process.
 
−
or bin/wrapper.pl for your configuration.
 
−
 
−
In a production environment, the "start" and "stop" options to
 
−
<tt>bin/httpd.sh</tt> start and stop Resin as a Unix daemon.
 
−
If Resin should ever exit, it will automatically be restarted.
 
  
 
=== Site specific daemon script ===
 
=== Site specific daemon script ===
  
 
{{main|daemon}}
 
{{main|daemon}}
 +
 +
'''httpd.sh''' accepts the <tt>start</tt>, <tt>stop</tt>, and <tt>restart</tt>
 +
options for executon as a [[daemon]].
  
 
You can create your own [[daemon]] script which will start and stop
 
You can create your own [[daemon]] script which will start and stop
Line 134: Line 139:
 
[[Port forwarding]] details operating system specific techniques for forwarding
 
[[Port forwarding]] details operating system specific techniques for forwarding
 
privileged ports to the ports that Resin is bound to.
 
privileged ports to the ports that Resin is bound to.
 +
 +
=== See also ==
 +
 +
; [[Linux service]] : installing Resin as a Linux service
  
 
== Windows ==
 
== Windows ==
Line 159: Line 168:
 
<!-- /pre -->
 
<!-- /pre -->
  
−
=== Deploying ===
+
=== httpd.exe  ===
  
−
{{See also|site structure}}
+
{{main|httpd.exe}}
  
−
When deploying, it's a good idea to create a bit of structure to
+
<tt>httpd.exe</tt> is the script for starting the web server.
−
make Resin and website upgrades easier and more maintainable.
+
−
In particular the [[-server-root]] option provides the ability to create
+
−
structure for your website.
+
  
−
==== Windows service ===
+
Developers commonly execute httpd.exe in a '''cmd''' window and log messages
 +
are displayed on the console.
  
−
The Resin Web Server can be installed as an Windows service.
+
<!-- pre -->
−
To install the service, use:
+
   (prompt) httpd.exe
−
 
+
−
<!-- pre syntax="sh" -->
+
−
   (prompt) httpd.exe -install -conf conf/resin.conf
+
 
<!-- /pre -->
 
<!-- /pre -->
  
−
To remove the service, use [[-remove]]:
+
=== Deploying ===
  
−
<!-- pre syntax="console" -->
+
{{See also|site structure}}
−
  (prompt) httpd.exe -remove
+
−
<!-- /pre -->
+
  
−
You will either need to reboot the machine or start the service
+
It is a good idea to create a bit of structure to make Resin and website
−
from the '''Control&nbsp;Panel''' | '''Services''' panel to start the server.
+
upgrades easier and more maintainable.  In particular the [[-server-root]]
−
On a machine reboot Windows will automatically start the web server.
+
option provides the ability to create a maintainable file structure for your
 +
website.
  
−
You can also start and stop the service from the command-line:
+
=== Windows service ===
  
−
<!-- pre syntax="console" -->
+
{{main|Windows service||
−
  (prompt) net start resin
+
−
  ...
+
−
  (prompt) net stop resin
+
−
<!-- /pre -->
+
  
−
The [[-server]] option is used if you have multiple JVMs either on different
+
The Resin Web Server can be installed as a Windows service.
−
machines or the same machine.
+
To install the service, use:
−
The [[load balancing]] and [[distributed session]]s topics describe usage
+
−
of [[-server]].
+
  
−
Resin's [[-install]] option saves the command-line options and starts the
+
<!-- pre syntax="sh" -->
−
service with those options.  You can look at them in the control panel, under
+
   (prompt) httpd.exe -install -conf conf/resin.conf
−
the executable string.
+
−
 
+
−
With multiple servers, you can use ""[[-install-as]] ''name''" to specify
+
−
a unique service name.
+
−
 
+
−
<!-- pre syntax="console" -->
+
−
   (prompt) httpd.exe -install-as ResinA -conf conf/myconf.conf -server a
+
−
  (prompt) net start ResinA
+
−
<!-- /pre -->
+
−
 
+
−
There is a bug in many JDKs which cause the JDK to exit when the
+
−
administrator logs out.  You can avoid that bug if the
+
−
JDK is started with [[-Xrs]]
+
−
 
+
−
<!-- pre syntax="console" -->
+
−
  (prompt) httpd.exe -install -Xrs
+
 
<!-- /pre -->
 
<!-- /pre -->
  
 
== Command-line options ==
 
== Command-line options ==
  
−
{{main|command line option}}
+
{{main|Command line option}}
  
−
<table>
 
−
<tr><th>Option</th><th>Description</th><th>Default</th></tr>
 
−
<tr><td>-verbose</td><td>Show the Java environment before starting Resin.</td><td>off</td></tr>
 
−
<tr><td>-conf ''xxx''<td>Selects the Resin configuration file<td>conf/resin.conf
 
−
<tr><td>-java_home ''xxx''<td>Sets the JDK (also recognizes the environment variable JAVA_HOME.)<td>A heuristic search
 
−
<tr><td>-resin_home ''xxx''<td>Sets the Resin home directory (also recognizes the environment variable RESIN_HOME.)<td>The parent directory of wrapper.pl
 
−
<tr><td>-classpath ''xxx''<td>Adds to the system classpath.<td>$CLASSPATH
 
−
<tr><td>-pid ''xxx''<td>(Unix) With ''start'' or ''stop'', sets the file
 
−
to save the process id.<td>resin.pid
 
−
<tr><td>-stdout ''xxx''<td>Sets the file to save stdout messages.<td>log/stdout.log.
 
−
<tr><td>-stderr ''xxx''<td>Sets the file to save stdout messages.<td>log/stderr.log.
 
−
<tr><td>-D''my.foo''=''value''<td>Sets a Java system property.<td>n/a
 
−
<tr><td>-X''xxx''<td>Passes the -X''xxx'' command to the JDK.<td>n/a
 
−
<tr><td>-J''xxx''<td>Passes ''xxx'' as a JDK argument.<td>n/a
 
−
<tr><td>-nojit<td>Disables the Just-In-Time compiler. Useful for debugging.<td>enabled
 
−
<tr><td>start<td>(Unix) Starts Resin as a daemon, saving the pid in the pid file.<td>n/a
 
−
<tr><td>stop<td>(Unix) Stops Resin as a daemon, using the pid in the pid file.<td>n/a
 
−
<tr><td>restart<td>(Unix) Restarts Resin as a daemon, using the pid in the pid file.<td>n/a
 
−
<tr><td>-install<td>(Windows) install Resin as a service (but doesn't automatically start.)<td>n/a
 
−
<tr><td>-install-as ''xxx''<td>(Windows) install Resin as a named service (but doesn't automatically start.)<td>n/a
 
−
<tr><td>-remove<td>(Windows) install Resin as a service (but doesn't automatically start.)<td>n/a
 
−
<tr><td>-remove-as ''xxx''<td>(Windows) remove Resin as a named service (but doesn't automatically start.)<td>n/a
 
−
</table>
 
  
 
== Memory configuration ==
 
== Memory configuration ==

Latest revision as of 17:21, 9 January 2009

Contents

[edit] Unix (including MacOS-X)

[edit] Getting started 

(prompt) tar -xzvf resin-pro-3.0.x.tar.gz
(prompt) cd resin-pro-3.0.x
(prompt) ./configure; make; make install
 
(prompt) bin/httpd.sh
 
Resin-3.0.x (built Fri, 03 Feb 2006 09:47:48 EST)
Copyright(c) 1998-2006 Caucho Technology.  All rights reserved.
 
Starting Resin on Mon, 13 Feb 2006 20:16:19 -0500 (EST)
 
[20:16:23.367] Server[] starting
...
[20:16:23.453] http listening to *:8080
...

The following steps will start Resin for development:

  1. Install JDK 1.4 or later and link /usr/java to the Java home or set environment variable JAVA_HOME.
  2. Download Resin from the [download] page
  3. Untar resin-pro-3.0.x.tar.gz
  4. Change directory to resin-pro-3.0.x
  5. Build Resin ./configure; make; make install
    • This was a problem with 3.1.6, but seems to have been fixed in 3.2.0. Please note that on OS X, the above will not copy the JNI libraries anywhere such that they will be loaded when resin starts. What results is a message in one of resin's log files along the lines of, "Socket JNI library is not available. To compile the Socket JNI library on Unix, use ./configure; make; make install." To address this, copy the .jnilib files, which should be in the resin/libexec directory, to /Library/Java/Extensions in order for any user, including root, to pick them up. If you're running resin with a particular user, i.e. for local development, you can put them into that user's local ~/Library/Java/Extensions.
  6. Execute bin/httpd.sh
  7. Browse http://localhost:8080

[edit] ./configure options

Main article: configure script
OptionDescription
--enable-64bitcompiles the JNI using 64-bits

The 64-bit JNI compilation must match the JDK you're using. The --enable-64bit compiles the JNI code as 64 bit. When starting Resin with httpd.sh, pass the -J-d64 option.

[edit] bin/httpd.sh

Main article: httpd.sh

bin/httpd.sh is the script for starting the web server.

Developers commonly execute httpd.sh in a cmd window and log messages are displayed on the console. 

 (prompt) bin/httpd.sh

[edit] Deploying

See also: site structure

It is a good idea to create a bit of structure to make Resin and website upgrades easier and more maintainable. In particular the -server-root option provides the ability to create a maintainable file structure for your website.

  1. Create a user to run Resin (e.g. resin or another non-root user)
  2. Link /usr/local/resin to the current Resin version.
  3. Create a deployment root, e.g. /var/www, owned by the resin user. This is -server-root.
  4. Put the modified resin.conf in /var/www/conf/resin.conf
  5. Put the site documents in /var/www/webapps/ROOT/
  6. Access logs will appear in /var/www/logs/
  7. Output logs will appear in /var/www/log/
  8. Put any .war files in /var/www/webapps/
  9. Virtual hosts are created by adding directories in /var/www/hosts/, e.g. /var/www/hosts/gryffindor.hogwarts.com/ and /var/www/hosts/slytherin.hogwarts.com/
  10. Create a daemon startup script and configure the server to start it when the machine reboots.

[edit] Site specific daemon script

Main article: daemon

httpd.sh accepts the start, stop, and restart options for executon as a daemon.

You can create your own daemon script which will start and stop your Resin instance, and pass any command-line options. This script can be placed in /etc/init.d and work cooperatively with the operating systems standard daemon control system. The script typically does a number of things:

  1. Configures the location of Java in JAVA_HOME
  2. Configures the location of Resin in RESIN_HOME
  3. Configures your web site directory in SERVER_ROOT
  4. Selects a server and pid file if you have multiple Resin servers.
  5. Starts and stops the Resin daemon.

An example is included in the Resin distribution resin-pro-3.0.x/contrib/init.resin.

A simple daemon script looks like: 

#!/bin/sh

JAVA_HOME=/usr/java
RESIN_HOME=/usr/local/resin
SERVER_ROOT=/usr/local/web

export JAVA_HOME
export RESIN_HOME
export SERVER_ROOT

$RESIN_HOME/bin/httpd.sh -server-root $SERVER_ROOT \
                         -conf $SERVER_ROOT/conf/resin.conf \
                         -server a -pid $SERVER_ROOT/a.pid \\
                         $*

The script is invoked with ./resin start to start and ./resin stop to stop.

The -server and -pid options are only necessary if you have multiple JVMs either on different machines or the same machine. The load balancing and distributed sessions topics describe usage of -server and -pid.

[edit] Port forwarding

Main article: Port forwarding

Unix systems require root privileges to bind to ports less than 1024. Running the Resin process as root is not advised for security reasons. Port forwarding details operating system specific techniques for forwarding privileged ports to the ports that Resin is bound to.

[edit] = See also

Linux service 
installing Resin as a Linux service

[edit] Windows

[edit] Getting started

  1. Install JDK 1.4 or later.
  2. Make sure the JDK installation set the environment variable JAVA_HOME correctly
  3. Unzip resin-3.0.x.zip
  4. Execute resin-3.0.x\httpd.exe
  5. Browse http://localhost:8080 
 (prompt) cd resin-pro-3.0.x
 (prompt) httpd.exe

 Resin-pro-3.0.x (built Fri, 03 Feb 2006 09:47:48 EST)
 Copyright(c) 1998-2006 Caucho Technology.  All rights reserved.
  
 Starting Resin on Mon, 13 Feb 2006 20:16:19 -0500 (EST)
  
 [20:16:23.367] Server[] starting

 ...

[edit] httpd.exe

Main article: httpd.exe

httpd.exe is the script for starting the web server.

Developers commonly execute httpd.exe in a cmd window and log messages are displayed on the console. 

 (prompt) httpd.exe

[edit] Deploying

See also: site structure

It is a good idea to create a bit of structure to make Resin and website upgrades easier and more maintainable. In particular the -server-root option provides the ability to create a maintainable file structure for your website.

[edit] Windows service

{{main|Windows service||

The Resin Web Server can be installed as a Windows service. To install the service, use: 

 (prompt) httpd.exe -install -conf conf/resin.conf

[edit] Command-line options

Main article: Command line option


[edit] Memory configuration

Main article: Command line options#Memory settings

Memory configuration is part of the JVM's options. For most JVMs, you can find the full list by starting "java -X".

-Xms<size>Initial Java heap size, e.g. -Xms32m
-Xmx<size>Maximum Java heap size, e.g. -Xmx128m

[edit] Starting Java directly

You can use the -verbose option to see the arguments the startup scripts/executables pass to the JDK. The IDE section also contains information about starting Resin directly from Java.

Retrieved from "http://wiki3.caucho.com/index.php?title=Resin_web_server&oldid=3134"
Personal tools