Step 1 of 5: Register a Docker Server

Goal

In addition to validating your connectivity to the XNAT REST API, in this step, you will register a Docker server with the XNAT Container Service.

Setup a Docker server

Before XNAT can interact with Docker, we need to tell XNAT how to access the Docker server. This can be done by posting a bit of JSON to the appropriate REST endpoint.

Tip

XNAT Swagger pages (default url: http://xnat-31.xnat.org/xapi/swagger-ui.html) provide documentation and access to the REST API via the browser. 

Use a web browser on your local computer. 

1. Navigate to the Swagger UI at http://xnat-31.xnat.org/xapi/swagger-ui.html.
2. Expand the docker-rest-api line item and expand the POST /xapi/docker/server line item.

   

3. In the dockerServer box, enter: 

{"host":"unix:///var/run/docker.sock"}

4. Press the "Try it out!" button. An empty response body and response code: 202 is a custom code that tells us that the server information was successfully submitted to XNAT and that the Docker server configuration was saved.

Note that the Swagger response page is full of lots of handy information, including the request URL and cURL format.

Tip

If the response body looks more like a full web page than the JSON you were expecting, you are probably being redirected to the XNAT login page and will need to reload and authenticate before continuing.

The information you just submitted registered the Docker server—accessible via the UNIX socket /var/run/docker.sock—with XNAT. If your docker server is on a different machine, you could point to the URL of that machine in this space. Options are also available to add a path to certificate files if your docker server requires them to authenticate the connection.

Ping Docker via XNAT

Now that XNAT knows about our Docker server, we can verify that the server information we entered is correct by telling XNAT to send a ping to docker. We will also look at the API to get back the host information we just posted.

1. Return to the XNAT Swagger page.
2. Expand the docker-rest-api item, and the GET /xapi/docker/server/ping line item.

3. Click "Try it out!". The response body should be "OK", indicating that XNAT knows about and can connect to your Docker server.

We can also verify the settings by GETing them back from XNAT.

1. Under docker-rest-api, expand the GET /xapi/docker/server line item.
2. Click the "Try it out!" button.
   
   

The response body should contain the server host settings that you previously POSTed.

Next step: View and Manage Docker Images