Configuration

Overview of HOOPS Server

The primary function of the HOOPS Server is to create and manage Stream Cache Server processes. A single Stream Cache Server process loads CAD model data and streams that data to a single HOOPS Web Viewer. Note that the server configuration-file setting parameters refer to a Stream Cache Server as a spawn, and devotes a large portion of the configurable values to controlling the behavior around spawns.

Configuration file format

HOOPS Server is built on top of Node.js, which is a Javascript-based application framework. The configuration for the server is therefore contained in a simple Javascript file that is loaded by the server at startup. Because the format is fairly simplistic, only basic knowledge of the Javascript programming language is necessary to modify the configuration file.

The HOOPS Communicator installation package includes a default configuration for HOOPS Server that allows basic server usage without modification. This file is found within the package file structure at <package-dir>/server/node/Config.js. All setting values must be specified, so when modifying Config.js be sure not to delete any setting value entries.

..note:

Please note the configuration file contains your :doc:`license key </overview/license>`.

Server communication

To start a viewing session, the HOOPS Web Viewer will issue an HTTP-based REST call to HOOPS Server via the port specified by spawnServerPort. This port can also be used to request server status or to issue an immediate request for garbage collection.

A spawned Stream Cache Server will communicate with the HOOPS Server by sending periodic HTTP-based REST calls to the port specified by spawnServerPort. These calls allow the HOOPS Web Viewer Server to have a reasonable idea of the current state of the Stream Cache Server. The first call is issued after the Stream Cache Server has started and is ready to send CAD model data. After that, periodic calls will be sent to indicate the liveliness status of the Stream Cache Server. Finally, when the Stream Cache Server has completed sending data and is ready to exit, it will send a final call indicating that state.

If there is a problem with a Stream Cache Server and it continually fails to send its liveliness status, then the HOOPS Server will eventually kill that process. The approach used is to wait for three consecutive missed liveliness periods before declaring that the Stream Cache Server should be killed.

Server ports

One networking port is required for each Stream Cache Server that is spawned. The port is used for websocket communication between the Stream Cache Server and the browser running the HOOPS Web Viewer. The HOOPS Server comes with the built-in ability to use proxy connections as described here.

File system paths

All file and directory values can be specified as either relative or absolute. You can use ~/ as a prefix that will be substituted with the home directory of the user account under which the HOOPS Server is run. When specifying a filesystem path as a relative path, the path will be interpreted as relative to the path specified by the setting for communicatorDir. When specifying the setting for communicatorDir, if a relative path is used, it will be relative to the directory within the HOOPS Communicator package containing the Node.js server, which is <package-dir>/server/node.

Optional HTTP file server

In addition to handling HTTP-based REST calls, the HOOPS Server also supports running a distinct HTTP file-server. This file-server can be used to serve standard web files including HTML, Javascript, images, and CSS files. The file server is optional simply because it’s a Node.js-based server, which may not be appropriate for production environments. The configuration setting fileServerPort determines if this file-server is enabled.

Configurable settings

The values marked as default in the following table are those shipped with our included Config.js file.

LogLevel values in priority order include: Error, Warn, Info, Verbose, Debug

LogSpawnCategory values can be binary OR’d together using “|” and include: Error, Warn, Info, Debug, All.

LogTimeFormat values include: ISO, Local, Delta

