<document>
  <header>
    <product>resin</product>
    <version>Resin 4.0</version>
    <title>Resin Installation Quick Start</title>

    <description>
<p>If you're using Resin for the first time, this section will
show you how to install Resin, start it, and deploy your application.</p>
    </description>
  </header>

  <body>
    <localtoc/>

<s1 title="Preconditions">

<ul>
<li>Resin requires JDK 6.0 or later.</li>
<li>An HTML 5 browser for some /resin-admin features.</li>
</ul>
 
<p>Oracle's JDK for Windows, Solaris, and Linux can be found at
<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">http://www.oracle.com/technetwork/java/javase/downloads/index.html</a>.
Oracle also has links to some other ports of the JDK.  Resin will not be fully functional while using a JRE.</p>

</s1>

<s1 title="Directory Overview">

<p>When Resin is installed on a <b>Unix</b> system:</p>

<ul>
<li><b>resinctl</b> is the <a href="starting-resin-command-line.xtp">command-line interface</a>.</li>
<li><a href="config-resin-properties.xtp">Configuration properties</a>
are in <em>/etc/resin/resin.properties</em></li>
<li><a href="deploy.xtp">Deployed applications</a> are
put in <em>/var/resin/webapps</em></li>
<li>Logs are in <em>/var/log/resin</em></li>
<li>Licenses belong in  <em>/etc/resin/licenses</em></li>
<li>OpenSSL keys belong in <em>/etc/resin/keys</em></li>
</ul>

<example title="Unix Directories">
/etc/resin/resin.properties  # configuration properties
/etc/resin/resin.xml         # configuration file
/etc/resin/licenses/         # license location
/etc/resin/keys/             # openssl keys

/var/resin/                  # resin.root (content)
/var/resin/webapps/          # default deployment directory

/var/log/resin/              # resin logs

/usr/local/share/resin/      # resin.home (binaries and libraries)
</example>

<p>When Resin is installed on a <b>Windows</b> system:</p>

<ul>
<li><b>resin</b> is the <a href="starting-resin-command-line.xtp">command-line interface</a>.</li>
<li><a href="config-resin-properties.xtp">Configuration properties</a>
are in <em>conf/resin.properties</em></li>
<li><a href="deploy.xtp">Deployed applications</a> are
in <em>webapps</em></li>
<li>Logs are in <em>log</em></li>
<li>Licenses belong in  <em>conf/licenses</em></li>
<li>OpenSSL keys belong in <em>conf/keys</em></li>
</ul>

<example title="Windows/unzip Directories">
resin-4.0.x/                 # installation directory: resin.home, resin.root
  conf/resin.properties      # configuration properties
  conf/resin.xml             # configuration file
  conf/licenses/             # license location
  conf/keys/                 # openssl keys

  webapps/                   # default deployment directory

  logs/                      # resin logs
</example>

</s1>

<s1 name="quickstart" title="Installing Resin">

<p>Installation steps for the major operating systems are outlined below:</p>

<s2 title="Debian Unix .deb and apt-get">
<p>
Debian users can download a .deb packaged version of Resin
or use apt-get to install Resin. The Debian package 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, you can add the debian repository as follows:
</p>
<example>
unix# add-apt-repository http://caucho.com/download/debian
</example>
<p>
After adding this line, update your local repository cache by running:
</p>
<example>
unix# apt-get update
</example>

<p>
Install Resin Professional  with this command:
</p>
<example>
unix# apt-get install resin-pro
</example>

<p>
Or install Resin Open Source with this command:
</p>
<example>
unix# apt-get install resin
</example>

</s2>

<s2 title="RedHat and CentOS .rpm files">
<p>
RPM files are available at <a href="http://caucho.com/download">
http://caucho.com/download</a>. The RPM public key is at
<a href="http://caucho.com/download/rpm/RPM-GPG-KEY-caucho">
http://caucho.com/download/rpm/RPM-GPG-KEY-caucho</a>.
</p>

