Installation

Download and setup

  1. Log in and download the XRebel Hub agent from http://hub.xrebel.com/.
  2. Add the following parameter to JVM arguments for the application server. Make sure the path that you refer to contains the xrebel.jar file:
-javaagent:[path/to/]xrebel.jar

Using multiple agents in the same JVM process? You need to specify the -javaagent parameter for every agent:

-javaagent:[path/to/]xrebel.jar -javaagent:[path/to/]jrebel.jar
  1. And you are done! Launch your server and application. The agent will start sending profiling data to the XRebel Hub servers as soon as it is successfully launched.

Adding XRebel Hub to your server

Having trouble getting XRebel Hub to work with your application server? This chapter details the correct examples for how to add the JVM parameter to your server startup, using either an IDE or running your server without it.


Adding the XRebel Hub parameter using an IDE

You can make your life a lot easier when you use an IDE. This section helps you add XRebel Hub agent to your servers in Eclipse, IntelliJ IDEA, NetBeans and JDeveloper.


Eclipse

This set of instructions assumes that you have already configured a server to be used in your IDE. In this example we have a Tomcat 8.0 server present in Eclipse.

  1. Open Run > Run Configurations...
  2. Select the desired server from the left hand menu.
  3. Open the Arguments tab on the right. You will be presented with this view:
../_images/addparameter-eclipse.png
  1. Add the following line under VM arguments:
-javaagent:[path/to/]xrebel.jar
  1. Press Apply to store the configuration.

From here, you can either press Run to immediately run the new server configuration. If you defined the XRebel Hub agent location successfully, you should see the XRebel Hub banner in the server console immediately on startup.


IntelliJ IDEA

This set of instructions assumes that you have already configured a server to be used in your IDE. In this example we have a Tomcat 7.0 server present in IntelliJ IDEA.

  1. Open Run > Edit Configurations...
  2. Select the desired server from the left hand menu. You will be presented with this view:
../_images/addparameter-intellij.png
  1. Add the following line in the VM options field:
-javaagent:[path/to/]xrebel.jar
  1. Press Apply to save the changes. Press OK to save the changes and close the configuration window.

The next time you run the server with this configuration, the XRebel Hub agent is run with it. If you defined the XRebel Hub agent location successfully, you should see the XRebel Hub banner in the server console immediately on startup.


NetBeans

This set of instructions assumes that you have already configured a server to be used in your IDE. In this example we have a Tomcat 8.0 server present in NetBeans.

  1. Open Tools > Servers.
  2. Select the desired server from the left hand menu. Open the Platform tab on the right. You will be presented with this view:
../_images/addparameter-netbeans.png
  1. Add the following line in the VM Options field:
-javaagent:[path/to/]xrebel.jar
  1. Press Close to save the changes and close the window.

The next time you run the server, XRebel Hub agent is run with it.


JDeveloper

This set of instructions assumes that you have already configured a server to be used in your IDE. In this example we have an embedded WebLogic server configured in JDeveloper.

  1. Open Window > Application Servers.
  2. Select the desired server from Application Servers pane. Right-click it and select Properties.
  3. Access the Launch Settings tab.
../_images/addparameter-jdeveloper.png
  1. Add the following line in the Java Options field:
-javaagent:[path/to/]xrebel.jar
  1. Press OK to save the changes and close the window.

The next time you run this server, the XRebel Hub agent is run with it.


Adding the XRebel parameter without an IDE

When running your application server without an IDE, you need to define the XRebel Hub agent within your server’s startup script. This chapter provides XRebel Hub agent running examples for servers that are supported.


GlassFish

  1. Access your GlassFish Administration Console.
  2. Open Configuration > JVM Settings > JVM Options.
  3. Press Add JVM Option and insert the following:
-javaagent:[path/to/]xrebel.jar
  1. Press Save and don’t forget to restart your server.

JBoss

JBoss on Windows

  1. Access your JBoss home folder.
  2. Open the bin folder.
  3. Create a new executable, for example run-xrebel.cmd.
  4. Add the following lines to this new executable:
@echo off
set JAVA_OPTS=-javaagent:[path/to/]xrebel.jar %JAVA_OPTS%
call "%~dp0\standalone.bat" %*

Note

Replace the link to the JBoss executable as necessary when using older JBoss versions.

  1. Run this executable instead of your standard JBoss executable.

JBoss on Mac OS and Linux

  1. Access your JBoss home folder.
  2. Open the bin folder.
  3. Create a new script, for example run-xrebel.sh.
  4. Add the following lines to this new executable:
#!/bin/bash
export JAVA_OPTS="-javaagent:[path/to/]xrebel.jar $JAVA_OPTS"
`dirname $0`/standalone.sh $@

Note

Replace the link to the JBoss executable as necessary when using older JBoss versions.

  1. Run this script instead of your standard JBoss executable.

JBoss Domain

  1. Access your JBoss Domain configuration folder JBOSS_HOME/domain/configuration.

  2. Open configuration.xml.

  3. Locate your desired server group.

  4. Add the following option to the configuration:

    <jvm-options>
      <option value="-javaagent:[path/to/]xrebel.jar"/>
    </jvm-options>
    
  5. Save configuration.xml and restart the server.


Jetty

Jetty on Windows

  1. Add the following to the command line:
-javaagent:[path/to/]xrebel.jar
  1. Run Jetty.

