Page tree
Skip to end of metadata
Go to start of metadata

Each day of the XNAT Workshop agenda will be split into two types of sessions: Lectures in the morning, and Practicals in the afternoon. To participate in the practical sessions, attendees are expected to bring a sufficiently powered laptop to run XNAT virtual machines. There will be wi-fi connections available in the conference center, but users are also strongly encouraged to download necessary components prior to the start of the Workshop to minimize delays and setup time.  Please contact us if you have questions about the required hardware.

Laptop Requirements & Recommendations

Operating Systems:

  • Mac OS 10.8 and up (preferred)
  • Linux: Debian-based (Debian, Ubuntu, Linux Mint) or Red Hat/Fedora-based (RHEL, Fedora, CentOS, Scientific Linux)
  • Windows 7 and up

Hard Drive: At least 40 GB of free hard drive space available, SSD preferred for performance

Processor: 2 gHz and up recommended

RAM: 8 GB and up recommended

Required Software

  • A fully supported browser. Most modern browsers–Chrome, Firefox, Safari, Internet Explorer, Opera–work with XNAT. If you are using Internet Explorer, you should have at least IE 10. Note that Microsoft Edge is not supported at this time!
  • The Java 8 JRE  for upload and download applets.
  • VirtualBox. You can use other virtualization platforms that support Vagrant, including Parallels and VMWare Workstation or Fusion, but the xnatstack base box and all of the xnat-vagrant configurations are based on using VirtualBox as the provider. That means you'd need to use another Vagrant base box, install any missing dependencies, and manage the configuration and installation of XNAT manually. Since VirtualBox is available free of charge and can exist alongside the other virtualization providers, we've opted to just support it for now.
  • Vagrant  required to create an XNAT virtual machine (Vagrant can be installed on OS X using homebrew or on most Linux variations using the standard package manager for the platform)
  • Vagrant Manager provides a convenient interface for managing vagrant machines.
  • Git for cloning data from XNAT development repositories.
  • Windows users only: Cygwin or Git Bash (which comes with Git). Optionally, if you are comfortable with MobaXterm, that is usable with some minor workarounds. 
  • An environment for code editing in practicals and hackathon projects. We recommend the following applications, all of which are either open-source or offer fully functional trials.

Predownload the XNAT Vagrant Base Box

Many of the practical sessions and hackathon sessions presume the use of Vagrant to create virtual machines that run the XNAT application. The XNAT team has created a Vagrant base box that has many of the services required to run XNAT already installed, greatly reducing the time required to build new instances. This is the xnatstack Vagrant base box. You should download and install this base box before leaving for XNAT Workshop 2016: this is a fairly large download and will be even slower if all attendees are trying to download it at the same time on the same wireless connection!.

To download the box, run the following command:

vagrant box add nrgxnat/xnatstack-ubuntu1404-docker --provider virtualbox

This will download the base box and cache it in your Vagrant data folder.

You can check for available updates to the xnatstack Vagrant base box by running the following command:

vagrant box update --box nrgxnat/xnatstack-ubuntu1404-docker

Taking care of this ahead of time will leave you more time to focus on the important parts of the sessions and practical exercises. If for some reason you don't get it downloaded ahead of the workshop, don't worry – we'll have it available on USB thumbdrives when you arrive.

You can also download the XNAT Vagrant base box by creating a new Vagrant project that references the box, then creating a VM instance from that project. Run these commands to do this:

$ vagrant init nrgxnat/xnatstack-ubuntu1404-docker
$ vagrant up

The first command creates a very basic Vagrantfile. After deleting all the comments in that file, you're left with this:

Vagrant.configure(2) do |config| = "nrgxnat/xnatstack-ubuntu1404-docker"

When you run the vagrant up command, this will reference the Vagrantfile and create a new virtual machine based on the XNAT base box.

If you want to further configure your virtual machine, you can have a look at the Part 1 Installing XNAT practical session documentation or use the XNAT Vagrant project to automate a great deal of the setup and configuration.

Notes for Windows Users

