.. _Isaac Sim Container: https://ngc.nvidia.com/catalog/containers/nvidia:isaac-sim: https://ngc.nvidia.com/catalog/containers/nvidia:isaac-sim

.. _NGC API Key: https://docs.nvidia.com/ngc/ngc-overview/index.html#generating-api-key
.. _NVIDIA GPU Driver: https://www.nvidia.com/en-us/drivers/unix
.. _Managing access keys (console): https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey
.. _AWS Secrets Manager: https://aws.amazon.com/secrets-manager
.. _Post-installation steps for Linux: https://docs.docker.com/engine/install/linux-postinstall
.. _PuTTYgen: https://www.puttygen.com

.. _Omniverse Navigator: ../../prod_nucleus/prod_nucleus/usage/navigator_v3.html
.. _Cache: ../../prod_nucleus/prod_utilities/cache/installation/workstation.html
.. _Omniverse Launcher: ../../prod_launcher/prod_launcher/installing_launcher.html
.. _Omniverse Enterprise: ../../prod_enterprise/prod_enterprise/overview.html

.. _isaac_sim_setup_faq:

=======================================
Setup FAQ
=======================================

.. _isaac_sim_setup_native_modes:

Isaac Sim Modes
------------------------------------------------------------------------------------------------

Isaac Sim App Selector
############################################

This is a mini-windowed app that will help run any of the modes below.

:ref:`isaac_sim_app_selector` will run as default when launching Isaac Sim from the :ref:`isaac_sim_setup_native_workstation_launcher`.

.. note::

    * The |isaac-sim_short| App Selector can be run from the terminal using the **isaac-sim.selector.sh** script on Linux or **isaac-sim.selector.bat** on Windows.
    * The |isaac-sim_short| App Selector can also be run from the Isaac Sim App under the **Help** menu.

Isaac Sim Main App
############################################

This is the main windowed Isaac Sim application.

It is the first option and default mode to run from the Isaac Sim App Selector.

.. _isaac_sim_setup_native_kitremote:

Isaac Sim Headless App (via Omniverse Streaming Client)
########################################################

This is a command line version of Isaac Sim. It can be run remotely on a workstation with an RTX GPU
and accessed from the :ref:`isaac_sim_setup_kit_remote` app available for Linux and Windows.

.. _isaac_sim_setup_native_webrtct:

Isaac Sim Headless App (via WebRTC Browser Client)
##################################################

This is a command-line version of Isaac Sim. It can be run remotely on a workstation with an RTX GPU
and accessed on a browser using the :ref:`isaac_sim_setup_livestream_webrtc` client.

.. _isaac_sim_setup_native_websocket:

Isaac Sim Headless App (via WebSocket Browser Client)
#####################################################

This is a command-line version of Isaac Sim. It can be run remotely on a workstation with an RTX GPU
and accessed on a browser using the :ref:`isaac_sim_setup_livestream_websocket` client.


Isaac Sim Python
############################################

This is a mini app to run the Python samples.

* See :ref:`isaac_sim_python_environment`.


Differences Between Workstation And Docker
############################################

There are two methods to install |isaac-sim_short|:

#. :ref:`isaac_sim_app_install_workstation` can be installed from the |launcher| and is recommended for **Workstation** users.
#. :doc:`Install Container </app_isaacsim/install_container>` is recommended for remote headless servers or the Cloud using a **Docker** container.

.. note::

    Here are the main differences between Basic and Advanced installations:

    * The |isaac-sim_short| docker container does not include Nucleus and will access assets directly from the Cloud by default.
    * The workstation version of |isaac-sim_short| works with a local Nucleus server by default.
    * The root folder of the workstation package is at **~/.local/share/ov/pkg/isaac_sim-2022.2.1**, while the root folder in the docker container is ``/isaac-sim``.
    * See :ref:`isaac_sim_misc_paths` for differences in common paths.


Assets and Nucleus
------------------------------------------------------------------------------------------------

.. _isaac_sim_setup_nucleus_add_assets_mount:

Sample Assets
############################################

