Skip to main content
Skip table of contents

Step 1 of 8 Create a new virtual machine


In this step, you'll create a new virtual machine that will provide the platform for deploying your XNAT server instance. You'll use the nrgxnat/xnatstack-ubuntu1404-docker Vagrant base box as the basis for your new VM, which provides many of the prerequisites required for XNAT to function.

First create a folder to contain your Vagrant project then change to that folder:

$ mkdir xnat-vagrant
$ cd xnat-vagrant

Now create a new Vagrant project and initialize it:

$ vagrant init nrgxnat/xnatstack-ubuntu1404-docker

This will create a basic Vagrantfile that specifies the box to use for the VM. You'll probably want to add at least a little bit more information to the file, such as a distinguishable VM name, IP address, host name, and enough RAM to be able to run all of the services required for XNAT. You can edit the Vagrantfile to look something like this:

# -*- mode: ruby -*-
# vi: set ft=ruby :
Vagrant.configure(2) do |config|
    config.vm.define 'xnat-11' = 'nrgxnat/xnatstack-ubuntu1404-docker' 'private_network', ip: ''
    config.vm.hostname = 'xnat-11'
    config.vm.provider 'virtualbox' do |v|   = 'xnat-11'
        v.memory = '2048'

The name of this VM is set to xnat-11 and the IP address to The fully qualified domain name of this server would be This server name is part of a block of specially reserved addresses configured in XNAT's DNS to resolve to IP addresses on local private network subdomains.


Once you've finished composing your Vagrantfile, you can create your new virtual machine with a simple command:

$ vagrant up


This will cause a lot of stuff to happen! But once this process is completed, you'll have your clean new virtual machine! You can access the server directly by typing:

$ vagrant ssh

Windows Users

Assuming you are using MobaXterm as instructed on Part 1 Installing XNAT 'vagrant ssh' will not find the ssh key.

Substitute {username} for your windows profile directory. Type "echo $USERPROFILE" if you do not know what this is.

Do this only once:

cp /drives/c/Users/{username}/.vagrant.d/boxes/nrgxnat-VAGRANTSLASH-xnatstack-ubuntu1404-docker/1.0.1/virtualbox/vagrant_private_key ~/xnat_private_key


Each time you want SSH to your instance type:

ssh -i ~/xnat_private_key vagrant@


You'll connect to the VM as the default user vagrant and should see something like this:

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


Notice that this configuration sets both an IP address––and a fully qualified domain name––for the new virtual machine. The XNAT IT team has set up a number of DNS entries on the domain–xnat-11 through xnat-13, xnat-21 through xnat-23, xnat-31 through xnat-33, and xnat-41 through xnat-43–that route to the IP address 10.1.7.xx, where xx is the number in the server name. If you use these IP and server addresses, you'll be able to use your VM directly as long as you can resolve against any standard DNS server. In this case, will resolve to, allowing you to reach the server through your browser without any further configuration.

In most cases, however, the hostname doesn't actually mean anything to anyone other than the virtual machine itself: you can't access the virtual machine through that hostname, because there is no DNS that can resolve it. To make the box work correctly, you can modify your hosts file to specify the mapping of server name to IP address. On most systems, this file is located in /etc/hosts, but on Windows it's located in C:\Windows\System32\drivers\etc\hosts. On Windows, you'll need administrator privileges to edit the file, while on Linux or OS X you'll need sudo access. The line you add to the hosts file should look something like this:

CODE    xnat-11

Note that this actually adds a fully qualified domain name (the server name xnat-11 with the domain name, aka an FQDN) as well.

You should also do this on the virtual machine side so that it can also resolve references to its FQDN:

sudo nano /etc/hosts

You'll see a line similar to the one below:

CODE xnat-11 xnat-11

Change this line to read:

CODE xnat-11

Type Ctrl-X, then Y (for "yes"), then Enter to save. Both sudo and nano are explained in the next section.


If you run into any problems, be sure to ask for help from any member of the XNAT development team!

You now have a functioning and provisioned virtual machine that will provide the hosting environment for your XNAT installation.

Go to the next step

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.