Configuring front-end web server to reverse proxy for multiple CAST Imaging instances

Introduction
Prerequisites
Step 1 - configure each existing instance of CAST Imaging
- Update nginx.conf file
- Update index.html file
Step 2 - configure the front-end web server as a reverse proxy

Introduction

It is possible to configure a front-end web server (such as Nginx or Apache) to act as a reverse proxy for accessing multiple installed instances of CAST Imaging. For example your organization may have multiple instances of CAST Imaging and would like to access them with a simple URL as follows:

https://imaging.mycompany.com/instance1
https://imaging.mycompany.com/instance2
https://imaging.mycompany.com/instance3
etc.

Prerequisites

Install front-end web server		Install a front-end web server that can handle the proxy pass mechanism. CAST recommends Nginx installed on Linux, however, any other web server that can handle this mechanism can be used, for example Apache. CAST only provides instructions for setting up Nginx as a front-end proxy.
Install instances of CAST Imaging		Ensure that all instances of CAST Imaging that require accessing via a front-end proxy are installed. The configuration of these instances will require updating as described below. It is only possible to configure version ≥ 1.8.0 in this way.

Step 1 - configure each existing instance of CAST Imaging

For each instance of CAST Imaging that you want to access via the front-end reverse proxy, you need to make the following changes:

Update nginx.conf file

Edit the following file:

Microsoft Windows traditional installer:
%APPDATA%\CAST\ImagingSystem\nginx\conf\nginx.conf

Docker Installer extension (located in the folder created when unzipping the extension):
server\nginx\conf\nginx.conf

Microsoft Windows via traditional installer

This file is located in the protected %APPDATA% location, therefore you must open the file with elevated permission (this is usually achieved by right clicking your text editor in the Windows start menu and selecting Run as administrator):

Linux

You may need to use elevated permissions to edit this file (for example use sudo).

Locate the "server {" block:

# Configuration for the server
server {

	# Running port
	listen 80;
	root html;
	index index.html;

	location ~ ^/imaging(.*) {
		index index.html;
		try_files $1 $1/ /index.html;
	}
	# Proxying the connections connections
	location ^~ /imaging/login/api/ {
		proxy_pass         http://127.0.0.1:8084/;
	}
	location ^~ /imaging/sourcecode/api/ {
		proxy_pass         http://127.0.0.1:8084/sourcecode/api/;
	}
	location ^~ /imaging/api/ {
		proxy_pass         http://127.0.0.1:8084/api/;
	}
	location ^~ /imaging/etl/api/ {
		proxy_pass         http://127.0.0.1:8084/etl/api/;
	}
	location ^~ /imaging/saml/ {
		proxy_pass         http://127.0.0.1:8084/saml/;
	}
	location ^~ /saml/ {
		proxy_pass         http://127.0.0.1:8084/saml/;
	}
	location ^~ /imaging/bot/ {
		proxy_pass http://127.0.0.1:8181;
		proxy_http_version 1.1;
		proxy_redirect     off;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection 'upgrade';
		proxy_set_header Host $host;
		proxy_cache_bypass $http_upgrade;

	}

}

Change the configuration to make the instance name unique. In the following example instance1 has been added in each "location" path, but you can add any name you like:

# Configuration for the server
server {

	# Running port
	listen 80;
	root html;
	index index.html;

	location ~ ^/imaging/instance1/(.*) {
		index index.html;
		try_files $1 $1/ /index.html;
	}
	# Proxying the connections connections
	location ^~ /imaging/instance1/login/api/ {
		proxy_pass         http://127.0.0.1:8084/;
	}
	location ^~ /imaging/instance1/sourcecode/api/ {
		proxy_pass         http://127.0.0.1:8084/sourcecode/api/;
	}
	location ^~ /imaging/instance1/api/ {
		proxy_pass         http://127.0.0.1:8084/api/;
	}
	location ^~ /imaging/instance1/etl/api/ {
		proxy_pass         http://127.0.0.1:8084/etl/api/;
	}
	location ^~ /imaging/instance1/saml/ {
		proxy_pass         http://127.0.0.1:8084/saml/;
	}
	location ^~ /instance1/saml/ {
		proxy_pass         http://127.0.0.1:8084/saml/;
	}
	location ^~ /imaging/instance1/bot/ {
		proxy_pass http://127.0.0.1:8181;
		proxy_http_version 1.1;
		proxy_redirect     off;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection 'upgrade';
		proxy_set_header Host $host;
		proxy_cache_bypass $http_upgrade;

	}

}