To access the |isaac-sim_short| assets, a |nuc| server is required. The |nuc_short| server should also have access to the Internet.

.. note::
    - Our |isaac-sim_short| assets is now available in the main **/NVIDIA** folder in every |nuc_short| server. Adding mounts is not needed.
    - Enabling `Cache`_ is recommended when accessing |isaac-sim_short| assets.

#. Login to the Nucleus server via the Web UI as the **admin** user. For **localhost**, go to
   ``http://localhost:8080/login``. See `Omniverse Navigator`_ for more details.

#. The Isaac Sim assets are located at the **/localhost/NVIDIA/Assets/Isaac/2022.2.1/Isaac/** folder.

.. _isaac_sim_setup_set_omni_server:

Setting the Default |nuc_short| Server
############################################

* To set the default Nucleus server when running natively, open the ``user.config.json``
  file for editiing and locate the following line:

    .. code-block:: console

        "persistent": {
            "isaac": {
                "asset_root": {
                    "default": "omniverse://localhost/NVIDIA/Assets/Isaac/2022.2.1",
                }
            },
        },

    Change ``localhost`` to the IP address of the |nuc_short| server.

    .. note::

        * Location of ``user.config.json`` file:

            * Linux: ``~/.local/share/ov/data/Kit/Isaac-Sim/2022.2/user.config.json``
            * Windows: ``C:\Users\{username}\AppData\Local\ov\data\Kit\Isaac-Sim\2022.2\user.config.json``

        * The folder in the **persistent/isaac/asset_root/default** setting should contain both the **Isaac** and the **NVIDIA** folder.

* You could also run |isaac-sim_short| with this flag:

    .. code-block:: console

        --/persistent/isaac/asset_root/default="omniverse://<ip_address>/NVIDIA/Assets/Isaac/2022.2.1"

* To set the default |nuc_short| server when running in Docker, use the flag ``-e "OMNI_SERVER=omniverse://<ip_address>/NVIDIA/Assets/Isaac/2022.2.1"``,
  where ``<ip_address>`` is the IP address of the |nuc_short| server.

    .. code-block:: console

        $ sudo docker run --gpus all -e "ACCEPT_EULA=Y" -e "OMNI_SERVER=omniverse://<ip_address>/NVIDIA/Assets/Isaac/2022.2.1" --rm --network=host nvcr.io/nvidia/isaac-sim:2022.2.1

.. _isaac_sim_setup_set_omni_user:

Setting the Default Username and Password for Connecting to the |nuc_short| Server
#####################################################################################

* Use the following commands to set the default credentials when running natively:

    .. code-block:: console

        $ export OMNI_USER=<username>
        $ export OMNI_PASS=<password>

* To set the default credentials when running in Docker, use the flag ``-e "OMNI_USER=<username>" -e "OMNI_PASS=<username>"``
  (the default is "admin" for each).

    .. code-block:: console

        $ sudo docker run --gpus all -e "ACCEPT_EULA=Y" -e "OMNI_USER=<username>" -e "OMNI_PASS=<password>" --rm --network=host nvcr.io/nvidia/isaac-sim:2022.2.1

.. _isaac_sim_help_uninstall_old_nucleus:

Uninstalling an Old |nuc_short| Server
############################################

To uninstall a |nuc_short| instance from Isaac Sim 2021.1.1 or earlier, follow these steps:

#. Use these commands to uninstall the old |nuc_short| instance:

    .. code-block:: console

        $ systemctl stop omniverse-server
        $ systemctl stop omniverse-asset-converter
        $ systemctl stop omniverse-cache
        $ systemctl stop omniverse-indexing
        $ systemctl stop omniverse-snapshot
        $ systemctl stop omniverse-thumbnail
        $ systemctl stop omniverse-web
        $ sudo rm -rf /var/lib/omniverse
        $ sudo rm -rf /opt/nvidia/omniverse
        $ sudo rm -rf /etc/systemd/systemomniverse-*
        $ sudo rm /lib/systemd/systemomniverse-*
        $ sudo systemctl reset-failed

#. Reboot your machine.

