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


Resin Documentation

home company docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server

resin installation quick start

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


  • 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. Resin will not be fully functional while using a JRE.

Directory Overview

When Resin is installed on a Unix system:

Unix Directories
/etc/resin/  # configuration properties
/etc/resin/resin.xml         # configuration file
/etc/resin/licenses/         # license location
/etc/resin/conf/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)

When Resin is installed on a Windows system:

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

  webapps/                   # default deployment directory

  logs/                      # resin logs

Installing Resin

Installation steps for the major operating systems are outlined below:

Debian Unix .deb and apt-get

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 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, you can add the debian repository as follows:

unix# add-apt-repository
unix# apt-key adv --fetch-keys

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

unix# apt-get update

Install Resin Professional with this command:

unix# apt-get install resin-pro

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, Solaris, and Mac OS X

  1. Install JDK 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
  5. make
  6. sudo make install
  7. Execute sudo resinctl start
    • or run java -jar lib/resin.jar start
  8. Browse to http://localhost:8080


  1. Install JDK 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

Installing a license file for Resin Pro

After installing Resin Professional, you need to install the license file.

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

Resin as a Web Server

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.

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 Wiki: Resin Web Server: Resin 4.0.x vs nginx 1.2 performance for a comparison of Resin's performance vs nginx, a fast C-based HTTP server.

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 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 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. Rename admin-users.xml.generated to 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, admin-users.xml.generated is typically generated in /etc/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
unix> resinctl deploy hello.war

unix> 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 or use the --name attribute.

Example: root command-line deployment
unix> resinctl deploy --name ROOT mywar.war

unix> resinctl undeploy --name ROOT

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

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

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.

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 server can be generated with the command-line, the /resin-admin browser-based GUI, or 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.

Next Steps

  • configuration shows how to customize basic configuration.
  • resin.xml configuration shows more advanced and specialized configuration.
  • command-line describes using the resinctl command line interface.
  • deployment deploying applications to a running server.
  • clustering describes clustering, cloud, and dynamic servers.
  • resin-admin describes the /resin-admin browser-based interface.
  • health describes the Resin health and monitoring system.
  • REST admin describes the REST interface for remote third-party admin integration.
  • Resin HTTP Web Server describes fast, scalable HTTP web server.
  • HTTP URL Rewrite describes Resin's URL rewriting (like mod_rewrite).
  • Security describes authentication, authorization and SSL.

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