-
Notifications
You must be signed in to change notification settings - Fork 0
Upgrade
Plugins and XNAT should be updated regularly. See maintenance for updating the XNAT version or/and plugins.
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
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
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:
sudo cd Linux && ./update_xnat_war.sh
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 xnat-setup script uses the official postgresql Docker image as a base image. As of July 2026, v16 is the most tested version. See note above if you wish to update Postgresql. Note, when performing ./restart.sh, postgresql is updated and the database reindexed and vacuumed.
For major updates, the best method (although potentially long) is to perform pg_dump and pg_restore. However for major upgrades, it is best to perform pg_dump and pg_restore from a more uptodate postgresql client. To do this, go into the XNAT container:
cd ./Linux && ./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
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 /data/scripts/cronjobs/pg_backup.sh
Edit the file ./postgres/dockerfile:
*FROM postgres:VERSION*
The tags are available on dockerhub
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 Europe/London.
Run restore_from_pg_backup.sh and follow the instructions fully.
Update your postgresql settings:
cd [path to]/xnat-setup/postgres
sudo ./set_postgres_db.sh