HOOPS Visualize Web HTTPS server with reverse proxy

[Toshi-TS3D]

Introduction

Although the HOOPS Visualize Web SC server can be configured with an HTTPS server as described in this article: HOOPS Visualize Web Server with HTTPS (SSL) , a non-standard port (11182) remains open to the internet, which poses a security risk. This port should be closed by restricting it to a private environment. It is important to minimizes exposure to the public network.

This article explains alternative way to configure SC server with HTTPS server by using an NGINX reverse proxy.

If you have not yet created an HTTPS server, please refer to the following article: How to setup HTTPS server with AWS

SDK / OS / server in use (version)

• HOOPS Visualize Web (2026.1.0)
• AWS Ubuntu Server (24.04 LTS)
• NGINX (1.24.0)

Instruction

HOOPS Visualize Web server installation

Place the folders and files required for the HVW server from the SDK.
Here is an illustration of how to configure the server:

var
 └── www
      ├── html
      │    ├── demo-app
      │    ├── hoops-web-viewer.mjs
      │    ├── engine.esm.wasm
      │    └── sample.html
      ├── server
      ├── 3rd_party
      └── sc_models

1. Transfer the tar.gz file of HOOPS Visualize Web for Linux to the /tmp folder of the virtual server via SCP
2. Extract the tar.gz file

cd /tmp
tar -zxvf HOOPS_Visualize_Web_202x.x.x_Linux_xxx.tar.gz

3. Allocate the necessary folders in a root folder of NGINX

cd HOOPS_Visualize_Web_202x.x.x/
sudo cp -r 3rd_party/ server/ /var/www/
sudo cp -r quick_start/converted_models/standard/sc_models/ /var/www/
cd web_viewer/
sudo cp -r demo-app hoops-web-viewer.mjs engine.esm.wasm /var/www/html/

HOOPS Visualize Web server setup

1. Open Config.js for HOOPS Communicator Stream Cache Server

sudo vi /var/www/server/node/Config.js

2. Set model search directory

    modelDirs: [
        "./sc_models",
    ],

3. Save and quit::wq

Note that it is not necessary to set SSL settings of Config.js if reverse proxy is used. WSS requests are routed through and handled as WS requests by reverse proxy of NGINX before it reaches the SC server.

Edit inbound rules

1. Edit the inbound rules of the virtual server so that HTTP (80), HTTPS (443) and SSH (22) ports are opened to the internet (Delete 11182 port)
   
   

Setting reverse proxy

1. Open the NGINX setting file

sudo vi /etc/nginx/sites-enabled/default

2. Add the following location under existing location / {…}

        location / {
                # First attempt to serve request as file, then
                # as directory, then fall back to displaying a 404.
                try_files $uri $uri/ =404;
        }
        location /wsproxy/ {
            rewrite /wsproxy/([^/]+) / break;
            proxy_pass http://127.0.0.1:$1;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
        }
        location /httpproxy/ {
            #Rewrite request URI (path), capturing some info in the process.
            #Capture 1 = back-end server port. Capture 2 = back-end server path.
            rewrite /httpproxy/([^/]+)/([^/]+) /$2 break;

            #Proxy to the back end server
            proxy_pass http://127.0.0.1:$1;
        }

3. Save and quit: :wq

Add mjs extension to MIME types of NGINX

Adding mjs extension to MIME types since there’s no entry for the mjs extension in NGINX ’s default file type.

1. Open the MIME types setting file

sudo vi /etc/nginx/mime.types

2. Add mjs extension to the js line
   
   
3. Save and quit: :wq

Note that if hoops-web-viewer.mjs is loaded without adding the mjs file type, the following error occurs:
Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of "application/octet-stream".

Reload NGINX

1. Reload NGINX to apply the changed settings

sudo service nginx reload

Minimal sample viewer creation

Configure a proxy connection using a minimal HTML sample.

1. Create a sample HTML and open

sudo touch /var/www/html/sample.html
sudo vi /var/www/html/sample.html

2. Implement the following HTML

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta charset="utf-8"/>
        <title>Simple</title>
         <style>
            #container {
                width:600px;
                height:480px;
                position:relative;
                border: thin solid #000000;
            }
        </style>

        <script type="importmap">
            {
              "imports": {
                "@hoops/web-viewer": "/hoops-web-viewer.mjs"
              }
            }
        </script>
        <script type="module">
            import {WebViewer} from "@hoops/web-viewer";
            WebViewer.defaultEnginePath = "./";
        </script>

        <script type="module">
            import { WebViewer } from "@hoops/web-viewer";
            window.onload = function () {
                const endpoint = "wss://" + window.location.hostname + "/wsproxy/11182";
                const viewer = new WebViewer({
                    containerId: "container",
                    model: "microengine",
                    endpointUri: endpoint,
                    enginePath: "./"
                });
                viewer.start();
            };
        </script>
    </head>
    <body>
        <div id="container"></div>
    </body>
</html>

Note that 11180 port is specified with /wsproxy/ location. This /wsproxy/ location will be rewritten as ws://YOUR_DOMAIN_NAME:11182 by reverse proxy of NGINX.

5. Save and quit: :wq
6. Start the HOOPS Visualize Web server

cd /var/www/server/node
../../3rd_party/node/bin/node --expose-gc ./lib/Startup.js

7. Open https://YOUR_DOMAIN_NAME/sample.html using your web browser to verify you have configured the proxy connections correctly
   
   

Edit sample viewer

If you want to use demo-app/index.html with reverse proxy, it is necessary to edit Router.js

1. Open Router.js

sudo vi /var/www/html/demo-app/web-viewer-demo/src/app/Router.js

2. Edit : to /wsproxy/ of the wsUriRoot function
   
   
3. Save and quit: :wq
4. Start the HOOPS Visualize Web server

sudo sh /var/www/server/node/start_server.sh

5. Open https://YOUR_DOMAIN_NAME/demo-app/index.html?viewer=csr&model=arboleda&wsPort=11182 using your web browser
   
   

HVW server start service

Make a service so that the HVW Server is started at boot time.

1. Create a description file for service and open

sudo touch /etc/systemd/system/onboot.service
sudo vi /etc/systemd/system/onboot.service

2. Write the following service description

[Unit]
Description=auto start commands in /etc/onboot.sh on boot
[Service]
Type=simple
ExecStart=/etc/onboot.sh
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target

3. Save and quit::wq

4. Create a shell file for the service and open

sudo touch /etc/onboot.sh
sudo chmod 0755 /etc/onboot.sh
sudo vi /etc/onboot.sh

5. Write the following shell command to start the server

#!/bin/bash
cd /var/www/server/node
../../3rd_party/node/bin/node --expose-gc ./lib/Startup.js

6. Save and quit: :wq

7. Verify the service is registered

sudo systemctl list-unit-files --type=service | grep onboot.service

img_10795×133 4.84 KB

8. Enable the service to start automatically

sudo systemctl enable onboot.service

9. Restart the virtual server and verify whether HOOPS Visualize Web Server is started automatically

sudo systemctl status onboot.service

img_111003×486 25.1 KB

10. Reload the URL of sample the HTML (http://xxx.xxx.xxx.xxx/sample.html) in your web browser to verify you have configured HVW Server to automatically start as a service correctly

[Toshi-TS3D]

I’ve updated this article for the HOOPS Communicator WebViewer ESM version (2024.4.0).