Development Guide for DLGaaS

Overview

With the 2.0.0 version of the client, web-gRPC is used with DLGaaS, and the WebSockets transport in particular when support for bidirectional streaming (microphone-based voice input) is needed.

When setting up the client for development, a specific setup is required.

This document provides insight and guidance to effectively develop locally.

In short, to support CORS, certificates must be adapted, and a reverse proxy must be set up with access to port 443.

Setup

⚠️ The following guidance applies to a linux/macOS setup with nginx. Adapt accordingly.

CORS

DLGaaS has a limited set of hosts that can exercise against it from the web browser. One of them is the demo client.

As such, leverage the hostname demo.mix.nuance.com (assuming the US geography) when developing.

The following is a recipe in linux/macOS.

1. Certificate

The client uses mkcert to generate self signed certificates. By default the Makefile's certs-setup command sets up localhost -- add the URL specified above.

-               $(XMKCERT) localhost 127.0.0.1 ::1; \
+               $(XMKCERT) demo.mix.nuance.com localhost 127.0.0.1 ::1; \

The generated file will differ, so be sure to account for it in the subsequent step:

-       $(XOPENSSL) pkcs12 -export -out resources/certificate.pfx -inkey resources/localhost+2-key.pem -in resources/localhost+2.pem -password file:resources/.password
+       $(XOPENSSL) pkcs12 -export -out resources/certificate.pfx -inkey resources/demo.mix.nuance.com+3-key.pem -in resources/demo.mix.nuance.com+3.pem -password file:resources/.password

This certificate can be installed in your keychain store.

2. Reverse Proxy (Web Server)

A Web Server will need to be set up, as traffic will need to go through port 443.

The WebServer's reverse proxy must be set up for standard Web resources, as well as WebSockets.

Here is a recipe if using nginx:

# demo.mix.nuance.com.conf
server {  
   listen 443 ssl http2;

   server_name demo.mix.nuance.com;

   ssl_certificate ~/mix-demo-client-azstaticwebapps/resources/demo.mix.nuance.com+3.pem;
   ssl_certificate_key ~/mix-demo-client-azstaticwebapps/resources/demo.mix.nuance.com+3-key.pem;

   client_max_body_size 0;
   charset UTF-8;
   proxy_read_timeout 300;
   proxy_intercept_errors on;

   # Enable Gzip
   gzip on;
   gzip_http_version 1.0;
   gzip_comp_level 2;
   gzip_min_length 1100;
   gzip_buffers 4 8k;
   gzip_proxied any;
   gzip_types
   # text/html is always compressed by HttpGzipModule 
   text/css
   text/javascript
   text/xml
   text/plain
   text/x-component
   application/javascript
   application/json
   image/svg+xml;
   
   location / {  
      proxy_set_header Host $host;
      proxy_redirect http:// https://;
      proxy_http_version 1.1;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header Upgrade $http_upgrade;
      proxy_set_header Connection "upgrade";
      proxy_pass https://localhost:8000;
   } 
}

3. Hosts File

Edit /etc/hosts:

127.0.0.1 localhost demo.mix.nuance.com
::1 localhost demo.mix.nuance.com

4. Docker-Compose File

Update the volume

-      - './resources/localhost+2.pem:/app/localhost+2.pem'
-      - './resources/localhost+2-key.pem:/app/localhost+2-key.pem'
+      - './resources/demo.mix.nuance.com+3.pem:/app/demo.mix.nuance.com+3.pem'
+      - './resources/demo.mix.nuance.com+3-key.pem:/app/demo.mix.nuance.com+3-key.pem'

Update the command

-      npm run develop -- -H 0.0.0.0 --https --cert-file localhost+2.pem --key-file localhost+2-key.pem
+      npm run develop -- -H 0.0.0.0 --https --cert-file demo.mix.nuance.com+3.pem --key-file demo.mix.nuance.com+3-key.pem

Note on Geographies

The client is natively set up for support with .com. If you are using a different stack, replace the TLD (com) with the appropriate TLD required.