Save the file.

Update index.html file

Edit the following file:

Microsoft Windows traditional installer:
%PROGRAMFILES%\CAST\ImagingSystem\nginx\html\index.html

Docker Installer extension (located in the folder created when unzipping the extension):
server\nginx\html\index.html

Microsoft Windows

This file is located in the protected %PROGRAMFILES% location, therefore you must open the file with elevated permission (this is usually achieved by right clicking your text editor in the Windows start menu and selecting Run as administrator):

Linux

You may need to use elevated permissions to edit this file (for example use sudo).

Find the line window.defaultBasePath='':

<!DOCTYPE html>
<html lang="en">
<script type="text/javascript">
   window.defaultBasePath=''

Update this line to match the name you have used in the previous step - i.e. in this example instance1:

<!DOCTYPE html>
<html lang="en">
<script type="text/javascript">
   window.defaultBasePath='instance1'

Save the file and ensure that you restart the CAST Imaging System - imaging-fe Windows service or the nginx Linux container.

Step 2 - configure the front-end web server as a reverse proxy

CAST only provides instructions for setting up Nginx as a front-end proxy.

Edit the nginx.conf file, depending on your Linux distribution this file may be located in one of the following places:

/usr/local/nginx/conf
/etc/nginx
/usr/local/etc/nginx

Locate the "server {" block:

# Configuration for the server
server {

    # Running port
    listen              443 ssl;
    server_name         imaging.mycompany.com;
    ssl_certificate     path/to/file.crt;
    ssl_certificate_key path/to/file.key;
    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;
	root html;
	index index.html;

After the # Running port section, add a new section that will contain the reverse proxy instructions, for example:

# Configuration for the server
server {

    # Running port
    listen              443 ssl;
    server_name         imaging.mycompany.com;
    ssl_certificate     path/to/file.crt;
    ssl_certificate_key path/to/file.key;
    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;
	root html;
	index index.html;

	# Reverse proxy

Now add in the configuration for the first instance of CAST Imaging you want to access:

location will configure the access URL that end users will use to access a specific instance of CAST Imaging. In this example it will be https://imaging.mycompany.com/instance1 - but you can use anything you like
proxy_pass configures the location of the CAST Imaging instance to access. Ensure you use naming convention you applied when updating the nginx.conf file - in this example it is instance1

# Configuration for the server
server {

    # Running port
    listen              443 ssl;
    server_name         imaging.mycompany.com;
    ssl_certificate     path/to/file.crt;
    ssl_certificate_key path/to/file.key;
    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;
	root html;
	index index.html;

	# Reverse proxy
	location /instance1 {
	proxy_pass http://192.168.200.10/imaging/instance1;
    proxy_set_header Host $host;
    proxy_redirect off;
    }

Then add in any additional instances:

# Configuration for the server
server {

    # Running port
    listen              443 ssl;
    server_name         imaging.mycompany.com;
    ssl_certificate     path/to/file.crt;
    ssl_certificate_key path/to/file.key;
    ssl_protocols       TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers         HIGH:!aNULL:!MD5;

	# Reverse proxy
	location /instance1 {
	proxy_pass http://192.168.200.10/imaging/instance1;
    proxy_set_header Host $host;
    proxy_redirect off;
    }

	location /instance2 {
	proxy_pass http://192.168.200.11/imaging/instance2;
    proxy_set_header Host $host;
    proxy_redirect off;
    }

	location /instance3 {
	proxy_pass http://192.168.200.12/imaging/instance3;
    proxy_set_header Host $host;
    proxy_redirect off;
    }

Save the nginx.conf file and ensure that you restart the front-end Nginx so that changes are taken into account. Users will now be able to access each CAST Imaging with a stable URL.