Merge pull request #692 from Kitware/authz-token-in-url

Authz token in url + initial deployment docs

docs/.vitepress/config.ts

@@ -53,6 +53,16 @@ export default defineConfig({
           { text: 'Configuration File', link: '/configuration_file' },
         ],
       },
+      {
+        text: 'Deployment',
+        items: [
+          { text: 'Overview', link: '/deployment_overview' },
+          { text: 'Building for Production', link: '/building_for_production' },
+          { text: 'Deploying VolView', link: '/deploying_volview' },
+          { text: 'Authentication', link: '/authentication' },
+          { text: 'Cross Origin Resource Sharing (CORS)', link: '/cors' },
+        ],
+      },
     ],
 
     socialLinks: [

docs/authentication.md

@@ -0,0 +1,24 @@
+# Authentication
+
+VolView itself does not specify any given authentication mechanism to use. How you let VolView access authenticated resources depends on individual deployment needs.
+
+## VolView behind Login Portal
+
+The easiest approach to securing a VolView instance is to host VolView behind an authentication portal. This will secure access to VolView, and allow VolView to automatically use existing user credentials to request protected data.  Often the credentials are stored in a cookie.
+
+## OAuth Tokens via URL
+
+When accessing OAuth-protected resources, VolView by default does not add the `Authorization` header to requests. It is possible to tell VolView to add `Authorization` headers to all requests, via the `token` and `tokenUrl` parameters.
+
+### `token` URL parameter
+
+> [!WARNING]
+> This is a discouraged approach! Only use it if you absolutely must.
+
+You can pass in the `token` URL parameter like so: `https://example.com/VolView/?token=XXXX`. When VolView sees this, it will extract the token from the URL and use it for all subsequent data requests. VolView will also strip the token from the URL to prevent saving the token into the browser history.
+
+### `tokenUrl` URL parameter
+
+As an alternative to passing in the token via the URL, if you have an endpoint that returns the user's token then you can use the `tokenUrl` parameter like so: `https://example.com/VolView/?tokenUrl=https://example.com/userToken`. If VolView successfully receives a token from this endpoint, it will use the token in subsequent data requests.
+
+By default, VolView will make a `GET` request to the token URL. If another type of request is needed, you can configure it via the `tokenUrlMethod` parameter. For example, to make a `POST` request: `https:/example.com/VolView/?tokenUrl=https://example.com/userToken&tokenUrlMethod=POST`.

docs/building_for_production.md

@@ -0,0 +1,14 @@
+# Building for Production
+
+To build VolView, ensure you have the latest `node.js` and `npm` tools installed. `git` is optional for fetching the VolView sources.
+
+To build, run the following commands.
+
+```bash
+git clone https://github.com/Kitware/VolView.git
+cd VolView/
+npm install
+npm run build
+```
+
+If all goes well, the build artifacts will be located in `dist/`. This directory should consist of a bunch of static HTML, CSS, JS, font files, and images. These files can be copied to any static site hosting root for immediate deployment.

docs/cors.md

@@ -0,0 +1,27 @@
+# Cross Origin Resource Sharing (CORS)
+
+CORS is a browser mechanism to let servers protect user data from malicious user-side scripts. In a nutshell, CORS protections prevent browsers from allowing JavaScript to read the responses of cross-origin requests unless certain conditions are met.
+
+For VolView, this manifests most prominently when fetching remote datasets. If the public VolView instance at <https://volview.kitware.app> requests MRI data from <https://example.com/mri-data.nrrd>, the request may fail if `example.com` has not whitelisted `volview.kitware.app`.
+
+The rest of this document describes two ways to resolve this issue.
+
+## Whitelist your VolView domain on the data server
+
+If you have control over the data server, you can whitelist your VolView domain. The simpliest way to do this is to set the `Access-Control-Allow-Origin: MYDOMAIN` header on the server. How this is done depends on the static file server that you are using. An example is provided below.
+
+### Nginx example
+
+Please see [the deployment docs](/deploying_volview) for more info on what an expanded nginx configuration may look like.
+
+```
+server {
+    ...
+
+    add_header Access-Control-Allow-Origin "example.com"
+}
+```
+
+## CORS proxy
+
+If you do not control the data server, you can use a CORS proxy. A CORS proxy is a lightweight proxy server that is configured to attach CORS headers to responses originating from the data server.

docs/deploying_volview.md

@@ -0,0 +1,46 @@
+# Deploying VolView
+
+Deploying VolView is straightforward: just take the locally built files in `dist/` and put them on any static site hosting.
+
+As a local example, running `npx serve dist/` will spin up a static file server (running on <http://localhost:3000>) that reads the locally built files from `dist/`.
+
+> [!NOTE]
+> Using `npx serve` is *not* a recommended way to deploy VolView. It is only used to demonstrate how easy it can be to deploy VolView in simple scenarios.
+
+## Managed Hosting (S3, GCP, etc.)
+
+Please refer to your hosting provider's documentation on how to host a static site. You will need to upload the built files in `dist/` to wherever your provider specifies.
+
+## Self-hosted Server (nginx, apache2, etc.)
+
+Please refer to your desired server's documentation on how to serve static files. You will need to upload the built files in `dist/` to the static file directory on your server. Several examples are provided below.
+
+### Apache example config
+
+In this apache2 example, the `dist/*` files are located under `/var/www/VolView`, and the domain is `example.com`. This does *not* configure TLS.
+
+```
+<VirtualHost *:80>
+   ServerName YOUR_SERVER_NAME
+   DocumentRoot "/var/www/VolView"
+</VirtualHost>
+```
+
+### Nginx example config
+
+In this nginx example, the `dist/*` files are located under `/var/www/VolView`, and the domain is `example.com`. This does *not* configure TLS.
+
+```
+server {
+	listen 80;
+	listen [::]:80;
+
+	server_name example.com;
+	root /var/www/VolView;
+
+	# index.html fallback
+	location / {
+		try_files $uri $uri/ /index.html;
+	}
+}
+```

docs/deployment_overview.md

@@ -0,0 +1,10 @@
+# Deployment Overview
+
+VolView is a client-side application, which means deploying VolView does not have much overhead. That being said, this section of the documentation will cover some common deployment environments that may be of interest.
+
+Generally, most deployments follow a similar pattern:
+
+1. [Building VolView for production](./building_for_production)
+2. [Hosting VolView](./hosting_volview)
+
+The other articles in this section cover other scenarios that may be applicable to your situation.