<example title="RPM/yum install">
unix# rpm --import http://caucho.com/download/rpm/RPM-GPG-KEY-caucho
unix# yum install http://caucho.com/download/rpm/4.0.30/x86_64/resin-pro-4.0.30-1.x86_64.rpm
</example>

</s2>

<s2 title="Other Unix, Linux, Solaris, and Mac OS X">

<ol>
<li>Install JDK 6 or later and link /usr/java to the Java home or define the 
environment variable <var>JAVA_HOME</var>.</li>
<li><code>tar -vzxf resin-4.0.x.tar.gz</code></li>
<li><code>cd resin-4.0.x</code></li>
<li><code>./configure</code>
  <ul><li>some details on the <a href="starting-resin-command-line.xtp">./configure options</a>.</li></ul>
</li>
<li><code>make</code></li>
<li><code>sudo make install</code></li>
<li>Execute <code>sudo resinctl start</code>
  <ul><li>or run <code>java -jar lib/resin.jar start</code></li></ul>
</li>
<li>Browse to <a href="http://localhost:8080">http://localhost:8080</a></li>
</ol>

</s2>

<s2 title="Windows">

<ol>
<li>Install JDK 6 or later.</li>
<li>Check that the environment variable <var>JAVA_HOME</var> is set to the JDK 
location, e.g. <code>c:\java\jdk1.6.0_14</code></li>
<li>Unzip resin-4.0.x.zip</li>
<li>Define the environment variable <var>RESIN_HOME</var> to the location of
Resin, for example <code>c:\resin-4.0.x</code></li>
<li>Execute <code>resin.exe</code>
  <ul><li>or run <code>java -jar lib/resin.jar start</code></li></ul>
</li>
<li>Browse to <a href="http://localhost:8080">http://localhost:8080</a></li>
</ol>
</s2>

</s1>

<s1 title="Installing a license file for Resin Pro">
<p>
After installing Resin Professional, you need to install the license file.
</p>

<p>
If you have a license file for Resin, save it in <var>/etc/resin/licenses</var>.
You can also install the license from the command line with:
<example>
unix> resinctl license-add mylicense.license
</example>
</p>
</s1>

<s1 title="Resin as a Web Server">

<p>Resin includes a high-performance HTTP server that outperforms NginX and Apache httpd. The easiest and fastest
Resin configuration uses Resin as the web server as well as 
the application server. We highly recommend you start with this configuration 
although you are free to use other web servers like Apache or IIS
with Resin.</p>

<p>Resin Web Server has been tested to serve 100,000 requests per second,
making it comparable in performance to top C-based web servers.
See <a href="http://wiki4.caucho.com/NginX_1.2.0_versus_Resin_4.0.29_performance_tests">Wiki: Resin Web Server: Resin 4.0.x vs nginx 1.2 performance</a> for
a comparison of Resin's performance vs nginx, a fast C-based HTTP server.</p>

<p>Keep in mind, Resin can be used for development or evaluation in addition
to using it in production. If desired,
you can easily apply for a development license to enable Resin Pro features.
You can also simply use Resin Open Source to start development.</p>

<figure src="httpd.gif" alt="browser <-> Resin httpd/servlets,beans <- html,jsp"/>

<p>The built-in HTTP server listens on port 8080 in the default
configuration and can be changed to listen on the HTTP port 80 instead during
deployment.</p>

<example title="Example: Starting Resin">
unix> resinctl start

c:\windows> resin start
</example>

<p>For troubleshooting your installation, you can also run Resin
in "console" mode, which will let you see the logging messages
in your console.</p>

<example title="Example: Starting Resin in console mode">
unix> resinctl console
</example>

<p>For more details, see the <a href="http-server.xtp">Resin Web Server</a>
configuration page.</p>

</s1>

<s1 title="Browser-Based Administration (/resin-admin)">

