Troubleshooting a Vagrant XNAT VM

Because your Vagrant VM lives on your local machine, it is subject to the occasional whims of your local machine -- i.e., unexpected shutdowns, restarts, etc. Restarting your local machine as needed is second nature. But then you'll need to reboot your XNAT VM as well, the next time you want to use it. Here is a set of simple commands to run.

Restarting Your Webapp

1. Bring up your Vagrant VM if it's down. Open the Terminal and navigate to the xnat-vagrant config folder containing your VM. Then run the following:

CODE

$ vagrant up 
$ vagrant ssh

2. Restart the XNAT webapp. Within the Vagrant SSH shell, run the following, where "[date]" is today's date in YYYY-MM-DD format:

CODE

$ sudo systemctl restart tomcat9.service 
$ sudo tail -f /var/log/tomcat9/catalina-[date].log

The Catalina log file will tell you when the XNAT Tomcat server has finished restarting. It normally takes a minute or so.

Recovering from More Severe Issues

If your Vagrant VM gets into a state that is irrecoverable, there are a few things you can do.

Option 1: Replace the XNAT war file

You can download a released version of the XNAT war file from https://www.bitbucket.org/xnatdev/xnat-web/downloads. Do this first, or build your own local war file from the XNAT development repos if you prefer.

1. Shut down Tomcat. Within the Vagrant SSH shell, run the following:

CODE

$ sudo systemctl stop tomcat9.service

2. Sudo as the 'xnat' system user and remove the old war file and the exploded war.

CODE

$ sudo su - xnat
$ rm -rf /var/lib/tomcat9/webapps/*

3. In a separate terminal window, copy your local war file to the VM's webapps folder, authenticating as the 'xnat' system user. Note that you will be prompted for that user's system password. You can reset it by sudoing to the root user within your XNAT VM (sudo -i) and setting the new password (passwd xnat).

CODE

$ scp xnat-web-1.8.3.war xnat@10.1.1.17:/var/lib/tomcat9/webapps/ROOT.war

4. Restart Tomcat and watch Catalina for successful startup.

CODE

$ sudo systemctl restart tomcat9.service 
$ tail -f /var/log/tomcat9/catalina-[date].log

Option 2: Re-deploying your VM with new settings

If you start running into memory constraints, for example, or need to adjust other parameters of the Virtual Machine setup, you can bring your VM down and redeploy it to pick up any new settings in your local.yaml file.

1. In a Terminal shell, navigate to your xnat-vagrant config directory. Here, we use the "xnat-dev" config as an example.

CODE

$ cd /path/to/your/xnat-vagrant/configs/xnat-dev

2. Edit your local.yaml file to make whatever VM configuration changes are required.

3. Delete the cached setup parameters.

CODE

$ rm -rf .work

4. Instruct Vagrant to rebuild the VM with new parameters. Note that the "--provision" flag is required.

CODE

$ vagrant reload --provision

Option 3: Dumping the Database

This is a nuclear option, and will completely wipe your XNAT clean of all project and user data. It is essentially the "factory reset" option. Use this only as a last resort before destroying the Vagrant VM altogether.

Upload and execute this bash script from within your XNAT VM, logged in as the 'xnat' system user.

CODE

#!/bin/bash

sudo systemctl stop tomcat9.service
dropdb xnat

for DIR in "/data/xnat/archive /data/xnat/build /data/xnat/cache /data/xnat/ftp /data/xnat/prearchive"; do
    echo "Deleting all contents under ${DIR}..."
    find ${DIR} -mindepth 1 -maxdepth 1 -exec rm -rf '{}' \;
done

createdb xnat
sudo systemctl start tomcat9.service

Note that this also resets the default "admin" user and its credentials.