Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


Resin Documentation

Feb 2012: Leading industry analyst names Caucho as "Visionary" vendor for Enterprise Application Servers.
Feb 2012: NetCraft survey says Resin experiencing strong growth in last year and used in number of the Million Busiest Sites.
home company blog wiki docs 
app server web server 
health cloud java ee pro 
 Resin Server | Application Server (Java EE Certified) and Web Server

resin installation quick start

You can start using Resin by simply expanding the archive and starting Resin with a Java command line. You can also start Resin directly from an IDE.


  • Resin requires JDK 6.0 or later
  • An HTML 5 browser for some /resin-admin features.

Oracle's JDK for Windows, Solaris, and Linux can be found at Oracle also has links to some other ports of the JDK.

Installing Resin

Installation steps for the major operating systems are outlined below:


  1. Install JDK 1.6 or later.
  2. Check that the environment variable JAVA_HOME is set to the JDK location, e.g. c:\java\jdk1.6.0_14
  3. Unzip
  4. Define the environment variable RESIN_HOME to the location of Resin, for example c:\resin-4.0.x
  5. Execute resin.exe
    • or run java -jar lib/resin.jar start
  6. Browse to http://localhost:8080

Debian Unix .deb and apt-get

Debian users can download a .deb packagated 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 Resin download page and install using dpkg.

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 /etc/apt/sources.list

unix# add-apt-repository

After adding this line, update your local repository cache by running:

unix# apt-get update

Finally, install Resin Professional using the following:

unix# apt-get install resin-pro

If you have a license file for Resin, save it in /etc/resin/licenses. You can also install the license from the command line with:

unix# resinctl license-add mylicense.license

Or install Resin Open Source with this command:

unix# apt-get install resin

RedHat and CentOS .rpm files

RPM files are available at The RPM public key is at

RPM/yum install
unix# rpm --import
unix# yum install

Other Unix, Linux, and Mac OS X

  1. Install JDK 1.6 or later and link /usr/java to the Java home or define the environment variable JAVA_HOME.
  2. tar -vzxf resin-4.0.x.tar.gz
  3. cd resin-4.0.x
  4. ./configure --prefix=`pwd`
  5. make
  6. make install
  7. Execute resinctl console
    • or run java -jar lib/resin.jar console
  8. Browse to http://localhost:8080

Resin as a Web Server

Resin includes a high-performance HTTP server. 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.

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.

browser <-> Resin httpd/servlets,beans <- html,jsp

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.

Example: Starting Resin
unix> resinctl start

c:\windows> resin start

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

Example: Starting Resin in console mode
unix> resinctl console

For more details, see the Resin Web Server configuration page.

Browser-Based Administration (/resin-admin)

To enable the /resin-admin, 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 you can generate the key from the command line resinctl

Installation with and generate-password

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

Example: generate-password
unix> resinctl generate-password my-user my-password
admin_user : my-user
admin_password : {SSHA}HTfP60Ceq0K0IAvN31wQtBxtql9D+8Wo

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

You can update the in one step on unix by using a pipe:

Example: generate-password for
unix# resinctl generate-password my-user my-password >> /etc/resin/

Installation with /resin-admin

  1. Create an admin user following the prompt at /resin-admin.
  2. Copy the resin.root/admin-users.xml.generated to resin.conf/admin-users.xml.
  3. Change the resin_admin_external to true in the resin.xml if you need access from a non-local IP address.
  4. Browse /resin-admin with an HTML 5 browser.

On Linux, resin.conf is typically /etc/resin/, and resin.root is typically /var/resin.

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.

For more information, see the /resin-admin documentation.

Deploying Applications

Once you've made sure Resin is working, you can start to run applications and add content

Local network command-line deployment

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.

Example: command-line deployment
resinctl deploy hello.war

resinctl undeploy hello.war

The URL for the application would be: http://localhost:8080/hello.

To deploy to the root context-path, use a file name ROOT.war.

Remote network command-line deployment

Deploying to a remote network requires some more configuration for security reasons:

  1. enable remote administration (disabled by default)
  2. configure an admin user and password

After the changes, will look something like:

Example: for remote deployment

admin_user          : my-user
admin_password      : {SSHA}HTfP60Ceq0K0IAvN31wQtBxtql0D+8Wo
admin_remote_enable : true

When you deploy, you will need to give the user and password:

Example: remote deploy
unix> resinctl deploy --user my-user --password my-password hello.war

(In 4.0.24, you will need to modify the local to point to the app server.)

webapps directory deployment

You can deploy .war files by copying them to the webapps directory like this: resin-4.0.x/webapps/hello.war. The URL for the application would be: http://localhost:8080/hello.

You can also deploy .wars in exploded form like: resin-4.0.x/webapps/hello/index.php. The URL for the application would be: http://localhost:8080/hello.

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

For more information on deployment, see the deployment documentation.

Running Resin as a Daemon

In most production environments, Resin will run as a background daemon. The previous steps ran Resin in the foreground, which is convenient for development since the logging output goes to the console. When running as a daemon, Resin detaches from the console and continues running until told to stop.

The following are the basic steps to running Resin as a daemon:

  1. Start resin with resinctl start
  2. Stop resin with resinctl stop
  3. Restart resin with resinctl restart

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

Command-Line PDF Reports

PDF reports about the Resin running status are available from the command-line, from /resin-admin browser-based GUI, and as automatic health system tasks.

From the command-line you can generate a pdf-report with the following:

Example: generating a PDF snapshot report
unix> resinctl pdf-report

generated /var/resin/log/default-Watchdog-20111010T1426.pdf

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.

Example: generating a PDF watchdog report
unix> resinctl pdf-report -watchdog

generated /var/resin/log/default-Watchdog-20111010T1426.pdf

Resin IDE Support

Resin includes excellent support for Eclipse. In fact, using the Eclipse support may be the easiest way get started with Resin.

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.

Further details on the Resin Eclipse plugin is available here.

More Installation Options

More installation and configuration are available at installation options.

Copyright © 1998-2012 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.