We have documented several common (and a few uncommon) problems that Windows users have run into with installing and using Vagrant. Running Vagrant from Cygwin or MobaXterm will likely help. Here are some more helpful hints: Troubleshooting XNAT Vagrant Installation for Windows Use. We highly recommend running through the Vagrant's "Getting Started" sequence before the Workshop to make sure you're able to run Vagrant on your local machine.

  • No labels


  1. Will we also have to install PostgreSQL directly on the main OS?  I've had problems installing it on my Windows 7 laptop.

    1. Only if you're planning on running XNAT directly on that machine. If you're going to work with a virtual machine, you'll only need to install PostgreSQL there. In fact, you won't need any of the prerequisites for XNAT on the host machine, just the prerequisites for running Vagrant, which is Vagrant itself, VirtualBox, and on Windows it's advisable to have Cygwin or Git Bash installed as well.

  2. Another quick tip for Windows users using Cygwin - here's how to break out of Cygwin's directory structure and map to your C: drive.

    1. For those stubborn Windows hardliners, I sometimes use for remote computing which is awesome and easy-to-use. Just tried it for ssh connect to a vagrant's XNAT VM and it worked.

      I am not sure what will be exactly required for the practical sessions but it might be a good alternative to the aforementioned tools as well. 



  3. Hellos,

    What is the password for 'xnat' user on the vagrant machine?

    I tried 'xnat' , 'xnat4life' , 'xnat170' , 'admin'  .. and all that i could think of. Doesn't work.

    "vagrant ssh"  , logs me in as 'xnat' user, but I need 'sudo' password. It's not mentioned here:

    Gracias (smile)

    1. Never mind.

      "sudo su - xnat"

      "sudo passwd xnat"

  4. I believe I got the vagrant vm working. It seems to up and running but I cannot connect to the vm.  When I try vagrant ssh, I get many error lines starting with a "(Vagrant::Util::Subprocess::LaunchError)" message.  I went to the VirtualBox application and saw the xnat vm is running.  I click on it and it asks if I want to connect and I say Yes.  Then a terminal window comes up wanting a username/password.  I tried xnat for the username but nothing I tried works for the password (including no password).  I am not sure how to connect to the vm.



    1. Hey Mike,

      What OS are you running on? Have you checked that your VirtualBox and Vagrant versions are both the latest available?

      There are a lot of different possible causes for this error, so it's hard to say what it might be specifically. Check out this search on the vagrant issues site for some possible causes/solutions.

      1. The virtualbox is 5.0.20r which is the latest version and vagrant is the latest one (1.8.1) I saw. 

        1. Mike, I think Rick is asking what OS your computer is running, not the VM. There are a lot of issues related to Vagrant and VirtualBox that are unique to Windows users, which we have been cataloging here: Troubleshooting XNAT Vagrant Installation for Windows Users.

          Also, if you are using Windows, I strongly recommend running your Cygwin or Git Bash terminal app as an Administrator.

          1. It is a Windows 7 OS but my issues have been all resolved until I get new ones! (smile)


  5. Hi Rick,

      It would be useful if you could post what we should be expecting to see when we issue "vagrant ssh". I'm running MacOS 10.11 and, after a seemingly trouble-free installation of vagrant and the installation of the nrgxnat/xnatstack-ubuntu1404-docker box, all I get is the following:

    Welcome to Ubuntu 14.04.4 LTS (GNU/Linux 4.2.0-27-generic x86_64)


     * Documentation:


      Ubuntu 14.04.4 LTS                          built 2016-04-25



    I checked for an xnat user, but there didn't seem to be one. I have a single file 


      Any suggestions as to what I should do with this? Should I install this? Then what?





    1. Looks like the vagrant-shell<date>-<hex>.sh script hasn't run on the VM yet. I believe what it's supposed to do is copy (scp) this shell script  into the VM and execute it there, where it will then install all the required components for the environment of xnat. May be there is a file permissions issue. Running everything as admin user, resolves most problems. (smile)

      See the comments on the sub-link of this page: Troubleshooting XNAT Vagrant Installation for Windows Users

      vagrant ssh should log in as xnat user.

      GIT Bash
      $ vagrant ssh
      Loading C:/Users/aaguptess/XnatWorkshop/Repos/xnat-vagrant/configs/xnat/config.yaml for Vagrant configuration...
      Welcome to Ubuntu 14.04.4 LTS (GNU/Linux 4.2.0-27-generic x86_64)
       * Documentation:
        Ubuntu 14.04.4 LTS                          built 2016-04-25
      Last login: Wed Jun  1 21:12:53 2016 from
    2. If all you've done is run vagrant up with the XNAT box, then that's exactly what you should see. The Puppet package is already installed as part of the build, so that should actually have been removed (I just made a fix to the xnatstack build project). At this point you have a virtual machine running on the xnatstack box. The main feature of that box is that it has all of the dependencies required by XNAT already installed, meaning you don't have to go through the process of downloading and installing the JDK, Tomcat, PostgreSQL, etc., every time you want to bring up a new XNAT VM. None of the configuration required for XNAT is done, however.

      The xnat user will be installed if you run from the full XNAT Vagrant project, which you can get at You can just get the archive from the Downloads page or clone the git repo if you want to be able to update. For that, you can run from a few different configurations as described in the README file. The easiest is the standard xnat configuration:

      $ git clone
      $ cd xnat-vagrant/configs/xnat
      $ ./

      You'll probably want to create a file named local.yaml in that folder. Basically this lets you set variables for the Vagrant build. Vagrant doesn't really let you pass variables and arguments into your build, so we have shoehorned our own way of configuring the Vagrant provisioning scripts. Eventually we'll be replacing those shell scripts with a Puppet 4 configuration that will actually leverage the work our internal IT team does to configure VMs for development, testing, and production deployment internally.

      We're not there yet, though! We have managed to get the amount of configuration most people will need to do to a minimum, however. I've attached the configuration I use for my standard dev VM.

      The other way you can get an xnat user configured is to work through the Part 1 Installing XNAT practical exercise on this wiki. By the end of that, you'll have a VM that is very similar to what you'll get running the XNAT Vagrant build. That's what we'll be working through in the first part of the Monday afternoon practical session at the workshop.


  6. One tip for Mac users...if you have your DYLD_LIBRARY_PATH environment variable set for whatever reason, Vagrant does not seem to like this at all. Unset it before starting the above steps.