=================================================
Enterprise Nucleus Server Quick Start Tips
=================================================

Overview
===================

Enterprise Nucleus Server quick start tips provide instructions for installing and configuring NVIDIA Omniverse Enterprise Nucleus Server on Ubuntu.   
If you require additional instructions, please refer to :ref:`the installation methodology <nuc_planning_install_methodology>` and 
the :code:`nucleus-stack.env` file (included in the installation package) which contains the majority of the 
details required for a successful install.

Compose files will pick up various containers for 
:ref:`Nucleus components <nuc_overview_arch>` from our Docker container registry.

**Please contact your NVIDIA representative to obtain access to the above artifacts.**

Obtaining the Enterprise Nucleus Server Docker Files
====================================================

After your order for NVIDIA Omniverse Nucleus subscription licenses has been processed, you will receive an order confirmation message from NVIDIA. 
This message contains information that you need for getting NVIDIA Omniverse software from the NVIDIA Licensing Portal. 
To log in to the NVIDIA Licensing Portal, an NVIDIA Enterprise Account is required.

Downloading the Enterprise Nucleus Server Package
----------------------------------------------------

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

.. image:: /content/images/nucleus_quickstart_softwareDownload.png
  :align: center

This will download the :code:`nucleus-stack-2022.4.0+tag-2022.4.0-rc.1.gitlab.6522377.48333833.tar.gz` package.

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


Docker
============

Getting Started
--------------------

For installing Docker CE, follow the `official instructions <https://docs.docker.com/engine/install/>`_ for your supported Linux 
distribution. For convenience, the documentation below includes instructions on installing Docker on Ubuntu.

Installing on Ubuntu
----------------------
The following steps can be used to setup NVIDIA Container Toolkit on Ubuntu LTS - 20.04 & 22.04

Install Helper Utilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash
  :linenos:

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


Setting Up Docker
~~~~~~~~~~~~~~~~~~

Docker-CE on Ubuntu can be setup using Docker's official convenience script:

.. code-block::

  curl https://get.docker.com | sh && sudo systemctl --now enable docker


Reference the `official instructions <https://docs.docker.com/engine/install/>`_ for more details 
and `post install actions <https://docs.docker.com/engine/install/linux-postinstall/>`_.

.. note:: Some terminal applications do not support pasting across multiple lines. If you encounter errors, try copying & pasting each command as individual lines.

Test Docker Install
~~~~~~~~~~~~~~~~~~~~~~~

Verify your installation worked using the following command:

.. code-block::

  sudo docker run hello-world


.. image:: /content/images/nucleus_quickstart_helloWorld.png
  :align: center
  :width: 600



Setting Up Docker Compose
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Next, setup Docker's ``docker-compose`` utility: 

.. code-block::

 sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
 sudo chmod +x /usr/local/bin/docker-compose
 docker-compose --version


Reference the `official Docker Compose instructions <https://docs.docker.com/compose/install/>`_ for more details.


Enterprise Nucleus Server Installation
==========================================

*	Copy the nucleus-stack package to a local temporary directory (e.g. /tmp) on your linux server.
*	Enter the temporary directory:

.. code-block::

 cd /tmp


* Create an install directory (e.g. /opt/ove):

.. code-block::

 sudo mkdir /opt/ove


* Extract the nucleus-stack package to your install directory:

.. code-block::

 sudo tar xzvf nucleus-stack-2022.4.0+tag-2022.4.0-rc.1.gitlab.6522377.48333833.tar.gz -C /opt/ove --strip-components=1
 nucleus-stack-2022.4.0+tag-2022.4.0-rc.1.gitlab.6522377.48333833/README.md
 nucleus-stack-2022.4.0+tag-2022.4.0-rc.1.gitlab.6522377.48333833/base_stack/generate-sample-insecure-secrets.sh
 nucleus-stack-2022.4.0+tag-2022.4.0-rc.1.gitlab.6522377.48333833/base_stack/nucleus-stack-no-ssl.yml
 nucleus-stack-2022.4.0+tag-2022.4.0-rc.1.gitlab.6522377.48333833/base_stack/nucleus-stack-ssl.yml
 nucleus-stack-2022.4.0+tag-2022.4.0-rc.1.gitlab.6522377.48333833/base_stack/nucleus-stack.env
 nucleus-stack-2022.4.0+tag-2022.4.0-rc.1.gitlab.6522377.48333833/base_stack/saml/federation.meta.blank.xml
 nucleus-stack-2022.4.0+tag-2022.4.0-rc.1.gitlab.6522377.48333833/ssl/nginx.ingress.router.conf
 nucleus-stack-2022.4.0+tag-2022.4.0-rc.1.gitlab.6522377.48333833/sso/nucleus-sso-gateway.env
 nucleus-stack-2022.4.0+tag-2022.4.0-rc.1.gitlab.6522377.48333833/sso/nucleus-sso-gateway.yml


