Installation

Just like the existing Material Theme the DCM Dashboard Frontend must be deployed. A way to do so can be done via NGINX / Tomcat / or whatever you prefer to use. Below you will find an example on how to do this for NGINX. 

Opposed to the Blueriq Material theme the Dashboard Frontend is not scoped to a single Runtime it may be setup to connect to multiple Runtime instance. To support this we have added additional environment properties to the building phase of the Dashboard Frontend. Another change between the Blueriq Material theme and Dashboard Frontend is that all of the requests to downstream service are send through the Gateway Service instead of directly to the Services itself. 

Yarn build

The DCM Dashboard Frontend does not need any changes in the environment.ts. With Blueriq Material Theme you were required to change the  `environment.runtime.ts` baseUrl to `/server`, with the DCM Dashboard Frontend this is not necessary as each Dashboard Widget is required to configure what its baseUrl is. This is due to that Widget may run on different Runtime instances, containing different exported projects.  

1. Run `yarn build` (which uses the environment.ts's configuration)
2. When finished: Copy the content of /dist to a application server you prefer (for NGINX that would be: /html)

NGINX

For getting started with NGINX please take a look at their documentation: https://www.nginx.com/resources/wiki/ 
The following configuration is the minimum needed to get the DCM Dashboard Frontend up and running. You could need adjustments to fit your own specific setup.

error_log logs/error.log;

events {
	worker_connections 1024;
}

http {
	upstream revProxyGateway {
		# 1: Replace <host>:<port>, example: my.gateway.local:8080
		server <host>:<port>;
	}
	
	server {
		include ../conf/mime.types;
		listen 1337;

		# Instruct the browser to always verify that its cache is up-to-date
		add_header Cache-Control 'max-age=0, must-revalidate';

		location / {
			root html;
			index index.html index.htm;
			try_files $uri $uri/ /index.html =404;
		}

		# Configure forwarding headers to let downstream systems know that requests are being sent from a service in front of a reverse proxy.
		proxy_set_header Forwarded "for=$host;host=$host:$server_port;proto=$scheme";
    	proxy_set_header Host $host:$server_port;
    	proxy_set_header X-Forwarded-Host $host;
    	proxy_set_header X-Forwarded-Server $host;
    	proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    	proxy_set_header X-Forwarded-Proto $scheme;
    	proxy_set_header X-Forwarded-Port $server_port;

        # 2: Configure a location for each baseUrl that is required by the dashboard applications. When a dashboard definition defines multiple baseUrls all of the baseUrls should have their own location.
		# A typical baseUrl would be /Runtime as this the context root under which the runtime is ran if you installed Blueriq with the installer.
	 	location /<baseUrl>/ {
			# Dashboard requests to a runtime contain a <widget-id> to identify for which Dashboard widget the request is. However this requires some modification to the request.
			# The first group '([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}/)?' contains the optional <wigdet-id>, the second group '(server/)' contains an optional server path segment which is omitted, the third group '(.*)' contains the rest of the request.
            rewrite "^/<baseUrl>/([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}/)?(server/)?(.*)$" /<baseUrl>/$1server/$3 break;

            # 3: This uses the upstream (step 1): So this becomes: http://<host>:<port>/<baseUrl>/<widget-id>/server/$and_the_rest_of_it;
        	proxy_pass http://revProxyGateway/;
    	}

		# 4: This location is optional for production environment. This location rewrites the first request to retrieve the development toolbar frontend. It should point towards a route where the development tools profile is 		active.
		location /server/ {
    		rewrite ^/server/(.*)$ /<development tools runtime context path>/server/$1 break;
    		proxy_pass http://revProxyGateway/;
		} 
        
        location /dashboards/ {
        	proxy_pass http://revProxyGateway/dashboards/;
      	}
  
        location /auth/ {
            rewrite ^/auth/(.*)$ /$1 break;
            proxy_pass http://revProxyGateway/;
        }
  
        location /oauth2/ {
            proxy_pass http://revProxyGateway/oauth2/;
        }
  
        location /login {
            proxy_pass http://revProxyGateway/login;
        }
  
        location /logout {
            proxy_pass http://revProxyGateway/logout;
        }
  
        location /gateway/ {
            proxy_pass http://revProxyGateway/gateway/;
        }
	}
}  

HTTP Session Management

There has been some changes regarding the HTTP Session Management when moving away from the DCM 1.0 and DCM 2.0 Material Theme dashboard. Previously each dashboard application was wrapped in a single HTTP Session. With the new Architecture of the DCM Dashboarding we came to the conclusion that this is not an option when potentially running against multiple Runtime instances. Therefor each Dashboard Widget is now wrapped in its own HTTP Session. In order to achieve this we have extended to Runtime request URLs with a widget-id.

Here is an example of the Runtime request differences between Material Theme and DCM Dashboard Frontend:

• Material Theme: /Runtime/server/api/v2/<rest_of_the_url>
• DCM Dashboard Frontend: /Runtime/<widget-id>/server/api/v2/<rest_of_the_url>

Session Cookies

Altering the Runtime request URL structure is not the only thing we have changed. To let the browser distinguish Dashboard Widgets from each other, the SessionCookie Path and SessionCookie Name attributes has been altered as well.

The Blueriq Gateway Service overrides the default SessionCookie Path and SessionCookie Name attributes send by a Runtime instance to include the <widget-id> in to the Path and Name attributes itself. By leveraging this feature the browser is able distinguish that requests for widget-x with the URL /Runtime/widget-x/<rest_of_the_url> are for intended for the HTTP Session which contain the SessionCookie Path /Runtime/widget-x and SessionCookie Name JSESSIONID_widget-x.