- About XNAT
- News & Events
- XNAT Marketplace
- Contact Us
This page is intended only to document the usage of the setup and update scripts and is not intended to be in-depth documentation on installing and configuring XNAT. For information on installing XNAT, refer to the installation documentation.
Scripting these build phases is the task of the setup and update scripts. These are located in the bin folder of your XNAT builder installation. There is also a quick deploy script that can be used to quickly push out changes to display elements that don't require a rebuild of code or database changes. Each of these scripts is described below.
XNAT setup can only be used on a clean installation of XNAT. That is, setup can not have been run previously.
OK, this isn't completely true: setup can't be run if the folder deployments/project exists. You can delete the folder and re-run setup if you need to do so for some reason:
rm -r deployments bin/setup.sh
In production scenarios, you very rarely want to do this, but in a development environment you may want to try building from a clean environment at times to verify customizations you've created work properly in a clean installation.
To set up your XNAT installation, invoke the setup script. Which script you use depends on your environment:
For simplicity, this documentation will use the shell script version of commands. Windows differs only in the path separator (i.e. '\' as opposed to '/') and script extension (i.e. ".bat" as opposed to ".sh").
So for a basic set-up process, run the following commands:
Copy the resulting war file into the webapps folder of your Tomcat installation.
You can push the application directly into Tomcat, avoiding step 3, by adding the -Ddeploy=true flag to your script invocation:
bin/setup.sh -Ddeploy=true. This deploys the application into the webapps folder underneath the location indicated by the maven.appserver.home property in your build.properties file.
As noted previously, there's more to the setup process than the build script! You also need to initialize your database and bootstrap the security data. For a full description of this process, refer to the installation documentation.
XNAT update is used to re-build and re-deploy your XNAT installation to include any changes, additions or deletions of code or functionality. In opposition to the setup process, update can only be run on an XNAT installation that has had setup run on it.
To update your XNAT installation, invoke the update script:
As with the setup script, you can build with or without automated application deployment. To deploy automatically, just append the same -Ddeploy=true flag to the update script.
Updating the Database
Once you've updated your deployment, you'll also need to update your database if you've made any changes to your data-type schema (this is similar to the database initialization process for XNAT installation, but doesn't require prepopulation of the database):
Once you've updated your database (if necessary) and re-deployed your application, you can restart Tomcat and access the application to verify your changes.
The full update process above is useful if you've made changes to your Java code or changes that affect your database schema, e.g. changes in a data type. However you'll often just make changes to some Velocity templates or graphics or something like that. In that case, the full update procedure is quite time consuming for no good reason. For this purpose, you can do one of two things:
As with setup and update, how you invoke the quick deploy templates script depends on your environment: bin/quick-deploy-templates.sh for *nix and bin\quick-deploy-templates.bat for Windows.
Unlike setup and update, the quick deploy templates script does not have an option for deploying to the application installation in Tomcat's webapps folder: its entire raison d'être is to deploy to the application installation in Tomcat's webapps folder, so there's no use for this utility if you're only deploying through a war file.
As of the initial release of XNAT 1.6, the quick deploy templates script does not support updating from modules in your module repository. There is currently an improvement request in the XNAT issue tracking system for this enhancement.