#. Install Nucleus from :ref:`isaac_sim_setup_native_workstation_launcher`.


Docker
------------------------------------------------------------------------------------------------

.. _isaac_sim_setup_nucleus_in_docker:

Manually Installing Nucleus in a Container
################################################################

.. note::

    * The Nucleus and Cache installer is no longer available in the Isaac Sim container.
    * The recommended installation of Nucleus is via the `Omniverse Launcher`_. For enterprise users, see `Omniverse Enterprise`_


.. _isaac_sim_setup_keep_configs:

Save Isaac Sim Configs on Local Disk
################################################################

To keep Isaac Sim configuration and data persistent when running in a container, use the flags below
when running the docker container.

    .. code-block:: console

        -v ~/docker/isaac-sim/cache/kit:/isaac-sim/kit/cache/Kit:rw          #For cache
        -v ~/docker/isaac-sim/cache/ov:/root/.cache/ov:rw                    #For cache
        -v ~/docker/isaac-sim/cache/pip:/root/.cache/pip:rw                  #For cache
        -v ~/docker/isaac-sim/cache/glcache:/root/.cache/nvidia/GLCache:rw   #For cache
        -v ~/docker/isaac-sim/cache/computecache:/root/.nv/ComputeCache:rw   #For cache
        -v ~/docker/isaac-sim/logs:/root/.nvidia-omniverse/logs:rw           #For log files
        -v ~/docker/isaac-sim/data:/root/.local/share/ov/data:rw             #For Isaac Sim data
        -v ~/docker/isaac-sim/documents:/root/Documents:rw                   #For adding new or saving files

    .. code-block:: console

        $ sudo docker run --name isaac-sim --entrypoint bash -it --gpus all -e "ACCEPT_EULA=Y" --rm --network=host \
        -v ~/docker/isaac-sim/kit/cache/Kit:/isaac-sim/kit/cache/Kit:rw \
        -v ~/docker/isaac-sim/cache/ov:/root/.cache/ov:rw \
        -v ~/docker/isaac-sim/cache/pip:/root/.cache/pip:rw \
        -v ~/docker/isaac-sim/cache/glcache:/root/.cache/nvidia/GLCache:rw \
        -v ~/docker/isaac-sim/cache/computecache:/root/.nv/ComputeCache:rw \
        -v ~/docker/isaac-sim/logs:/root/.nvidia-omniverse/logs:rw \
        -v ~/docker/isaac-sim/data:/root/.local/share/ov/data:rw \
        -v ~/docker/isaac-sim/documents:/root/Documents:rw \
        nvcr.io/nvidia/isaac-sim:2022.2.1

    .. note:: These flags will use the use Home folder to save the Isaac Sim cache, logs, config and data.


.. _isaac_sim_setup_net_host:

Problem connecting to Docker container
################################################################

To resolve some problems connecting to a Docker container, try using the **--network=host** flag
when running the docker container.

    .. code-block:: console

        $ sudo docker run --gpus all -e "ACCEPT_EULA=Y" --rm --network=host nvcr.io/nvidia/isaac-sim:2022.2.1

    .. note:: This flag is needed to connect to a Nucleus server.


.. _isaac_sim_setup_read_logs:

Reading the Logs in a Container
############################################

To ensure |isaac-sim| is running in a container, you can read the logs:

#. If the |isaac-sim| container is on a remote machine, SSH into the Docker host using a terminal.
Run this command from where your pem key folder is; replace the ``<public_ip_address>`` with your
instance or remote host IP address:

    .. code-block:: console

        $ ssh -i "yourkey.pem" ubuntu@<public_ip_address>

#. Access the running container as follows:

    .. code-block:: console

        $ docker exec -it <container_id_or_name> bash
        $ cd /root/.nvidia-omniverse/logs/Kit/Isaac-Sim/<version_number>


.. _isaac_sim_setup_restart_container:

Restarting the Container
############################################

The steps below are used to restart a headless container.

#. SSH into the host machine or AWS instance running the |isaac-sim| Container.

    .. code-block:: console

        $ ssh -i "<ssh_key_name>.pem" ubuntu@<public_ip_address>