<p>To enable the /resin-admin browser-based administration, you'll need
to create an admin user and password. You can either create the user in
resin-admin itself, or if you are using the standard resin.xml and
resin.properties you can generate the key from the command
line <em>resinctl</em></p>

<s2 title="Installation with resin.properties and generate-password">

<p>You can generate the user and password properties
from the command-line. Resin's password must be hashed for security.</p>

<example title="Example: generate-password">
unix> resinctl generate-password my-user my-password
<em>admin_user : my-user
admin_password : {SSHA}HTfP60Ceq0K0IAvN31wQtBxtql9D+8Wo
</em>
</example>

<p>Add the admin_user and admin_password lines to
the end of the /etc/resin/resin.properties file. You may also use
those values to change your admin-users.xml file.</p>

<p>You can update the resin.properties in one step on unix
by using a pipe:</p>

<example title="Example: generate-password for resin.properties">
unix# resinctl generate-password my-user my-password >> /etc/resin/resin.properties
</example>

</s2>

<s2 title="Installation with /resin-admin">

<ol>
<li>Create an admin user following the prompt at /resin-admin.</li>
<li>Rename <em>admin-users.xml.generated</em> to <em>admin-users.xml</em>.</li>
<li>Change the resin_admin_external to true in the resin.xml if you need access from a non-local IP address.</li>
<li>Browse /resin-admin with an HTML 5 browser.</li>
</ol>

<p>On Linux, <var>admin-users.xml.generated</var> is typically generated in <em>/etc/resin/</em>.</p>

<p>The steps are for security reasons. Copying the admin-users.xml
verifies that you have access to the server. And the default
resin_admin_external=false makes sure you're not exposing the /resin-admin
to the internet.</p>

</s2>

<p>For more information, see the <a href="resin-admin-console.xtp">/resin-admin
documentation</a>.</p>

</s1>

<s1 title="Deploying Applications">

<p>Once you've made sure Resin is working, you can start to run
applications and add content.</p>

<s2 title="Local network command-line deployment">

<p>Command-line deployment on a local network deploys a .war file to
a running Resin server, using the .war file's name as the context-path.
It looks like the following example.</p>

<example title="Example: command-line deployment">
unix> resinctl deploy hello.war

unix> resinctl undeploy hello.war
</example>

<p>The URL for the application would be: <em>http://localhost:8080/hello</em>.</p>

<p>To deploy to the root context-path, use a file name ROOT.war
or use the --name attribute.</p>

<example title="Example: root command-line deployment">
unix> resinctl deploy --name ROOT mywar.war

unix> resinctl undeploy --name ROOT
</example>

</s2>

<s2 title="Remote network command-line deployment">

<p>Deploying to a remote network requires some more configuration for
security reasons:</p>

<ol>
<li>enable remote administration (disabled by default)</li>
<li>configure an admin user and password</li>
</ol>

<p>After the changes, resin.properties will look something like:</p>

<example title="Example: resin.properties for remote deployment">
...

admin_user          : my-user
admin_password      : {SSHA}HTfP60Ceq0K0IAvN31wQtBxtql0D+8Wo
admin_remote_enable : true
</example>

<p>When you deploy, you will need to give the user and password:</p>

<example title="Example: remote deploy">
unix> resinctl deploy --user my-user --password my-password hello.war
</example>

</s2>

<s2 title="webapps directory deployment">

<p>You can deploy .war files by copying them
to the webapps directory like this: <code>resin-4.0.x/webapps/hello.war</code>.
The URL for the application would be: 
<a href="http://localhost:8080/hello">http://localhost:8080/hello</a>.
</p>

<p>You can also deploy .wars in exploded form like: <code>resin-4.0.x/webapps/hello/index.php</code>.
The URL for the application would be:
<a href="http://localhost:8080/hello">http://localhost:8080/hello</a>.</p>

