Maintenance and Scripts

• Home
• Installation
• Troubleshooting - Post Install

Routine Checks

Ensure the host software is regularly updated:

sudo apt update && sudo apt upgrade

Cronjobs inside the containers updates software inside, although updating/repulling the base image occasionally recommended.

If you are just repulling the base images for updates:

cd ./Linux && sudo ./update_images.sh

Warning: this will restart XNAT.

Before updating, you can edit the respective docker files located:

./xnat-setup/nginx/dockerfile

./xnat-setup/postgres/Dockerfile

Check for space occasionally, to ensure that your disk is not filling up. Cronjobs run that remove old files, but as the database increases in size, space may run low.

Check XNAT for updates to plugins and XNAT itself. Fill in xnat.cfg with the latest xnat version and plugin versions (ensuring the plugin versions are compatible) and run:

cd ./Linux && sudo ./update_xnat_war.sh

Warning: this will restart XNAT.

Scripts

In the Linux directory are the scripts for managing XNAT.

./restart_and_clean.sh - This deletes EVERYTHING and creates a fresh install. It will delete all data and docker containers and images.

./restart_tomcat.sh - This will restart Tomcat on a running XNAT. This is required for installing new plugins.

./restart.sh - This will restart the XNAT dfocker containers. This often solves some issues. See Troubleshooting.

./update_xnat_war.sh - for just updating the XNAT war file (for minor releases), you can run this.

./update_images - this updates XNAT the base images of postgresql and nginx. It restarts XNAT.

save/backup XNAT:

This makes a backup of EVERYTHING. If you do not want the archive zipped and backed up (which is likely if it is large), edit the script first.

A directory path/to/xnat-setup/Linux/backup is created.

The script performs a pg_dump within the container, and cleans the image of excess log files etc before saving it. It saves the containers as images in the backup directory.

/xnat-data/postgresql is backed up /xnat-data/xnat is backed up. If you do not wish the archive/build/cache directories to be backed up, or edit the script beforehand.

cd [path_to]/xnat-setup/Linux/

sudo ./save_and_restore.sh save

To restore XNAT from the backup directory:

First create a docker secret on the new server if it does not exist. This contains the password for the Postgresql server. To create type:

echo "[POSTGRESQL PASSWORD]" | docker secret create pgpass -

replacing [POSTGRESQL PASSWORD] with the actual password. The run:

sudo ./save_and_restore.sh restore

Installing Site Monitor Script:

There is a script that checks whether the XNAT website is available and restarts the XNAT docker stack if not. The script is located in

./scripts/host_scripts/site_monitor.sh.

Please add the site and email addresses to notify at the top of the script. To install you must add as a cronjob.

cronjobs.txt includes the cron command to run hourly.

Stopping and Restarting

To stop:

sudo docker stack rm xnat-stack

To restart:

sudo [path-to]/xnat-setup/Linux/restart.sh

Changing the Container Configuration (Ports, memory etc)

When you install XNAT, a copy of the file docker-compose-stack.yml is created, renamed docker-compose.yml and modified according to the settings in xnat.cfg. If you wish to change the settings in the docker-compose.yml file, you must write the changes and restart XNAT as per instructions above. If you reinstall XNAT, docker-compose.yml will be overwritten. The most common reason you will change docker-compose.yml is to add or change ports to the container xnat-web or change memory/cpu settings. These are described in other sections of the wiki.

Viewing and Changing all XNAT Site Config Settings:

Examples: - allowing Projects to be deleted via UI, or view Manage Files

The initial setting are taken from: ./xnat/templates/site-config-template

This is modified during the installation and used to set the initial site settings. To change these on working XNAT site, use swagger:

site-config-api - GET /siteconfig

Click on Try it out and click on Execute. This will return a json response that contains the entire site settings. This can be copied, altered and pasted into:

site-config-api - POST /siteconfig

Click on Try it out, paste the new json in the properties window and click on Execute.

Changing Postgresql Settings

You may need to change your Postgresql settings to allow more connections for example or if more resources are available. First of all, determine your system resources:

    lscpu - cpus x Threads per Core = Number of CPU cores
    lsmem - total online memory

You can use this calculator to optimise for your Postgresql:

https://pgtune.leopard.in.ua/#/

Select postgresql V12, Linux, Web Application and fill in the rest of the fields. Click on the Generate button. Copy and paste the contents of postgresql.conf tab into xnat.cfg, replacing the default values. The run the script:

cd postgres sudo /set_postgres_db.sh

This will change the Postgresql settings and save the running container as an image, replacing the existing postgres-xnat docker image.

Installing a logo into an existing XNAT

Make sure your logo is in png format, and anme it logo.png. Place this in:

[xnat_home]/scripts

Where [xnat_home] is specified in the xnat.cg file.

Then run:

sudo ./restart_tomcat.sh

Installing Plugins on an Existing XNAT

This will restart XNAT. Place the new plugins in your [path-to]/xnat-setup/plugins folder of your install directory and run as sudo:

cd [path-to]/xnat-setup/Linux/ && ./restart.sh

Adding External Storage

If you are installing a fresh XNAT, build XNAT with default xnat_home set in the xnat.cfg file (/xnat-data/xnat).

Stop XNAT using the instructions at the top of the page.

Delete the directory:

sudo rm -f /xnat-data/xnat/archive/

create a directory on the storage:

sudo mkdir [path to storage]/archive

Create a symlink:

sudo ln -sf [path to storage]/archive /xnat-data/xnat/archive/

Start XNAT using the instructions at the top of the page.

If moving an existing XNAT archive to external storage, stop XNAT using the instructions at the top of the page and make a backup of the existing archive:

sudo cp -R /xnat-data/xnat/archive/ /xnat-data/xnat/archive_backup/

Move the archive to the storage:

sudo mv /xnat-data/xnat/archive/ [path to storage]/archive/

Create a symbolic link:

sudo ln -s [path to storage]/archive /xnat-data/xnat/archive/

Start XNAT using the instructions at the top of the page. If everything works as expected, you may want to delete or move the archive_backup.

The JavaMelody XNAT monitoring page is useful to determine the number of connections and resources used by XNAT.

Creating and Installing SSL certificates

A script in the /certs folder can generate self-signed certificates, for testing.

You should be given 4 files:

• Private.key
• ca_bundle (intermediate)
• root.crt
• signed cert (certificate.crt)

If you are given other formats (pfx for example), you will need to convert these:

https://knowledge.digicert.com/solution/SO26449.html

You may need to concatenate some files:

cat certificate.crt ca_bundle.crt > bundle.pem
cat root.crt ca_bundle.crt > trust.pem

These correlate to the files in the xnat.cfg file:

ssl_crt = bundle.pem
ssl_key = private.key
ssl_trust = trust.pem

You may also need a dhparam files. These are generated on the server itself by running:

openssl dhparam -out dhparam.pem 4096

And in the xnat.cfg file:

ssl_dhparam_file=dhparam.pem

These must be placed in the /xnat-data/xnat/certificates directory.

Nginx must then be restarted. Type 'docker ps' to get a list of docker containers and find the ID of the nginx container. Then:

docker exec [nginx container ID] nginx -s reload