XNAT Vagrant VM Setup

Setting up a virtual machine running the latest XNAT release – or your own custom code – is quick and fairly painless, particularly once you have your XNAT Stack base box installed and cached. Follow the instructions here:


Container Services Plugin Setup

There will be a Container Services presentation on Day 1 of the workshop. If you are interested in running Docker containers with XNAT data or developing images for Container Services, you will need to install the following plugins:

  • XNAT Container Services: This plugin adds the Container Services API, Admin controls, and UI to add images and commands, and run containers from XNAT report pages.
  • XNAT Selectable Table: This plugin overwrites the core XNAT version of the image session scan listing and allows you to run scan-level containers, such as dcm2niix. It is also required to support the new batch-selection feature in Container Services 1.3.1.

For help installing plugins, see: Deploying Plugins in XNAT

Example Containers and Images

In order to run some basic containers in XNAT, install these images through the Admin UI: 

  • xnat/dcm2niix:latest
  • xnat/debug-command:latest

For help, see: Getting Started with Container Services


Scratch Data Setup with XNAT Populate

If you want to quickly set up a series of XNAT projects with usable and anonymized sample data, the XNAT Populate tool is a very useful tool to get this done. Get started by opening up your Terminal or Git Bash app and navigating to your local repos directory and cloning the XNAT Populate git repository.

$ git clone https://bitbucket.org/xnatdev/xnat_populate.git

XNAT Populate requires Groovy to run. See http://groovy-lang.org/install.html

The XNAT Populate repo contains a series of predefined projects with associated XNAT users, anonymized subjects, image sessions, subject assessors, image assessors, and resources. These projects use only standard XNAT data types, though some projects require additional plugins. To add data from a single project, run this simple script:

$ groovy populateXnat.groovy -s http://10.1.1.174 -u {username} -p {password} -d {project_ID} 

On a standard XNAT VM, use admin/admin as your credentials and Nifti_Proc as an example project ID. You can also specify a text file for the -d parameter to add a list of projects. The full list of supported projects in XNAT Populate is listed here: xnat_populate_cheat_sheet.md

A few projects in the XNAT Populate directory, such as NIHCC_Chest with 30,000 image sessions, contain more image data than a typical Vagrant VM can hold. Please read each project description carefully before importing it.

Full XNAT Populate Documentation: XNAT Populate

Troubleshooting Large Project Uploads with XNAT Populate

If you run into issues where XNAT Populate is timing out midway through a project import, you are probably running into memory issues with your Vagrant VM. To fix this, you can set a larger allotment of RAM for your virtual machine. Here's how to do that:

  1. Go to your local xnat-vagrant repo and open the config folder for the VM that you're running. (Example: /xnat-vagrant/configs/xnat-release).
  2. Open config.yaml in your text editor of choice and edit the line that specifies ram: 2048. Set this to a higher value, either "4096" or "8192". Save the file. 
  3. Delete the vars.yaml file from this same config folder. This gets created when a VM is initialized, and its settings will overwrite config.yaml if it is not deleted.
  4. Open your Terminal or Git Bash console, and halt your vagrant VM: $ vagrant halt
  5. Force your VM to reload with the new config parameters with the command: $ vagrant reload


$label.name