#. List all running containers and find the container ID running |isaac-sim|.

    .. code-block:: console

        $ sudo docker ps
        CONTAINER ID        IMAGE
        823686a7036d      nvcr.io/nvidia/isaac-sim...2021.2.1

3. Restart the container.

    .. code-block:: console

        $ sudo docker restart [CONTAINER ID]

4. View the Docker logs.

    .. code-block:: console

        $ sudo docker logs [CONTAINER ID]


.. _isaac_sim_restart_sim_inside_docker:

Restart |isaac-sim| inside Docker
############################################

If you want to restart |isaac-sim| while keeping Docker running, you must start the Docker with
Bash as the entrypoint so that you can manually start or stop |isaac-sim|.

#. Start the Docker withBash, and start |isaac-sim| manually.

    .. code-block:: console

        $ sudo docker run -it --entrypoint bash --gpus all -e "ACCEPT_EULA=Y" --rm --network=host nvcr.io/nvidia/isaac-sim:2022.2.1
        $ runheadless.websocket

#. Proceed to :ref:`isaac_sim_setup_livestream_websocket` to live stream |isaac-sim| remotely.

#. When you need to exit, in a separate terminal start an interactive bash session inside the same
   container that's running the headless server and kill the |isaac-sim| related processes.

    .. code-block:: console

        $ docker exec -it <container_id> bash
        $ pkill omniverse-kit

#. Restart |isaac-sim|.

    .. code-block:: console

        $ runheadless.websocket


.. _isaac_sim_save_docker_image:

Save Docker Image
############################################

If you made significant changes inside the docker, for example, installed ROS or other libraries, you may want to save the docker image so that you can restart the docker without having to reinstall everything.

#. Find the container's id and commit it.

    .. code-block:: console

        $ docker ps
        $ docker commit <CONTAINER ID> <new docker name>

#. To reload a specific docker:

    .. code-block:: console

        $ docker run -it --entrypoint bash --gpus all -e "ACCEPT_EULA=Y" --rm --network=host -d <new docker name>


.. _isaac_sim_setup_docker_post_install:

Setting up Docker
############################################

Once you have docker on Linux installed, follow the instructions at `Post-installation steps for Linux`_ to set it up so you would not need to use *sudo* to run a docker container.


.. _isaac_sim_setup_mount_folder:

Mount a Folder to the Container
############################################

To add data from the host machine to a container, mounting a folder is needed.

    .. code-block:: console

        $ sudo docker run --gpus all --rm -e "ACCEPT_EULA=Y" -v ~/docker/isaac-sim/documents:/root/Documents:rw nvcr.io/nvidia/isaac-sim:2022.2.1

    .. note:: Can now copy files to docker/isaac-sim/documents in your Home folder and it will show up in the Isaac Sim container at /root/Documents.


Cloud and Remote
------------------------------------------------------------------------------------------------


.. _isaac_sim_setup_aws_ip_address:

Getting IP Addresses of AWS EC2 Instance
############################################

To get the public and private IP addresses of an AWS EC2 instance, go to the **Instances** section of the **EC2 Dashboard** and select the instance. See the image below for an example of the Private and Public IPs:

    .. figure:: /content/images/isaac_main_aws_ip_address.png
            :align: center

.. _isaac_sim_setup_ssh_aws_instance:

SSH into the AWS EC2 Instance
############################################

If you need to directly access an AWS EC2 instance that was created from the deployment above, run these steps to SSH into the instance:

    .. code-block:: console

        $ ssh -i "<ssh_key_name>.pem" ubuntu@<public_ip_address>

.. _isaac_sim_setup_create_aws_key:

Creating AWS Access Key
#################################

Create an AWS Access Key by following the instructions here:

    `Managing access keys (console)`_

.. _isaac_sim_setup_create_ssh_key:

Creating SSH Key
#################################

***On Linux***

#. Run:

    .. code-block:: console

        $ mkdir ~/.ssh
        $ chmod 700 ~/.ssh
        $ ssh-keygen -t rsa

