Upgrade

• Home
• Installation

Plugins and XNAT should be updated regularly. See maintenance for updating the XNAT version or/and plugins.

Upgrade of xnat-setup:

For XNAT 1.9x -> 1.10, this is required.

This is for upgrading the xnat-setup repo etc. It is only for major updates.

Important Notes:

• Note, with XNAT 1.10, the xnat.cfg file has changed to include xnat-data= to replace xnat-home, archive, postgresql mount points. Assuming all mount points are already under /xnat-data (./xnat, ./postgresql ./import_data) then leave as /xnat-data in the new xnat.cfg file.

• Postgresql Alpine: In old versions of xnat-setup postgresql:alpine was used. Apline databases are not compatible with debian databases. Only if you an Alpine-based database, then set use_pg_alpine=true in the new xnat.cfg file.

• If you are using SSL certificates but do not have a trust cert, comment out ssl_trusted_certificate in ./nginx/xnat_ssl.conf.

Warning: This will stop your current server. Backup everything! Please read the troubleshooting pages if you encounter and error, specifically database errors.

• Rename your xnat-setup directory to xnat-setup-backup.
• Backup using the save and restore script in the Linux directory. This will create a directory /path/to/xnat-setup/Linux/backup with all your current images and data. WARNING - this copies and compresses the entire archive - use with caution or edit the script before using. If you do not want to backup the entire archive comment out the line: tar -zcvf ./backup/xnat_home.tar.gz -C $xnat_home ..
• Run:

cd Linux
sudo ./save_and_restore.sh save

• Do not stop your current XNAT - settings are extracted from the existing XNAT and it needs to be running.
• Download the latest version of xnat-setup.
• Fill in the xnat.cfg file, based on your old xnat.cfg file, but enter the lastest XNAT version and compatible plugins. The Postgresql Password (psql_pwd) is taken from the running XNAT container, not xnat.cfg - you can leave this empty
• Make any custom changes to the docker-compose-stack.yml file (ports, cpu/memory, any additional custom mounts) - this should be similar to the docker-compose.yml file of your old installation. Do not change shared_memory / shm parts of the new docker-compose-stack.yml file.
• Make sure your plugins that are not listed in xnat.cfg are copied over to the new ./plugins directory.
• run:

cd Linux
sudo ./build.sh upgrade

A warning will appear, asking for confirmation. Make sure the warning contains UPGRADE else it may be building from scratch - although this will fail and not delete anything if the /xnat-data directory exists

XNAT should be upgraded. If not, please read the troubleshooting page

Update of Nginx/Postgresql docker base images:

If you wish, you can edit the Dockerfiles /path/ro/xnat-setup/nginx/ You can then run the script - Warning! This will restart XNAT:

cd Linux
sudo ./update_images.sh

It will also update and upgrade software in the xnat-web.

You may want to save the container to save the settings. This will replace your existing xnat docker image. You could save as xnat2, therefore keeping your original image. Then you'd need to update docker-compose.yml to select which docker image it uses. To get the container id:

docker ps

Then run:

docker commit [container id] xnat

Note for Major updates of Postgresql, follow the instructions below for manual update.

Update xnat.war only:

If you wish to keep everything the same, but just update your xnat.war file, update your xnat.cfg file to the newest xnat version:

xnat_version=XXX

Read the release notes to ensure that you are able to update easily from your current version and that plugins are compatible (you may have to update your plugins).

Place this script in your Linux directory:

update_xnat_war.sh

sudo cd Linux && ./update_xnat_war.sh

Manual update of components:

These instructions are effectively the contents of the automatic script.

Nginx upgrade:

You may wish to upgrade the nginx settings. All files are located in [path-to]/xnat-setup/nginx. Most importantly the files Dockerfile and xnat.conf

To upgrade nginx, ensure that the xnat.conf file is uptodate. Use this site to find the appropriate intermediate settings.

Edit the Dockerfile and change the nginx tag. This is the very first line in the format:

*FROM nginx:VERSION-alpine*

The xnat-setup script uses alpine image. Tags can be found https://hub.docker.com/_/nginx?tab=tags&page=1&ordering=last_updated

Then run:

cd  `[path-to]/xnat-setup/nginx
docker build -t nginx-xnat1 .

Then restart docker:

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

Postgresql Upgrade:

The current default for xnat-setup is Postgresql v16. The client in the XNAT container however is v17 in the current version of xnat-setup (>XNAT 1.10). If you do not have this version, upgrade xnat-setup fully with Postgreql v16 and then upgrade Postgresql after using the following instructions.

The xnat-setup script uses the official postgresql Docker image as a base image. As of July 2026, v16 is the most tested version with XNAT.

For major updates, the best method (although potentially long) is to perform pg_dump and pg_restore. To do this, the Postgresql Client must be equal or greater to the version in the XNAT container performing the nightly database backups.

If upgrading to a version > 17, you must change the client version, go into the XNAT container:

cd ./Linux && sudo ./docker-bash.sh

apt-get -yq update && apt-get remove postgresql-client-[old version] && apt-get install postgresql-client-[upgrade version]

In older versions of xnat-setup, you may have to install postgresql-common first then run the command:

/usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

Continue with these steps if upgrading from v16 to v17:

Nightly backups using pg_dump are already performed, and the script ./Linux/restore_from_pg_backup.sh can be used to perform a pg_restore from a backup.

Leave overnight for a pg_dump to be performed or run:

./docker-bash.sh

/data/scripts/cronjobs/pg_backup.sh

Edit the file ./postgres/dockerfile:

*FROM postgres:VERSION*

The tags are available on dockerhub

If you are using an Alpine image you must upgrade to an Alpine image.

Edit xnat.cfg to update your postgresql settings for your new version of Postgresql.

Then run:

cd  `[path-to]/xnat-setup/postgres
docker build  --build-arg TIMEZONE=[timezone] -t postgres-xnat .

Replace [timezone] with your host timezone. Type printenv to see what your host timezone is (TZ), for example:

docker build --build-arg TIMEZONE=Europe/London -t postgres-xnat .

If using alpine, edit dockerfile-alpine then run:

docker build --build-arg TIMEZONE=Europe/London -f dockerfile-alpine -t postgres-xnat .

Run restore_from_pg_backup.sh and follow the instructions fully:

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

Update your postgresql settings:

cd [path to]/xnat-setup/postgres
sudo ./set_postgres_db.sh