Installing an Enterprise Nucleus Server

The documentation below focuses on installing and configuring an Enterprise Nucleus Server using Ubuntu 22.04 LTS.

For more information, please refer to the before you begin page and the in-line documentation contained within the nucleus-stack.env file (included within the installation artifacts.)

Obtaining the Enterprise Nucleus Server Docker Files

After your order for Omniverse Enterprise licenses has been processed, you will receive an order confirmation message from NVIDIA. This confirmation contains information needed to log in and download the required Omniverse Enterprise software from the NVIDIA Licensing Portal.

Downloading the Enterprise Nucleus Server Package

From the NVIDIA Licensing portal, click SOFTWARE DOWNLOADS, and then set product family to Omniverse Enterprise. Locate the latest Omniverse Enterprise Nucleus package and click Download.

../../_images/nucleus_quickstart_softwareDownload.png

Docker Installation

Note

For complete instructions on how to upgrade or downgrade a previously installed version of Docker, please see the Docker website. https://docs.docker.com/engine/install/ubuntu/

Prerequisites

After your Ubuntu 22.04 server is installed, log into the server. Aligning with best practices, ensure the server is fully patched with the latest security updates before proceeding. Before installing Docker, ensure the following helper utilities are installed using the following command:

sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release

Installing Docker

Nucleus 2023.2.0 and above

As of the publishing date of this document, Docker 20 is the recommended version for the successful deployment of an Enterprise Nucleus Server. This version also includes Docker Compose as a built-in module and no longer requires additional software to be installed. This document will be updated as newer versions of Docker are validated and approved.

To install Docker on your server, follow the steps listed below:

  1. Run the following commands which add the proper Docker repositories:

sudo mkdir -p /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

  1. Run the following command, which adds the Docker repository to your apt sources file:

sudo echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

  1. Next, run the following command to update all your local apt repositories:

sudo apt-get update

  1. Run the following command to display a list of available Docker versions within the repository. As noted above, the recommended version of Docker is version 20. The latest version of Docker 20 as of this writing is 20.10.24.

sudo apt-cache madison docker-ce | awk '{ print $3 }'

  1. To install the recommended version of Docker, run the following commands:

VERSION_STRING=5:20.10.24~3-0~ubuntu-jammy
sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-compose-plugin

  1. To confirm Docker and the correct version is installed, run the following command:

docker --version

The expected output is: (This may slightly differ on your system.)

Docker version 20.10.24, build 297e128

Enterprise Nucleus Server Installation

Unpacking software and creating directory structures

  1. Copy the latest nucleus-stack (.tar.gz) package to a local temporary directory (e.g., /tmp) on your server.

  2. Enter the temporary directory:

cd /tmp

  1. Create an install directory (Recommended location: /opt/ove):

sudo mkdir /opt/ove

  1. Extract the nucleus-stack package to your install directory:

sudo tar xzvf nucleus-stack-2023.1.0+mr-26.gitlab.10291385.4b569c9f.tar.gz -C /opt/ove --strip-components=1

Note

The name of the nucleus-stack package downloaded may differ depending on the latest product version available.

The following structure will now be within the /opt/ove directory:

drwxr-xr-x 7 root root  112 Nov  1 18:32 .
drwxr-xr-x 7 root root   98 Nov  1 18:31 ..
-rw-rw-rw- 1 root root 2450 Oct 31 05:06 README.md
-rw-r--r-- 1 root root   52 Oct 31 05:06 VERSION
drwxr-xr-x 6 root root  328 Nov  2 22:16 base_stack
drwxr-xr-x 3 root root   67 Nov  1 18:32 navigator
drwxr-xr-x 2 root root   39 Nov  1 18:32 ssl
drwxr-xr-x 2 root root   68 Nov  1 18:32 sso
drwxr-xr-x 2 root root  101 Nov  1 18:32 templates

For this installation guide, we will focus on configuring nucleus-stack.env within the base_stack directory.

Editing the Nucleus configuration

  1. Enter the base_stack directory:

    cd /opt/ove/base_stack

  2. Using your preferred text editor (nano is used for this example), make the following changes to nucleus-stack.env:

sudo nano nucleus-stack.env

Uncomment Accept EULA:

ACCEPT_EULA=1

Uncomment Security Reviewed:

SECURITY_REVIEWED=1

Set the IP or Hostname:

SERVER_IP_OR_HOST=myhost.mydomain.com

Configure Nucleus passwords:

MASTER_PASSWORD=MY_NEW_PASSWORD
SERVICE_PASSWORD=MY_NEW_PASSWORD

Set the location for your Nucleus data:

DATA_ROOT=/var/lib/omni/nucleus-data

Configure your subnet:

Near the bottom of the nucleus-stack.env file, locate the subnet section. If the subnet defined in CONTAINER_SUBNET conflicts with an existing subnet already present in your network, change it here. IP Addresses for Nucleus Docker containers will be allocated from this subnet.

CONTAINER_SUBNET=192.168.2.0/26

Note

By default, the WEB_PORT is configured to TCP 8080. If using the included NGINX Ingress Router, this is also pre-configured to use TCP 8080. If using an alternate SSL/TLS solution, configure this port to match your requirements.

