Add xnat architecture notes

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.