#. Enter your passphrase twice.
#. Your public key is at **.ssh/id_rsa.pub** in your home folder and private key at **.ssh/id_rsa**.

***On Windows***

#. Download `PuTTYgen`_.
#. Launch PuTTYgen, and click on "Generate a public/private key pair".
#. Click on "Save public key" and name the file "${ssh_key_name}.pub". This is your Public Key file.
#. From the "Conversions" menu, select "Export OpenSSH key" and name the file "${ssh_key_name}.pem". This is your Private Key file.
#. Edit the properties of the "${ssh_key_name}.pem" file.

    * Go to security settings, click “Advanced”
    * Remove inheritance
    * Set current user as owner of the file and full permissions to only that user.
    * This is to prevent permission errors when trying to SSH into the instance

.. _isaac_sim_setup_create_ngc_key_aws:

Setting up NGC API Key on AWS
######################################

If you don't already have an API key:

#.  Generate your `NGC API Key`_.

#. Go to `AWS Secrets Manager`_ section of the AWS console:

#. Click **Store a new secret**.

#. Select **Other type of secrets**.

#. Set the following two sets of Secret key/value pairs

    ===========================  ===================================================================================================
    Key                          Value
    ===========================  ===================================================================================================
    Username                     $oauthtoken
    Password                     <Your_NGC_API Key>
    ===========================  ===================================================================================================

#. Give the secret a name



Livestreaming
------------------------------------------------------------------------------------------------


.. _isaac_sim_change_websocket_ports:

Change WebSocket ports
#####################################################################################

To override the HTTP and server ports for WebSocket:

#. Run Isaac Sim via command line or Launcher with this extra arguments:

    .. code-block:: console

        --/exts/omni.services.transport.server.http/port=8211
        --/app/livestream/websocket/server_port=8899

.. note::

    - Replace the port number **8211** to the desired HTTP port number.
    - Replace the port number **8899** to the desired WebSocket server port number.


Miscellaneous
------------------------------------------------------------------------------------------------


.. _isaac_sim_misc_paths:

Common Path Locations
#####################################################################################

#. Location for |isaac-sim_short| logs

    .. code-block:: console

        # Linux
        ~/.nvidia-omniverse/logs/Kit/Isaac-Sim

        # Windows
        %userprofile%\.nvidia-omniverse\logs\Kit\Isaac-Sim

        # Container
        /root/.nvidia-omniverse/logs/Kit/Isaac-Sim

#. Location for |kit| shader cache

    .. code-block:: console

        # Linux
        ~/.cache/ov/Kit

        # Windows
        %userprofile%\AppData\Local\ov\cache\Kit

        # Container
        /root/.cache/ov/Kit

#. Location for |isaac-sim_short| configs

    .. code-block:: console

        # Linux
        ~/.local/share/ov/data/Kit/Isaac-Sim

        # Windows
        %userprofile%\AppData\Local\ov\data\Kit\Isaac-Sim

        # Container
        /root/.local/share/ov/data/Kit/Isaac-Sim

#. Location for |isaac-sim_short| packages

    .. code-block:: console

        # Linux
        ~/.local/share/ov/pkg/isaac_sim-2022.2.1

        # Windows
        %userprofile%\AppData\Local\ov\pkg\isaac_sim-2022.2.1

        # Container
        /isaac-sim


.. _isaac_sim_misc_uninstall:

How to Uninstall Isaac Sim
#####################################################################################

To uninstall |isaac-sim_short| from the |launcher|:

#. Select the |isaac-sim_short| app in the **Library** tab.

#. Select **Settings**:

    .. figure:: /content/images/isaac_sim_faq_uninstall_1.png
            :align: center

#. Select **Uninstall**:

    .. figure:: /content/images/isaac_sim_faq_uninstall_2.png
            :align: center

.. note::

    * See :ref:`isaac_sim_misc_paths` to remove other files used by |isaac-sim_short|.



.. Python (WIP)
.. ------------------------------------------------------------------------------------------------

.. ROS (WIP)
.. ------------------------------------------------------------------------------------------------