Skip to main content
Skip table of contents

Installing and Enabling the Container Service in XNAT

The Container Service is distributed as a plugin, but this plugin requires core components to be made available to your XNAT system. This guide covers standard practices for local container execution. Production systems may use a more complex setup, including the use of multi-node Docker Swarm to handle the queuing and execution of batches of container launches.

Container Service Plugin

XNAT Container Service is distributed as a plugin jar.  Following Deploying Plugins in XNAT, add the Container Service plugin to a compatible XNAT. Be sure to reference the Container Service Compatibility Matrix to ensure you are using the right version of this plugin for your XNAT.

Docker Engine

If you are using the XNAT Vagrant VM, Docker Engine is already installed and the Container Service plugin will be ready to use out-of-the-box.

XNAT Container Service requires that Docker Engine be installed on a server that is accessible to XNAT via local socket or HTTP/HTTPS and has shared file access to the XNAT filesystem. Docker Engine can be installed on Mac, Windows, and Linux systems. Mac and Windows Docker installations are suitable for development and testing of containers, but Docker for Linux should be used in production environments. Docker provides Docker Engine Installation instructions.

Once Docker Engine is installed, you need to configure the connection between XNAT and your Docker Server. Also see Configuring a Compute Backend for details concerning file path translation for instances where XNAT and Docker Engine servers access the filesystem by different paths.

Single Engine Mode

By default, Container Service is configured to connect directly to a single Docker Engine via unix:///var/run/docker.sock. Consult instructions at Configuring a Compute Backend to connect to Docker Engine on a different host. Container jobs sent directly to a single Docker Engine are executed as quickly as possible, without regard to available system resources.  This can create issues when running containers in bulk or those with resource requirements that exceed server capacity.

Docker Swarm Mode

For any production XNAT running Container Service, we strongly recommend running Docker Engine in Swarm mode.

Container Service can also be configured to connect to Docker in "Swarm mode". Docker Swarm mode can be enabled on a server with a single-node Docker Engine up to a cluster of Docker engines, connected by a Swarm manager. Enabling Swarm mode in any configuration provides advanced resource management and container queueing. Learn more about enabling and managing Docker Swarm mode here:

To enable Swarm Mode in your Docker Engine and in XNAT, do the following:

  • Enable Container Service Swarm Mode in Compute Backend settings.

  • Initialize single-node Docker Swarm from the command line of the Docker Server

> docker swarm init

Kubernetes Mode

See Setting up Container Service on Kubernetes

Container Service Setup


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.