Deploying Plugins in XNAT

Installing plugins in XNAT is as simple as installing a properly formatted jar in the XNAT plugins folder.

Make sure no one is logged in and using your XNAT before taking these steps. See Administering Users for notes on how to view active user sessions. It would also be a good practice to notify users of an upcoming maintenance window and perform this update then. See Notifications and Alerts in XNAT for reference.

Step-by-step guide

This presumes you have a valid plugin jar to install. Unless the documentation for a specific plugin tells you otherwise, the standard way to create a jar for an XNAT plugin is to navigate to the root folder of the plugin code and run the following:

CODE

$ ./gradlew jar

Note that your plugin may require a different jar construction. See your plugin repo's README for clarification.

After this process completes, a jar file will be created in the build/libs subdirectory.

Step 1: Shut Down Tomcat

If your web application is currently running, shut it down. SSH into your XNAT web application, then shut down your Tomcat server:

CODE

$ sudo systemctl stop tomcat.service

Step 2: Install Your Plugin JAR file

Copy your plugin jar file into the folder ${xnat.home}/plugins. The location of xnat.home depends on your system configuration.

Step 3: Start Up Tomcat

Start Tomcat back up.

CODE

$ sudo systemctl restart tomcat.service

XNAT will take a moment to unpack and incorporate the new plugin before the application comes back online. You can monitor the progress of the application as it builds by following Tomcat's catalina.out log file. The specific path to your Tomcat logs will depend on your system configuration.

CODE

$ tail -f /var/lib/tomcat/logs/catalina.out

When you see a message in the log file like INFO: Server Startup in 105462 ms, your XNAT is ready to use again.

An XNAT plugin can consist of a number of different components, including:

Data types in the form of XSD files
Velocity templates
JavaScript files
CSS style sheets
Java code for REST services, Velocity screen or action classes, Spring MVC controllers, services, database entities, and more