Configuring a Container Host

All Container Service site configuration screens are available via the top navigation under Administer > Plugin Settings

Connecting XNAT with your Container Host

XNAT needs to know how to communicate with your container host over HTTP. By default, the Container Service looks for a Docker server to be its container host, and listens for connections on a UNIX socket. If docker is listening on the default socket, and XNAT can access that socket, then you won't need to change anything. The default container service settings correspond to the default docker settings.

If your Docker server is set up to listen on the default socket but your XNAT cannot communicate with Docker, you may need to add the "xnat" system user to the Docker group.

If your Docker server is on a separate machine from your XNAT server, and XNAT has no access to the Docker socket, then you need to enable communication on both sides.

  • Enable docker to listen for TCP connections. These can be either secured (HTTPS) or unsecured (HTTP).
  • Set up a new docker server in the container service administration page. (See screenshot above). Click the "New Container Host" button. Enter a user-friendly name for the server, the URL at which your docker server is listening, and (if you configured docker to listen over HTTPS) the path to the certificate file used to secure communications.

Docker HTTP

We recommend only allowing access to the docker server through the socket or HTTPS. Do not enable HTTP unless...

  • Your docker server is behind a firewall. Enabling HTTP with no firewall would allow anyone on the internet to execute arbitrary code on your docker server.
  • You are careful about the containers you allow XNAT users to execute. In particular, be very careful about allowing users to execute custom scripts. The containers run inside your firewall, which means a container could use the docker HTTP API to start new containers. This would allow users to completely control the docker server and view any XNAT data, bypassing the XNAT security model.

Enabling access to docker only through the socket or HTTPS does not create these problems.

Editing or Setting Up a New Container Host

Currently the Container Service only supports having one Container Host Definition. There is no practical difference between "Edit" and "New Container Host" since a new host definition will replace the existing one.

Container Host Definitions support a variety of configuration options, most notably allowing administrators to enable and configure the use of Docker Swarm. To get started, click in the UI to Edit an existing host definition or create a new one. You will see a dialog like this:

Initial Settings

SettingDescriptionDefault Value
Host Name

This is a text field that serves as a label for your host configuration

Local Socket
URLThis is the HTTPS or UNIX path to where your Docker Server is configured to listen for new connections. See Processing URL for more detail.


Certificate PathThis is the local file path to your server's SSL certificate, if needed to authenticate the above URL

Enabling and Configuring Docker Swarm Mode

"Swarm mode" is Docker's term for enabling batches of containers to be managed in a queue and farmed out across multiple processing nodes. By default, Docker Swarm mode is off, since it requires a Swarm-enabled configuration to be set up on your Docker Server. However, we strongly recommend enabling swarm mode on your server and turning this feature on in the XNAT Container Service. Even if you only define a single processing node, the container queuing feature gives your XNAT system much more resiliency for handling processing in bulk and/or automated processing triggered via the Event Service.

Refer to the Docker Swarm Mode documentation for details on how to configure this mode in your Docker Server.

In XNAT, to enable Swarm Mode on a container host configuration, simple toggle the selector to "ON". You will then have the opportunity to establish constraints on individual swarm nodes. See documentation on defining Swarm Node Constraints for reference.

Path Translation

In order to execute processing on your XNAT resource files, you need to be able to mount the XNAT Archive within the context of a running container. In most deployments, your XNAT server and your Docker server will be running side by side, or through a HTTPS connection, and this mount process is fairly straightforward. However, if your XNAT server is running inside a Docker container – for example, using the xnat-docker-compose build – then the relationship between the XNAT archive and the Docker server becomes more complicated, since it is already mounted.

The "path translation" configuration setting was created to resolve these differences. See Path Translation for more details on how (and when) to fill out these fields.

SettingDescriptionDefault Value
XNAT Path PrefixThe server path to your XNAT_HOME directory, i.e. "/data/xnat"
Docker Server Path PrefixThe Docker Server path to the XNAT_HOME mount, i.e. "/docker/my-data/XNAT"

Other Settings

You can configure a series of other settings as well to enable or disable certain Docker server behaviors.

SettingDescriptionDefault Value
Re-Pull Images on Init Optional: Use this setting to force the Docker server to re-pull your images whenever the Apache Tomcat server is restarted. Images are only pulled if they are missingOFF
Container UserOptional: By default, Docker will execute container processes running as the "root" user, or allow containers to designate their own user. This field can override those defaults and allow you to specify a valid system user to execute containers.
Automatically cleanup completed containers

Use this setting to automatically remove completed containers after saving outputs and logs. If you do not use this setting, you will need to run some sort of cleanup script on your server to remove old containers so as not to run out of system resources.