<p>You can use a web.xml file to configure the 'hello' web application:
<code>resin-4.0.x/webapps/hello/WEB-INF/web.xml</code>.</p>

<p>For more information on deployment, see the <a href="deploy.xtp">deployment documentation</a>.</p>

</s2>
</s1>

<s1 title="Running Resin as a Daemon">

<p>Most production environments will run Resin as a background daemon.
When running as a daemon, Resin detaches from the console and continues
running until it is stopped.</p>

<p>The following are the basic steps to running Resin as a daemon:</p>
<ol>
<li>Start resin with <code>resinctl start</code></li>
<li>Stop resin with <code>resinctl stop</code></li>
<li>Restart resin with <code>resinctl restart</code></li>
</ol>

<p>The .rpm and .deb files install Resin in /etc/init.d/resin, which will
start Resin when the system boots.</p>

</s1>

<s1 title="Command-Line PDF Reports">

<p>PDF reports about the Resin server can be generated with the
command-line, the /resin-admin browser-based GUI, or as automatic health
system tasks.</p>

<p>From the command-line you can generate a pdf-report with the following:</p>

<example title="Example: generating a PDF snapshot report">
unix> resinctl pdf-report

<em>generated /var/resin/log/default-Watchdog-20111010T1426.pdf</em>
</example>

<p>You can also generate a report for the most recent restart event saved by
the watchdog. The watchdog report will give information about why Resin was
last stopped.</p>

<example title="Example: generating a PDF watchdog report">
unix> resinctl pdf-report -watchdog

<em>generated /var/resin/log/default-Watchdog-20111010T1426.pdf</em>
</example>

</s1>

<s1 title="Resin IDE Support">

<p>Resin includes excellent support for Eclipse. In fact, using the Eclipse support 
may be the easiest way get started with Resin.</p>
<p>Resin plugin support is included in 
Indigo (Eclipse 3.7) and above (you can install the Resin plugin manually for earlier
Eclipse versions). The Resin plugin allows you to create new server instances, 
configure servers, start servers, stop servers, restart instances, deploy/undeploy 
applications, debug on the server and so on. You can even automatically download and 
install the latest version of Resin using the plugin or apply for a development license 
for Resin Pro.</p>
<p>Further details on the Resin Eclipse plugin is available 
<a href="resin-eclipse-support.xtp">here</a>.</p>

</s1>

<s1 title="More Installation Options">

<p>More installation and configuration are available at
<a href="install.xtp">installation options</a>.</p>

</s1>

<s1 title="Next Steps">

<ul>
<li><b><a href="config-resin-properties.xtp">resin.properties</a></b> configuration shows how to customize basic configuration.</li>
<li><b><a href="config-resin-xml.xtp">resin.xml</a></b> configuration shows more advanced and specialized configuration.</li>
<li><b><a href="resin-admin-command-line.xtp">command-line</a></b> describes
using the <b>resinctl</b> command line interface.</li>
<li><b><a href="deploy.xtp">deployment</a></b> deploying applications to
a running server.</li>
<li><b><a href="clustering.xtp">clustering</a></b> describes clustering,
cloud, and dynamic servers.</li>
<li><b><a href="resin-admin.xtp">resin-admin</a></b> describes the
/resin-admin browser-based interface.</li>
<li><b><a href="health.xtp">health</a></b> describes the
Resin health and monitoring system.</li>
<li><b><a href="resin-admin-rest.xtp">REST admin</a></b> describes the
REST interface for remote third-party admin integration.</li>
<li><b><a href="http.xtp">Resin HTTP Web Server</a></b>
describes fast, scalable HTTP web server.</li>
<li><b><a href="http-rewrite.xtp">HTTP URL Rewrite</a></b>
describes Resin's URL rewriting (like mod_rewrite).</li>
<li><b><a href="security.xtp">Security</a></b>
describes authentication, authorization and SSL.</li>
</ul>

</s1>

</body>
</document>