[Optional] Mount Configurations

The following configuration modifications are optional. These changes enable you to configure your Enterprise Nucleus Server to mount a different S3 bucket on or post deployment.

If you choose to rename the mount path from /NVIDIA, unmount the original path using Nucleus Navigator prior to stopping the services. This can be achieved by having an admin user right-click the /NVIDIA mount, and click Unmount.

../../_images/nucleus_unmount.png

Configure your mount path

Choose to disable or enable reference mount (default= 1). Disabling will start the Enterprise Nucleus Server without any reference path mounted:

REFERENCE_CONTENT_MOUNT_ENABLE=1

Choose the mount path within the Enterprise Nucleus Server (default= /NVIDIA). The path must start with / as this is the root of Nucleus:

REFERENCE_CONTENT_MOUNT_TARGET=/NVIDIA

Define the S3 URL the mount will point to:

REFERENCE_CONTENT_SOURCE="content-production.omniverse.nvidia.com"

Define the bucket name for the reference path. While it is common for many S3 URLs to include the bucket name, not all do. Supply the bucket name if the URL does not contain the bucket name and/or Nucleus is unable to connect to it:

REFERENCE_CONTENT_BUCKET=""

Choose to enable secure connections (HTTPS) to the S3 bucket (default= 1):

REFERENCE_CONTENT_SECURE=1

Configuration using a private bucket is possible, however; additional configuration parameters are required:

# (Must enable and supply all 3 parameters if enabled.)
#
REFERENCE_CONTENT_USE_CREDENTIALS=0
REFERENCE_CONTENT_SOURCE_REGION=""
REFERENCE_CONTENT_BUCKET_ACCESS_KEY_ID=""
REFERENCE_CONTENT_BUCKET_SECRET_ACCESS_KEY=""

It is possible the S3 compliant storage may not support the full expected schema. This option loosens the requirements on the schema, but it is not recommended to change this unless your storage requires less restrictions:

REFERENCE_CONTENT_NON_COMPLIANT_XML_SCHEMA=0

  1. Once all configuration changes are complete, save the file using CTRL+O, then exit the nano editor using CTRL+X.

Required Secrets

It is critical to review the Required Secrets section of the nucleus-stack.env file. The Public-Private key pair act as the root of trust between Nucleus Authentication and Core services.

# For a quick !>INSECURE<! evaluation, a simple shell script generating these
# values is provided along with this stack,
#
# generate-sample-insecure-secrets.sh
# -----------------------------------
#
# Feel free to use it to arrive at a quick sample set;
# but MAKE SURE YOU UNDERSTAND THAT THE SAMPLE SET IS INSECURE.
#
# For any real environment, we recommend reviewing what
# generate-sample-insecure-secrets.sh does, and provisioning the same
# *type* of secrets in whichever manner is appropriate for your environment.

If you would like to quickly set up a Nucleus instance without generating production-grade secrets, a sample script named generate-sample-insecure-secrets.sh is included with the stack.

  1. Enter the base_stack directory.

cd /opt/ove/base_stack

  1. Run the generate-sample-insecure-secrets.sh.

sudo ./generate-sample-insecure-secrets.sh

Warning

generate-sample-insecure-secrets.sh is not intended to be used in production environments, but rather provided as a sample only.

Please consult your security policies and/or Information Security team for guidance on how to handle production secrets.

Using Docker Compose to Run the Stack

For this guide we are using the nucleus-stack.env and nucleus-stack-no-ssl.yml files.

Pull the latest version of the containers. Docker will use the .yml and .env file to do this.

This command will pull the containers from the NVIDIA repository:

sudo docker compose --env-file /opt/ove/base_stack/nucleus-stack.env -f /opt/ove/base_stack/nucleus-stack-no-ssl.yml pull

This command will start the stack in foreground:

sudo docker compose --env-file /opt/ove/base_stack/nucleus-stack.env -f /opt/ove/base_stack/nucleus-stack-no-ssl.yml up

It is recommended to watch the logs initially to spot any errors or issues. If none are observed, stop the stack by pressing Ctrl+C and waiting for it to fully shut down, then restart it in “daemon” mode:

sudo docker compose --env-file /opt/ove/base_stack/nucleus-stack.env -f /opt/ove/base_stack/nucleus-stack-no-ssl.yml up -d

Testing the Installation

Once the stack has been started using the above commands, open a web browser on a workstation and access your Enterprise Nucleus Server using the IP Address or Hostname with the port it’s configured to use. (i.e., http://my-nucleus.example.com:8080 or http://10.54.76.10:8080.) If configured correctly, Nucleus Navigator should appear.

Congratulations! You have successfully installed and configured your Enterprise Nucleus Server!

Next Steps

To configure your Enterprise Nucleus Server with SSL/TLS and/or Single Sign-On (SSO), refer to the linked documentation.

Additional Docker Compose Command Reference

Additional commands for managing your docker compose environment:

  • docker compose --env-file <.env file path> -f <.yml file path> down - stops the running stack

  • docker ps - prints the status of the running containers to the display