From ee31127b08b24a8a16a146d4de1360693483f158 Mon Sep 17 00:00:00 2001
From: dannyrb <danny.ri.brown@gmail.com>
Date: Mon, 13 May 2019 12:58:59 -0400
Subject: [PATCH] Explaining web requests, cors, and diagram of flow

---
 .../recipes/nginx--image-archive.md           | 53 +++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/docs/latest/deployment/recipes/nginx--image-archive.md b/docs/latest/deployment/recipes/nginx--image-archive.md
index 0f0a431b1..e9856b57b 100644
--- a/docs/latest/deployment/recipes/nginx--image-archive.md
+++ b/docs/latest/deployment/recipes/nginx--image-archive.md
@@ -15,3 +15,56 @@ setup, check out our [user account control recpie](./user-account-control.md)
 that builds on the lessons learned here.
 
 ## Overview
+
+Our two biggest hurdles when hosting our image archive and web client are:
+
+- Risks related to exposing our PACS to the netowrk
+- Cross-Origin Resource Sharing (CORS) requests
+
+### Handling Web Requests
+
+We mittigate our first issue by allowing [Nginx][nginx] to handle incoming web
+requests. Nginx is open source software for web serving, reverse proxying,
+caching, and more. It's designed for maximum performance and stability --
+allowing us to more reliably serve content than Orthanc's built-in server can.
+
+More specifically, we accomplish this by using a
+[`reverse proxy`](https://en.wikipedia.org/wiki/Reverse_proxy) to retrieve
+resources from our image archive (Orthanc), and when accessing its web admin.
+
+> A reverse proxy is a type of proxy server that retrieves resources on behalf
+> of a client from one or more servers. These resources are then returned to the
+> client, appearing as if they originated from the proxy server itself.
+
+### CORS Issues
+
+Cross-Origin Resource Sharing (CORS) is a mechanism that uses HTTP headers to
+tell a browser which web applications have permission to access selected
+resources from a server at a different origin (domain, protocol, port). IE. By
+default, a Web App located at `http://my-website.com` can't access resources
+hosted at `http://not-my-website.com`
+
+We can solve this one of two ways:
+
+1. Have our Image Archive located at the same domain as our Web App
+2. Add appropriate `Access-Control-Allow-*` HTTP headers
+
+This solution uses the first approach, but you can see an example of the second
+in the `docker-compose` bundled with this project for local development:
+[HERE](#)
+
+You can read more about CORS in this Medium article: [Understanding
+CORS][understanding-cors]
+
+### Diagram
+
+This setup allows us to create a setup similar to the one pictured below:
+
+{% include "./../_nginx-image-archive-diagram.md" %}
+
+- All web requests are routed through `nginx` on our `OpenResty` image
+- `/pacs` is a reverse proxy for `orthanc`'s `DICOM Web` endpoints
+- `/pacs-admin` is a reverse proxy for `orthanc`'s Web Admin
+- All static resources for OHIF Viewer are served up by `nginx` when a matching
+  route for that resource is requested
+