Hub Workstation Cache#

Overview#

Hub Workstation Cache is a service that helps speed up USD workflows on your local workstation. This is a stand-alone service that runs on your local workstation and benefits Kit-based applications or Client Library tools.

Hub Workstation Cache has been performance optimized and supports storage-derived data from newer versions of Kit-based applications.

Download the Hub Workstation Cache from the NGC Catalog.

Warning

Hub Workstation Cache requires Client Library 2.49.2 or greater. If using older versions of Client Library, you may experience errors when attempting to load files.

Installing Hub with Install Scripts#

Hub Workstation Cache is simple to manually install with the scripts included in the archive files which are downloaded from the NGC Catalog. Under File Browser, choose which package to download (either Windows or Linux), and click the three dots under Actions to download it. Extract the data, and install using the ./scripts/install.[bat/sh] file.

Installing Hub with Kit Cache Status Indicator#

Installing Hub Workstation Cache is simple using the Cache Status Indicator extension within your Kit app.

Note

This requires Cache Status Indicator 3.0.0 or greater.

First, search for the Cache Status Indicator extension within your Kit app. Install and load the Cache Status Indicator. Set the extension to autoload so it will always load in your application.

This will load the extension, and add a UI element to the upper right corner of your application. The UI element will notify you when a new version of the Cache Status Indicator is available to download.

Click the indicator to download and install Hub Workstation Cache.

The indicator will change to Downloading… while this is happening.

Once the installation is complete, you will be prompted to restart your applications. (Hub will not connect to running Kit applications until they are restarted.)

After you restart your application, the indicator will be updated with a green SET letting you know it is ready to use.

Clicking the cache indicator will now take you to the Hub Settings documented below.

Uninstalling Hub with Install Scripts#

Within the installed Hub directory, you will find an uninstall.[bat/sh] file.

To uninstall, make sure all your Omniverse applications are shutdown.

Next, run the uninstall.[bat/sh] file directly.

Note

If you provide the -d argument, the hub directory will be removed as well, rather than only the content of the directory.

Hub Configuration and Settings#

Hub Workstation Cache is managed through a settings page, located at http://localhost:14090/index.html.

Cache Path
- This is where all your cache data will be stored for Hub. Make sure this is a local disk on your workstation.
Cleanup Threshold (%)
- How much data should get cleaned up once you have reached or exceeded your allocated storage amount.
Cache Collection Interval(s)
- Duration, in seconds, for when storage utilization is checked for cleanup to make sure it stays within the allocated threshold.
Cache Max Size (Gb)
- This is your initial storage allocation Hub will use when caching data. It is possible for your utilization to be higher than the allocated space until cleanup finishes.
Apply
- Button to make sure modifications to the settings are saved.
Cache size/Cached files
- This is the current size of data and file count stored in your cache location.
Clear
- Clears all the data stored in your cache that is not in use.
Download Support Bundle
- This will zip up all the needed data to supply to NVIDIA to report bugs.

Hub as a Docker Container#

Added in Hub Workstation Cache version 2.0.0, we have added the ability to run Hub as a Docker container. This is a great way to deploy Hub on a single-user workstation, or on a server that is not running Omniverse.

Preamble#

To simplify use, the following requirements should be met:

There should be a directory for the Hub cache on the host system, owned by the user that will be running the Hub container.
The path to this directory should be consistent for all Hub clients. It is strongly recommended for this path to be /var/cache/hub.
The Hub container should have its network configured in host mode.

If a bare metal application will be connecting to Hub in a container, the Hub cache path must be the same on the host system as it is within the Hub container. That is, the directory should be /var/cache/hub on the host system.

However, if all Hub clients are in containers as well, the Hub cache directory may exist within the user’s home directory tree and merely mapped into the Hub and client containers as /var/cache/hub.

Note

Containerized deployments of Hub are assumed to always be running in shared mode.

Sample Docker Commands#

Including a bare metal client:

docker run --rm -v "/var/cache/hub":"/var/cache/hub" -u $(id -u ${USER}):$(id -g ${USER}) --network=host hub-local

Only containerized clients:

docker run --rm -v "$HOME/.cache/ov/hub":"/var/cache/hub" -u $(id -u ${USER}):$(id -g ${USER}) --network=host hub-local

Client Configuration#

Clients using the Hub client (packaged with the omni-client library) will also need to configure their environment so the Hub client can find Hub in this configuration. This should be done as follows:

Install the Hub executable somewhere on the filesystem. For the sake of discussion, this will be /usr/local/bin/hub.
Set the OMNICLIENT_HUB_EXE environment variable to the full path of the installed Hub executable. This tells the Hub client where a Hub executable is. This is needed because the Hub executable is used to communicate configuration information back to the Hub client even when Hub itself will not be running locally.
Set the HUB__CACHE__PATH environment variable to the full path of the Hub cache. This tells the locally-installed Hub executable where to coordinate with the containerized version of Hub that will be doing the caching.
Set the HUB__ARGS__DETECT_ONLY environment variable to true. This tells the locally-installed Hub executable that it should only be looking for a running Hub instance and should not start one if no Hub instance is found.

Sample Client Environment#

Here is a sample client environment. Note that it is not necessary to have every Hub client install the Hub executable in the same location.

HUB__CACHE__PATH=/var/cache/hub
HUB__ARGS__DETECT_ONLY=true
OMNICLIENT_HUB_EXE=/usr/local/bin/hub

Cache Cleaner Tool#

In Hub 1.1.0, a Cache Cleaner tool is included for use with Kit 107 and below applications. This helps manage the derived data those versions of Kit create to help keep derived cache from growing unbounded.

To use the Cache Cleaner tool in Hub with Kit versions lower than 109.0.1, you will need to launch Hub from the command line. Go into the Hub install directory and run the following command:

hub --with-cleaner

Or, if you are using Kit version 109.0.1 or greater, you can launch Kit with an environment variable:

export OMNICLIENT_HUB_WITH_CLEANER=1

Once Hub is running, you can go to the Hub Settings page and click the Cache Cleaner button.

Known Issues and Workarounds#

Updating of Hub Workstation Cache does not remove the old versions that were installed.
- Workaround: Delete the old version of Hub Workstation Cache after updating.
Some Windows users may experience errors when using Kit-based applications 107.3 and below, you may experience errors with Hub not being found in the application, even if it’s been installed.
- Workaround: You will need to create a symlink as follows: mklink /d %APPDATA%\ov %LOCALAPPDATA%\ov
- This issue is fixed in Kit 109.0.1 and greater.

Release Notes#

2.0.0:
- Performance improvements for derived data.
- Added support for Linux AARCH64 architecture.
- Hub can now run as a docker container.
1.1.0:
- Added new Cache Cleaner for more information.
- Performance improvments to support Kit 109 derived data creation.
- Overall stability improvements.
1.0.2:
- Install script now supports installing to a non-default location.
- Updated default library root location on Windows to %LOCALAPPDATA%\ov\pkg.
1.0.1:
- Added an uninstall script.
1.0.0:
- Initial Release.