Jetty on Mac OS and Linux

  1. Access your Jetty home folder.
  2. Open the bin folder.
  3. Create a new script, for example jetty-xrebel.sh.
  4. Add the following lines to this new executable:
#!/bin/bash
export JAVA_OPTIONS="-javaagent:[path/to/]xrebel.jar $JAVA_OPTIONS"
`dirname $0`/jetty.sh $@
  1. Run this script instead of of your standard Jetty executable.

Resin

  1. Access your Resin home folder.
  2. Open the conf folder.
  3. Edit the resin.properties file. Locate jvm_args.
  4. Add the XRebel parameter:
jvm_args=-javaagent:[path/to]xrebel.jar
  1. Save and restart your application server.

Note

Alternatively, you can include the XRebel parameter in the resin.xml file. To do this, add the following within the <server> tags: <jvm-arg>-javaagent:[path/to]xrebel.jar</jvm-arg>

Warning

You only need to configure the JVM parameter once. Pick either the properties file or the xml file. Do not add the JVM parameter in both places.


Tomcat

Tomcat on Windows

  1. Access your Tomcat home folder.
  2. Open the bin folder.
  3. Create a new executable, for example catalina-xrebel.bat.
  4. Add the following lines to this new executable:
@echo off
set JAVA_OPTS=-javaagent:[path/to/]xrebel.jar %JAVA_OPTS%
call "%~dp0\catalina.bat" %*
  1. Run this executable instead of your standard Tomcat executable:
$ catalina-xrebel.bat run

Running Tomcat as a service? Open the tomcatXw.exe wrapper (double-click the Tomcat icon in your system tray). Insert the following line into the Java > Java Options text field:

-javaagent:[path/to/]xrebel.jar

Tomcat on Mac OS and Linux

  1. Access your Tomcat home folder.
  2. Open the bin folder.
  3. Create a new script, for example run-xrebel.sh.
  4. Add the following lines to this new executable:
#!/bin/bash
export JAVA_OPTS="-javaagent:[path/to/]xrebel.jar $JAVA_OPTS"
`dirname $0`/catalina.sh $@
  1. Run this script instead of your standard Tomcat executable.
./catalina-xrebel.sh run

WildFly

WildFly on Windows

  1. Access your WildFly home folder.
  2. Open the bin folder.
  3. Create a new executable, for example run-xrebel.cmd.
  4. Add the following lines to this new executable:
@echo off
set JAVA_OPTS=-javaagent:[path/to/]xrebel.jar %JAVA_OPTS%
call "%~dp0\standalone.bat" %*
  1. Run this executable instead of your standard JBoss executable.

WildFly on Mac OS and Linux

  1. Access your WildFly home folder.
  2. Open the bin folder.
  3. Create a new script, for example run-xrebel.sh.
  4. Add the following lines to this new executable:
#!/bin/bash
export JAVA_OPTS="-javaagent:[path/to/]xrebel.jar $JAVA_OPTS"
`dirname $0`/standalone.sh $@
  1. Run this script instead of your standard WildFly executable.

WebLogic

WebLogic on Windows

  1. Access your WebLogic home folder.
  2. Open the bin folder.
  3. Create a new executable, for example startWeblogic-xrebel.cmd.
  4. Add the following lines to this new executable:
@echo off
set JAVA_OPTIONS=-javaagent:[path/to/]xrebel.jar %JAVA_OPTIONS%
call "%~dp0\startWebLogic.cmd" %*
  1. Run this executable instead of your standard WebLogic executable.

WebLogic on Mac OS and Linux

  1. Access your WebLogic home folder.
  2. Open the bin folder.
  3. Create a new executable, for example startWeblogic-xrebel.sh.
  4. Add the following lines to this new executable:
#!/bin/bash
export JAVA_OPTIONS="-javaagent:[path/to/]xrebel.jar $JAVA_OPTIONS"
`dirname $0`/startWebLogic.sh $@
  1. Run this executable instead of your standard WebLogic executable.

WebSphere

Windows

  1. Start the IBM WebSphere server and open the administrative console.
  2. In the Admin Console open Servers > Application servers. Select the server your application is deployed to.
  3. Select Java and Process Management > Process Definition.
  4. Select Java Virtual Machine.
  5. Insert the following line into Generic JVM arguments for WebSphere:
-noverify -Xshareclasses:none -javaagent:[c:\path\to\]xrebel.jar
  1. Press OK. When asked, save the master configuration and restart the server.

Linux and Mac OS

  1. Start the IBM WebSphere server and open the administrative console.
  2. In the Administration Console open Servers > Application Servers. Select the server your application is deployed to.
  3. Select Java and Process Management > Process Definition.
  4. Select Java Virtual Machine.
  5. Insert the following line into Generic JVM arguments for WebSphere:
-noverify -Xshareclasses:none -javaagent:[/path/to/]xrebel.jar
  1. Press OK. When asked, save the master configuration and restart the server.

WebSphere Application Server Liberty Profile

To run XRebel, you need to specify the XRebel JVM argument in the JVM_ARGS environment variable before you launch the startup script:

  1. Run the JVM arguments setting command using the server command line:
  2. When using Mac OS or Linux:
export JVM_ARGS="-javaagent:[path/to]xrebel.jar"
  1. When using Windows:
set JVM_ARGS=-javaagent:[path/to]xrebel.jar
  1. Launch the server.

When you start your application server with this argument configured, the XRebel Hub agent is loaded at startup.