Setting	Description	Default value
spawnServerPort	The primary port for communicating with the HOOPS Server via HTTP-based REST messages. These messages can include spawning a new Stream Cache Server, requesting status, or forcing garbage collection.	11182
publicHostname	The public hostname to use when accessing stream-cache servers in broker mode, or for SSL certificate verification. This field can be either a DNS findable hostname or an IP address, although when using in conjunction with an SSL certificate it’s unlikely that the IP address is adequate. If not specified, only the localhost’s IP address will be used. This value is not required when using proxying via the fileServerProxyViewerConnection setting and when SSL is not enabled. When SSL is enabled, this hostname must be verifiable against the supplied certificate chain specified in sslCertificateFile.	null
ipVersion	Determines if the server automatically determines the IP versions which can be a mix of IPv4 and IPv6, or force the server to use only IPv4. Valid values are: IPVersion.ForceIPv4, and IPVersion.Auto	IPVersion.Auto
sslCertificateFile	Determines the file path to a valid SSL certificate chain file, or null if SSL is no server components have SSL enabled.	null
sslPrivateKeyFile	Determines the file path to a valid SSL private key file, or null if SSL is no server components have SSL enabled.	null
sslEnableFileServer	Determines if SSL should be enabled for the file-server.	false
sslEnableSpawnServer	Determines if SSL should be enabled for the spawn-server.	false
sslEnableScServer	Determines if SSL should be enabled for spawned stream-cache servers.	false
spawnMaxSpawnCount	This value controls the maximum number of simultaneous Stream Cache Servers that can be spawned. HTTP requests to start a new streaming session will fail any time this maximum would be exceeded by the request.	32
spawnWebsocketPortsBegin	This value sets the first port to be used for websocket communications. The range of used websocket ports will therefore be: [spawnWebsocketPortsBegin, (spawnWebsocketPortsBegin + spawnMaxSpawnCount - 1)]	11000
spawnLivelinessReportIntervalTime	Determines the frequency, in seconds, at which each spawned Stream Cache Server will report its liveliness status with the HOOPS Server. The HOOPS Server will kill any Stream Cache Server process that hasn’t reported within three consecutive interval periods.	5
spawnInitialUseDuration	Determines the number of seconds of initial inactivity from the HOOPS Web Viewer websocket connection after a new Stream Cache Server has been started. If this time period is exceeded without any communication, the Stream Cache Server will exit and end the viewing session.	60
csrEnabled	Determines if client-side rendering requests are allowed.	true
ssrEnabled	Determines if server-side rendering requests are allowed.	true
ssrUseEgl	Optional parameter to have the SSR use EGL for OpenGL context creation. It is recommended to set this value to true for headless server environments. This parameter is currently only supported on Linux.	false
ssrGpuCount	Optional parameter to allow use of multiple GPUs in SSR mode. This should be a positive integer indicating the number of available GPUs to include. The general approach is the GPU with the least number of clients will be selected for a new spawn. Alternatively, setting this value to null will cause the default GPU to be used in all cases.	null
autoGcIntervalTime	Determines the frequency, in seconds, at which the Node.js garbage collector will be explicitly invoked. To disable explicit collection and rely on the Node.js runtime environment to determine the best times, set this value to null. Note that the Node.js runtime environment will run the garbage collector from time to time, thus the need to enable explicit collection isn’t required. However, our testing has shown that if the HOOPS Server is under heavy load, it can be advantageous to have explicit collection enabled.	30
disableConsoleEnterToShutdown	Determines if the server will respond to an ‘Enter’ key press in the console to shutdown, and display an associated message. If set to ‘true’, it will not display a message and will not respond to the ‘Enter’ key. If false, null, or undefined, the server will display the message and exit upon an ‘Enter’ key press.	null
communicatorDir	Specifies either a relative or absolute path to the root of the communicator package. If the path is relative, then it’s relative to the root of the <package-dir>/server/node directory.	../..
streamCacheExeFile	Specifies either a relative or absolute path to the Stream Cache Server application executable file. If this value is set to null, then the default executable from within the specified communicator package is used. If this is a relative path, it will be relative to the communicatorDir setting.	null
modelDirs	Specifies one or more relative or absolute paths to directories that will be used by Stream Cache Servers to locate CAD model files. Any relative paths will be relative to the communicatorDir setting. The Javascript array format is a bracketed list of path strings separated by commas. See the default value for an example.	[‘./quick_start/content/model_data’, ‘./quick_start/content/authoring_samples_data’]
workspaceDir	Specifies either a relative or absolute path to a directory that is used by a spawned Stream Cache Server for temporary file storage. If this is a relative path, it will be relative to the communicatorDir setting.	~/ts3d_communicator_workspace
logDir	Specifies either a relative or absolute path to a directory where log files will be written too. To disable log file creation, set this value to null. If this is a relative path, it will be relative to the communicatorDir setting.	~/ts3d_communicator_logs
logSpawnFileCategoryMask	This setting allows control of which types of messages are logged by spawned Stream Cache Servers. Use the bitwise-OR operator ‘|’ to combine different values from the LogSpawnCategory enum which is found at the beginning of the configuration file. See the default value for an example.	LogCategoryEnum.Info | LogCategoryEnum.Warn | LogCategoryEnum.Error
logSpawnUseDeltaTime	This setting determines how entries within a Stream Cache Server log file report time. If set to true, then log entries will use a delta style representing ‘time since application start’. If false, the log entries will use an absolute time format.	true
logFileTimeFormat	Specifies the time format used for HOOPS Server file logging. Set this to a value from the LogTimeFormat enumeration, whose values include LogTimeFormat.ISO, LogTimeFormat.Local, or LogTimeFormat.Delta. If this value is undefined or ‘null’, ISO time will be used.	LogTimeFormat.ISO
logConsoleTimeFormat	Determines the time format used for the server console logging. Set this to a value from the LogTimeFormat enumeration, whose values include LogTimeFormat.ISO, LogTimeFormat.Local, or LogTimeFormat.Delta. If this value is undefined or ‘null’, Delta time will be used.	LogTimeFormat.Delta
logStdoutAsLevel	Controls how stdout messages from spawned stream-cached server are logged. If a valid log-level is given, it will be used. If the value is ‘null’, stdout messages will not be logged.	LogLevel.Debug
logStderrAsLevel	Controls how stderr messages from spawned stream-cached server are logged. If a valid log-level is given, it will be used. If the value is ‘null’, stderr messages will not be logged.	`LogLevel.Debug
logConsoleLevelCutoff	Specifies the log-level to use for the HOOPS Server’s console logging. ‘null’ will disable console logging. Logged messages at the indicated LogLevel and the levels to the left of that level will be logged.	LogLevel.Warn
logFileLevelCutoff	Specifies the log-level to use for the HOOPS Server’s file logging. ‘null’ will disable console logging. Logged messages at the indicated LogLevel and the levels to the left of that level will be logged.	LogLevel.Verbose
logRestFilterRegex	Allows a regular expression to filter out unwanted REST HTTP requests from the log. This should be a Javascript compliant regular expression, or ‘null’ to allow all messages logged. For the format, see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions	/POST.*liveliness=ping/
logRestHttpRequestsAsLevel	Specifies the log-level used for REST HTTP requests received by the HOOPS Server. ‘null’ will disable logging those entries entirely.	LogLevel.Verbose
logFileHttpRequestsAsLevel	Specifies the log-level used for file-server HTTP requests received by the HOOPS Server. ‘null’ will disable logging those entries entirely. This value is unused if the file-server is disabled.	LogLevel.Debug
fileServerPort	This setting determines the port used by the optional HTTP file server. To enable the server, set this to an available port value. To disable the server, set this to null or 0.	11180
fileServerStaticDirs	Specifies one or more relative or absolute paths to directories that will be used to search for web content as requested by the HTTP file server. Any relative paths will be relative to the communicatorDir setting. The Javascript array format is a bracketed list of path strings separated by commas. See the default value for an example.	[‘./quick_start’, ‘./quick_start/content’, ‘./web_viewer/src’, ‘./web_viewer/examples’]
fileServerProxyViewerConnections	Determines if the file-server will support proxying of direct viewer websocket connections to the spawn-server. If this is ‘true’ then only the file-server port needs to be made accessible in the server’s firewall.	true
windowsServiceRespawnEnabled	Windows services and associated child processes are executed in what Microsoft calls ‘Terminal Services session 0’ and thus don’t typically have access to the GPU, which means SSR will not work properly without modification. Setting this value to ‘true’ will cause any spawned stream-cache server to ‘respawn’ itself into the same terminal session as the winlogon.exe application which does have access to the GPU. When enabled, this means that a single viewer session will result in two spawned stream-cache server processes for the duration of the viewing session. Since the originating process does nothing more than spawn the second process and forward its stdout, its CPU and memory usage will be minimal. Also note that the process are linked such that they will exit together, so there should be no concern about cleaning up extra processes. To summarize, enable this setting only when 1) running the HOOPS Server as a Windows Service and 2) utilizing SSR functionality. See the Microsoft documentation on interactive services for more information.	false
windowsServiceRespawnLogSuffix	When ‘windowsServiceRespawnEnabled’ is ‘true’, this value will control the suffix of the log file name used for the originating stream-cache server process. Note that the ‘respawned’ process, i.e. the one that does the actual streaming, will use the normal log file name, so this suffix does not apply to it. To disable log files entirely for the originating processes, set this to the empty string or to null. Typically you only need to set this to a suffix string like ‘_respawner’ when diagnosing viewers that aren’t working properly when using as a Windows service, thus we default it to null.	null
licenseFile	Specifies either a relative or absolute path to a file containing a valid HOOPS Communicator license. Setting this value to null indicates that a license file will not be used. Note that if a license file is specified, then the license setting must be null. If this is a relative path, it will be relative to the communicatorDir setting.	null
license	Specifies a valid HOOPS Communicator license key unless the licenseFile setting has been specified, in which case this setting must be null.	<generated-license>