* Within your install directory you will find three directories: :code:`base_stack`, :code:`ssl`, and :code:`sso`
* For this quick start guide, we will focus on configuring :code:`nucleus-stack.env` within the :code:`base_stack` directory
* Enter the base_stack directory

.. code-block::

  cd /opt/ove/base_stack


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

.. code-block::

  sudo nano nucleus-stack.env


**Uncomment Accept EULA**:

.. code-block::

 ACCEPT_EULA=1

**Uncomment Security Reviewed**:

.. code-block::

 SECURITY_REVIEWED=1


**Set the IP or Hostname**:


.. code-block::

 #SERVER_IP_OR_HOST=USE_CORRECT_HOSTNAME_OR_IP_HERE
 SERVER_IP_OR_HOST=myhost.mydomain.com


**Modify default passwords**:


.. code-block::

 # Master superuser ('omniverse') user's password 
 #
 # This is the initial setting and you can change this password
 # later. 
 #
 # If you change this password using the UI, you will NOT be able to 
 # reset it from here. The only way to recover it would be to 
 # delete your accounts' db (that will delete ALL accounts), 
 # located in ${DATA_ROOT}/local-accounts-db/

 MASTER_PASSWORD=MY_NEW_PASSWORD 

 # Password for built-in service accounts for all services 
 # shipped with this stack. 
 #
 # Authentication DB will be initialized with this password, and 
 # all the services will be configured to use it. Our recommendation is
 # to configure this once, and not touch it. 
 #
 # If you desire to change service accounts' password, 
 # use your Superuser (`omniverse`), change 
 # service accounts' passwords for **all** `*_service` accounts to be 
 # the same new password, update the value below, and restart your stack. 

 SERVICE_PASSWORD=MY_NEW_PASSWORD


**Set the location for your Nucleus data**:

.. code-block::

 ################################################################################
 ## Data
 ################################################################################

 # Set this variable to where you want Nucleus Data to be.
 # Make sure the right kind of disk and adequate amount of disk space is
 # available.
 #
 # It will contain the actual data, as well as logs. File and dir names
 # should be self-explanatory.
 #
 # If running on top of data from an older version of Nucleus, data upgrade
 # may be required. Use `nucleus-upgrade-db.yml` stack
 # along with this .env file to perform the upgrade.
 #
 # To validate internal consistency of data, use `nucleus-verify-db.yml`
 # along with this .env file to run the verifier tool.
 #
 # IMPORTANT: Nucleus Stack must be stopped to perform verification and/or
 # IMPORTANT: upgrade.

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


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

.. code-block::

 CONTAINER_SUBNET=192.168.2.0/26
 

Required Secrets
------------------

Please review the section of the :code:`nucleus-stack.env` file titled **Required Secrets**.
The Public-Private keypair act as the root of trust between the Authentication and Core Nucleus services.

.. code-block::

 # 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 wish 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. 

* Enter the base_stack directory

.. code-block::

  cd /opt/ove/base_stack


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

.. code-block::

  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 teams
  for guidance on how to handle production secrets.


Running Docker Compose to Build the Stack
-------------------------------------------

For this quick start guide we are using :code:`nucleus-stack.env` and :code:`nucleus-stack-no-ssl.yml` files.  
For SSL/TLS and/or SSO integrations, please refer to :doc:`SSL/TLS Configuration <tls>` and 
:doc:`Integrating with SSO <sso>` documentation for further guidance.

Now pull the latest version of the containers. Docker will use the :code:`.yml` file and the :code:`.env` to do this.

Before running these commands, change the path to the location of the files.

**This command example will pull the containers:**

.. code-block::

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


**This command example will start the stack in foreground:**

.. code-block::

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

It's recommended to watch the logs initially to spot any errors or issues. If none are noticed, stop your stack by pressing ``Ctrl+C`` and waiting for it to shut down, then restart it in "daemon" mode:

.. code-block::

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

Congratulations!  You have now successfully installed Enterprise Nucleus Server.

Additional Useful Commands
============================

**To stop the containers:**

.. code-block::

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

Verifying the Enterprise Nucleus Server is running
--------------------------------------------------

**View the status of all the containers:**

.. code-block::

 sudo docker ps