From 77edfb8a7345cb01913a196c44697d22ce973996 Mon Sep 17 00:00:00 2001 From: Daniel Matthews Date: Fri, 5 Jan 2024 14:13:05 +0000 Subject: [PATCH] Add xnat architecture notes --- xnat_architecture_notes.md | 71 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 xnat_architecture_notes.md diff --git a/xnat_architecture_notes.md b/xnat_architecture_notes.md new file mode 100644 index 00000000..59f1319e --- /dev/null +++ b/xnat_architecture_notes.md @@ -0,0 +1,71 @@ +# XNAT deployment architecture + +## XNAT + +XNAT is written in Java with the Velocity Template Language (VTL) framework +providing front-end integration with HTML/CSS/Javascript. XNAT's interface is +primarily a web server which allows direct access through a browser or +programmatic access through the [REST +API](https://wiki.xnat.org/display/XAPI/XNAT+REST+API+Directory), although other +interfaces can be provided such as the DICOM SCP node which receives DICOM data. + +## Pipelines + +XNAT provides +[pipeline](https://wiki.xnat.org/documentation/how-to-use-xnat/adding-pipelines-to-your-project) +support for local data processing. The pipelines engine is built as part of the +install. Pipelines can be useful for small automated tasks to be performed when +data are added. In general however it is preferred to use external processing +(eg using [DAX](https://dax.readthedocs.io/en/latest/)), as running local data +processing will use up system resources and could make the server less +responsive. + +## Tomcat + +XNAT runs as a container within Tomcat 9. + +Tomcat receives web requests from nginx internally on port 8080 and forwards +them onto XNAT. + +Tomcat runs under the `tomcat` user (it does not need to run as root as port +8080 is unprivileged). + +## Java + +Tomcat runs under Java. Java options need to be configured in the `JAVA_OPTS` or +`CATALINA_OPTS` variables when the Java process is started. + +## nginx + +Nginx is used as a reverse proxy and handles SSL termination and static file +caching. + +Nginx listens on the following ports: + +- 80: unencrypted http traffic is redirected to https +- 443: encrypted https traffic is decrypted and forwarded internally to port + 8080 for tomcat to process via XNAT +- 104: DICOM traffic is streamed to 8104 where the XNAT SCP service can receive + it + +Nginx has to run as root because it listens on privileged ports 80, 104 and 443. + +## PostgreSQL server + +XNAT uses a PostgreSQL database to store metadata (project structure, custom +data types, user details etc). In this setup, a PostgreSQL server is installed +on a separate machine to the tomcat server. + +- The PostgreSQL database file location is mapped to local storage, or + optionally a shared storage drive (`external_storage_drive`) +- The database server firewall and PostgreSQL configuration only permits + connections from the XNAT server +- PostgreSQL traffic is encrypted with both client and server certificates. The + certificates are generated by the Ansible scripts, which is suitable for a + PostgreSQL server hosted on the same internal network as the XNAT server, + which has no external access, +- If your PostgreSQL server is on a publicly accessible network, you should + obtain SSL certificates signed by a Certificate Authority. + +Source image files themselves are generally kept in the **archive** and not +stored in the PostgreSQL database.