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.
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.
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:
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:
To start with a specific configuration file:
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:
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:
To completely remove the Service after it has been stopped, run:
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:
You will need to set the values between the < > to be relevant to your system. Once you have created the file, move it into the correct systemd folder:
You can now start the server by running:
Likewise, you can stop the server:
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'.
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:
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:
After a successful build, the modified server is ready to start: