XNAT Configuration file xnat.cfg

Postgresql Version:

XNAT is best tested with Postgresql 16 as of the beginning of 2026. It should work with v17, please see the discussion below:

https://groups.google.com/g/xnat_discussion/c/chLfPMJ6aP4/m/2j_m0kYQDQAJ

If you wish to use v17 (or higher) edit the file ./postgres/dockerfile and change:

FROM postgres:16

to

FROM postgres:17

In addition in ./xnat/dockerfile, change postgresql-client-16 to postgresql-client-17.

Optimise and Configure XNAT Setup Script:

The xnat.cfg file is in 4 separate sections. XNAT, NGINX, TOMCAT and POSTGRESQL.

Optimise:

The xnat.cfg file contains all the parameters to optimise for memory and CPU cores allocated to XNAT and each of it's components. If you are running processes on the server, you must leave sufficient resources for these. To determine your system resources:

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

For Postgresql, you can use this calculator to optimise for your system:

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

Select postgresql V16, Linux, Web Application and click on the Generate button. Select at least 100 max connections. Copy and paste the contents of postgresql.conf tab into xnat.cfg, replacing the default values.

You may want to increase Tomcat resource, for example Xms=1024, Xmx=4096. You can do this in the xnat.cfg files.

You can edit docker-compose-stack.yml to change the default resources that are reserved for PostgreSQL.

          resources:
            reservations:
              cpus: '3'
              memory: 4000M

For large databases, you may want to increase this. In addition, large Postgresql databases will fail in docker unless the shared memory is increased from the default. This has been added to docker-compose-stack.yml as a mounted volume:

Under postgres section, add a volume:

- shm:/dev/shm

And add this at the end of the file:

volumes:
  shm:
    driver: local
    driver_opts:
      type: tmpfs
      device: tmpfs
      o: "size=1g,mode=1777"

When you build XNAT a copy of the docker-compose-stack.yml is made and renamed docker-compose.yml. You can make changes to this new file on an existing XNAT and restart XNAT as per the maintenance page.

Large Batch Processing:

If you are running large batch processing, you will need to ensure the postgresql maxconnections* setting is sufficiently high for the maximum number number of parallel processes (>100?). XNAT will run in swarm mode, as is the XNAT docker container service. If you are running on the same server (not recommended), any memory-resource limits set in the XNAT containers will work along with XNAT.

In addition, each container generates a new unique connection. If running many hundreds of containers per hour, you will need to adjust the Maximum Concurrent Sessions allowed in the XNAT Administer Menu (Site Administration/Security).

If docker containers are running on the same server, you will have to ensure to constrain the resources used by the containers. The batch launcher will attempt to launch all the containers at once unless you put in place a constraint - for example, ensure that command.json contains:

"reserve-memory": "XXXX",

Where XXXX is the memory in MB required to launch the container - if there is insufficient free memory, the Batch launcher will wait.

You can also adjust the Max Concurrent Finalizing Jobs in the Plugin Settings/Edit Container Service Host:

XNAT.cfg file:

site_name = Name of the XNAT Instance. No spaces, no underscores or other special characters.

xnat_host = URL or IP Address of XNAT instance. Required.

xnat_admin_user = The XNAT Administrator user that will be created during installation.

xnat_admin_email = XNAT Administrator Email configuration

xnat_smtp_server = Required for XNAT to send emails (default localhost)

psql_pwd = The password for the postgresql database. This needs to be complex.

xnat-data = The directory containing all the mount points for the docker containers, including the archive and database. The default is /xnat-data.

SSL CONFIG:

ssl = Whether SSL certificates will be used.

ssl_crt_file = Name of the crt file - no paths, just filename

ssl_key_file = Name of the key file - no paths, just filename

ssl_trust_file = Name of the key file - no paths, just filename. If you have no trust certificate put 'none'.

ssl_dhparam_file = dhparam.pem - - this is generated on the server. To generate run openssl dhparam -out dhparam.pem 4096

RESOURCE SETTINGS:

These settings are not currently used.

memory =

This is used for the Garbage Collector and also when performing a postgreql dump/restore in parallel:

cpu_cores =

TOMCAT:

JVM Heap settings:

Xms = Initial heap size.

Xmx = Max heap size. For deployment minimum recommended 4096m (4GB)

POSTGRESQL:

use_pg_alpine = Only set True if upgrading from an old xnat-setup instance/database that uses Alpine as a base image. Else, leave as false. Alpine databases are not compatible with deb-based postgresql images.

These change the postgresql settings. The website https://pgtune.leopard.in.ua/#/ is useful in determining the optimum settings for your system

XNAT VERSION:

xnat_version=1.10.0

XNAT PLUGINS:

Install plugins - set as true/false

ohif_viewer=true

container_service=true

batch_launch=true

xsync =true

ldap=true

dqr=true

plugin_versions: