# Advanced Setup

The quick_start directory of the HOOPS Visualize Web 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 HOOPS Visualize Web 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 HOOPS Visualize Web 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 HOOPS Visualize Web 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 HOOPS Visualize Web 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 HOOPS Visualize Web 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 HOOPS Visualize Web 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/bin/node.exe --expose-gc  ./lib/Startup.js

To start with a specific configuration file:

    cd <communicator-dir>/server/node
    ../../3rd_party/node/bin/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 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" -- --config-file ..\..\quick_start\server_config.js

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

## Running as a Linux daemon

Systemd is available on most Linux distributions and can be used to run HOOPS Visualize Web 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 as a Windows service

To simplify the process of running the HOOPS Server as a Windows Service, we provide a TypeScript CreateWindowsService.ts script located at /server/node/. This script automates the following steps:

- Stop and uninstall the previously created service (if any).
- Remove the previously created wrapper (if any).
- Create a wrapper using winsw locally.
- Install the freshly created service.
- Start the freshly created service.
- Using the Windows Service Install Script

You can use our simple Windows service install script with the following command:

    HOOPS_Communicator_2025.4.0\server\node> node .\lib\CreateWindowsService.js --config-file ..\..\quick_start\server_config.js

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’.

## 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 Tech Soft 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 HOOPS Visualize Web 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

Conversation saved
HOOPSY BETA

### Hello! I'm HOOPSY

Your Docs generative AI assistant. Ask me anything about HOOPS Visualize Web or choose a sample question below to start a conversation:

What is HOOPS Visualize Web?
What are the latest release notes for HOOPS Visualize Web?
How do I start evaluating HOOPS Visualize Web?
How do I write my first sample application?
How can I get assistance?

HOOPSY may store conversations according to OpenAI's policy. Responses may not always be accurate.

HOOPSY is thinking...