Advanced Setup

The quick_start directory of the HOOPS Communicator package contains the start_server script that will start a HOOPS Server using common settings and a bundled version of the NodeJS runtime. This guide moves beyond to provide insights on how to run the server in a variety of ways that provide greater control and monitoring capabilities.

Note

The Communicator package includes the NodeJS runtime in the 3rd_party/node directory. Our testing of the HOOPS Server has been performed against this version of the NodeJS runtime, therefore we recommended it when running the server. However, using our supplied version is not a hard requirment and we are not currently aware of any incompatibilites with versions starting with 10.0 or later.

Startup configuration

The HOOPS Server requires a Javascript configuration file to run properly which is typically specified at startup time. The Communicator package ships with two configuration files: The first is found at quick_start/server_settings.js and is intended to be used with the start_server in the quick_start directory only. The second configuration file is found in the the package directory containing the HOOPS Server runtime files and source code at server/node/Config.js. When manually starting the HOOPS Server, the second configuration file will be used unless an alternate file is designated by the startup parameters. When utilizing these advanced startup choices, it is important to be clear on which configuration file is being used.

The command line options for the HOOPS Server include the ability to specify a configuration file using --config-file. The value for this option should be an absolute or relative file path to a valid configuration file. Note that in some startup scenarios, the working directory for the NodeJS runtime may not be settable in which case absolute paths should be used for all relevant configuration items. In particular, these configuration values should likely use absolute paths:

communicatorDir: This specifies the communicator installation directory, and is shipped with a relative path that will only work correctly if the working directory for the NodeJS runtime is within the Communicator installation directory at server/node. Thus to run in all scenarios, it may be required to set this value to the absolute path of the Communicator installation directory.

logDir: This specifies the directory for log files and is shipped with a user home directory relative path starting with ‘~’. This may not make sense when running as a service or a daemon.

workspaceDir: This specifies the directory for temporary model files and is shipped with a user home directory relative path starting with ‘~’. This may not make sense when running as a service or a daemon.

Manually starting the HOOPS Server

The HOOPS Server has been developed with NodeJS and therefore uses the NodeJS runtime to execute. There are two ways to start the server with NodeJS:

Starting with npm

You can use the NodeJS package manager ‘npm’ to start the server. We have included a ‘start’ script in the npm ‘package.json’ file that ships with the server:

cd <communicator-dir>/server/node
npm start

Note

Important: In this case, the configuration file is not specified in the package.json start script, therefore it will attempt to use “Config.js” from the current working directory. You can modify the start script in package.json to include a configuration file of your choice using the --config-file command-line option.

Warning

Starting with npm is not recommended because it will not use the version of NodeJS runtime shipped in the Communicator package.

Starting with the NodeJS runtime

You can also directly launch the NodeJS runtime node.exe to start the server. If no configuration file is specified, it will look for Config.js in the current working directory:

cd <communicator-dir>/server/node
../../3rd_party/node/node.exe --expose-gc  ./lib/Startup.js

To start with a specific configuration file:

cd <communicator-dir>/server/node
../../3rd_party/node/node.exe --expose-gc  ./lib/Startup.js --config-file <file-path-to-user-configuration>

Note

We encourage starting the NodeJS runtime with --expose-gc as this allows the HOOPS Server to manually initiate garbage collection and also supports the REST API call to run the garbage collector. If this argument is ommitted, the HOOPS Server will function properly, but no manual attempts to run the garbage collector will be honored.

Running as a background process

It can be useful to run the HOOPS Server as a background process with the use of a process manager tool. These tools provide easy ways to monitor, aggregate, and restart applications in the event of a crash. There are a variety of options available to accomplish this task depending on your needs and environment. When running as a background process, absolute paths are recommended as mentioned in Startup Configuration.

Running as a Windows service

The following example will use Microsoft’s Service Control Manager sc.exe to create and start the HOOPS Server as a Windows Service. Details on the sc command can be found at sc create. While these examples use sc.exe its capabilities are limited and we recommend looking at more flexible and easier to use service control managers like nssm.

First, since the Windows sc.exe command does not allow the specification of a working directory, edit server/node/Config.js and set absolute paths per Startup Configuration.

Next, to create the service, open a console window with administrator privileges and enter the following command substituting the Communicator installation directory as needed:

sc.exe create ts3d-server displayName="TS3D Server" binPath="<communicator-dir>\3rd_party\node\node.exe --expose-gc <communicator-dir>\server\node\lib\Startup.js --config-file <communicator-dir>\server\node\Config.js"

This creates a Windows Service named ‘ts3d-server’ which will be used for future service control commands. Now that the Service is created, it can be started and stopped as follows:

sc.exe start ts3d-server
sc.exe stop ts3d-server

To completely remove the service after it has been stopped, run:

sc.exe delete ts3d-server

IMPORTANT: If you intend to run the HOOPS Server as a Windows Service and use Server-Side Rendering (SSR), you’ll need to set the windowsServiceRespawnEnabled configuration value to ‘true’.

Running as a Linux daemon

Systemd is available on most Linux distributions and can be used to run HOOPS Communicator in the background. While systemd allows you to set a working directory for the service, you may want to edit the server/node/Config.js and set absolute paths per Startup Configuration. Once the configuration is correct, create a file named communicator.service with the following content:

[Unit]
Description=communicator

[Service]
ExecStart=<communicator-dir>/3rd_party/node/bin/node '--expose-gc' './lib/Startup.js' '--config-file' '<communicator-dir>/server/node/Config.js'
Restart=always
User=<your user name>
# Note Debian/Ubuntu uses 'nogroup', RHEL/Fedora uses 'nobody'
Group=nogroup
Environment=PATH=/usr/bin:/usr/local/bin
WorkingDirectory=<communicator-dir>/server/node

[Install]
WantedBy=multi-user.target

You will need to set the values between the < brackets > to be relevant to your system. Once you have created the file, move it into the correct systemd folder:

sudo cp communicator.service /etc/systemd/system

You can now start the server by running:

sudo systemctl start communicator

Likewise, you can stop the server:

sudo systemctl stop communicator

You can also view the server log, which includes all entries logged to the console stdout by the HOOPS Server. Considering this, you may want to adjust the configuration settings to refine the console logging settings, and you may consider disabling the HOOPS server’s internal file logging by setting logFileLevelCutoff to null.

journalctl -u communicator.service -b

Running cross-platform with PM2

The PM2 Process Manager is a production-grade process manager for NodeJS applications. It provides a consistent cross-platform API for monitoring and restarting processes in the event of a failure.

After installing PM2 globally we can start HOOPS Server with the following command:

pm2 start ./lib/Startup.js --node-args="--expose-gc"

Additionally, PM2 is capable of starting processes when the system boots. Refer to the Startup script section of the PM2 documentation for detailed information.

Modifying the HOOPS Server source code

The HOOPS Server ships with the full Typescript source code, and can be found at server/node/src. While you are free to modify this code, please bare in mind that TechSoft 3D will continue to enhance the HOOPS Server and associated source code with each release, thus we cannot guarantee your changes will continue to work as-is across releases.

To build the HOOPS Server you first need to ensure that all dependent packages have been downloaded. While we ship the runtime dependencies as part of the Communicator package, the development dependencies (like the TypeScript compiler) are not included. However, they are specified in the included package.json file and can easily be installed using npm as follows:

cd <communicator-dir>/server/node
npm install

Now that all of the Node dependencies have been installed, we need to compile our TypeScript code into JavaScript before running the server:

npm run build

After a successful build, the modified server is ready to start:

npm start