View source

== Unix (including MacOS-X) ==

=== Getting started ===

<!-- pre syntax="console" -->
 (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
 ...
<!-- /pre -->

The following steps will start Resin for development:
<ol>
<li>Install JDK 1.4 or later and link <tt>/usr/java</tt> to the Java home ''or'' set environment variable [[JAVA_HOME]].
<li>Download Resin from the [[http://www.caucho.com/download download]] page
<li>Untar <tt>resin-pro-3.0.x.tar.gz</tt>
<li>Change directory to <tt>resin-pro-3.0.x</tt>
<li>Build Resin <tt>./configure; make; make install</tt>
<ul>
<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 ===

{{main|configure script}}

<table>
<tr><th>Option<th>Description
<tr><td>[[--enable-64bit]]<td>compiles the JNI using 64-bits
</table>

The 64-bit [[JNI]] compilation must match the JDK you're using.
The <tt>--enable-64bit</tt> compiles the JNI code as 64 bit.
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 ===

{{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.

# Create a user to run Resin (e.g. resin or another non-root user)
# Link /usr/local/resin to the current Resin version.
# Create a deployment root, e.g. <tt>/var/www</tt>, owned by the resin user.  This is [[-server-root]].
# Put the modified resin.conf in <tt>/var/www/conf/resin.conf</tt>
# Put the site documents in <tt>/var/www/webapps/ROOT/</tt>
# Access logs will appear in <tt>/var/www/logs/</tt>
# Output logs will appear in <tt>/var/www/log/</tt>
# Put any .war files in <tt>/var/www/webapps/</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.

=== Site specific daemon script ===

{{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
your Resin instance, and pass any [[command-line option]]s.  This script 
can be placed in <tt>/etc/init.d</tt> and work cooperatively with the
operating systems standard daemon control system. The script typically does a
number of things:

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

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

A simple daemon script looks like:

<!-- pre syntax="sh" -->
 #!/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 \\
                          $*
<!-- /pre -->

The script is invoked with <tt>./resin start</tt> to start
and <tt>./resin stop</tt> 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 session]]s topics describe
usage of [[-server]] and [[-pid]].

=== Port forwarding ===

{{main|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.

=== See also ==

; [[Linux service]] : installing Resin as a Linux service

== Windows ==

=== Getting started ===

# Install JDK 1.4 or later.
# Make sure the JDK installation set the environment variable JAVA_HOME correctly
# Unzip resin-3.0.x.zip
# Execute resin-3.0.x\httpd.exe
# Browse http://localhost:8080

<!-- pre syntax="console" -->
  (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
 
  ...
<!-- /pre -->

=== httpd.exe  ===

{{main|httpd.exe}}

<tt>httpd.exe</tt> 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.

<!-- pre -->
  (prompt) httpd.exe
<!-- /pre -->

=== 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.

=== Windows service ===

{{main|Windows service||

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

<!-- pre syntax="sh" -->
  (prompt) httpd.exe -install -conf conf/resin.conf
<!-- /pre -->

== Command-line options ==

{{main|Command line option}}


== Memory configuration ==

{{main|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".

<table>
<tr><td>-Xms&lt;size><td>Initial Java heap size, e.g. -Xms32m
<tr><td>-Xmx&lt;size><td>Maximum Java heap size, e.g. -Xmx128m
</table>

== 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.