.. _Palette installation:

Software Installation
#####################

This section describes how to get your host development environment set up with the necessary software including the system requirements
before you begin installing the software.

The pre-requisites for installing the Palette software are listed in the :ref:`Palette requirements` section.


.. tabs::

   .. tab:: Linux

      .. rubric:: Online Installation

      Use this method when the host machine has a working internet connection.

      .. dropdown:: Prerequisites
         :animate: fade-in
         :color: secondary
         :open:

         Ensure the following are installed before proceeding:

         **sima-cli**

         .. include:: ../overview/blocks/install_sima_cli.rst

         **Docker**

         The Palette software runs inside Docker. Install Docker Engine or Docker Desktop before continuing.

         * `Docker Engine post-install steps <https://docs.docker.com/engine/install/linux-postinstall/>`_
         * `Docker Desktop installation instructions <https://docs.docker.com/desktop/install/ubuntu/>`_

         To install Docker Engine manually:

         .. code-block:: console

            sima-user@sima-user-machine:~$ sudo apt-get update
            sima-user@sima-user-machine:~$ sudo apt-get install docker-engine

         If you have a previous Palette installation running, stop the existing container before
         installing a new version to ensure a clean upgrade.

         .. important::

            In customer environments with strict firewall policies, coordinate with your IT team
            to allow outbound HTTPS (port 443) access to the following URL:

            .. code-block:: console

               https://783709528641.dkr.ecr.us-west-2.amazonaws.com

      .. dropdown:: Step 1. Select SDK containers to install
         :animate: fade-in
         :color: secondary
         :open:

         Run the following command to start the installation. You will be prompted to select which
         SDK components to install — for example, a Modalix-focused developer may skip the Yocto SDK.

         .. code-block:: console
            :substitutions:

            sima-user@sima-user-machine:~$ sima-cli install sdk

         When prompted, use the arrow keys and ``Space`` to select components, then press ``Enter`` to confirm:

         .. code-block:: console
            :substitutions:

            ✅ sima-cli is up-to-date
            ✅ OS version 22.04 for ubuntu is compatible.
            ✅ Metadata validated successfully.
            ╭─  Select one or more opt-in resources to download ───────────╮
            │                                                              │
            │  Use ↑ / ↓ to navigate                                       │
            │  Press Space to select or deselect items                     │
            │  Press Enter to confirm selection                            │
            │  Tip: You can select multiple items before pressing Enter.   │
            │                                                              │
            ╰──────────────────────────────────────────────────────────────╯
            📦 : Use Space key to toggle selection(s)
            ❯ ◉ MPK CLI Tools (GStreamer pipeline builder and device manager)
            ○ Model SDK (Model compilation and quantization)
            ○ eLxr SDK (Cross-compile for eLxr Linux)
            ○ Yocto SDK (Cross-compile for Yocto Linux)
            ○ 🚫 Skip

         .. warning::

            You may bypass the OS compatibility check using the ``--force`` option.
            **Proceed at your own risk** — this configuration is unsupported and may cause unexpected behavior.

            .. code-block:: console

               sima-user@sima-user-machine:~$ sima-cli install sdk --force

      .. dropdown:: Step 2. Review the dependencies checklist
         :animate: fade-in
         :color: secondary
         :open:

         After downloading, ``sima-cli`` automatically verifies that your system meets the minimum
         requirements. Review all warnings before continuing.

         .. code-block:: console
            :substitutions:

            ╭──────────────────────╮
            │ 🔧 SiMa.ai SDK Setup │
            ╰──────────────────────╯
            🔍 Checking SiMa SDK Bridge Network...
            ✅ SiMa SDK Bridge Network found.
            ✅ Python 3.10.12 (Required ≥ 3.10.0)
            ✅ Docker 28.3.2 (Required ≥ 20.10.10)
            ✅ 14 cores / 31.0 GB RAM (Required ≥ 4 cores / 16 GB)
            ⚠️  Firewall may restrict Docker or SDK communication.

                               System Requirements Report
            ┌───────────┬───────────────────┬──────────────┬───────────┐
            │ Component │ Required          │ Found        │ Result    │
            ├───────────┼───────────────────┼──────────────┼───────────┤
            │ Python    │ ≥ 3.10.0          │ 3.10.12      │ ✅ PASS   │
            ├───────────┼───────────────────┼──────────────┼───────────┤
            │ Docker    │ ≥ 20.10.10        │ 28.3.2       │ ✅ PASS   │
            ├───────────┼───────────────────┼──────────────┼───────────┤
            │ CPU/RAM   │ ≥4 cores / ≥16 GB │ 14 / 31.0 GB │ ✅ PASS   │
            ├───────────┼───────────────────┼──────────────┼───────────┤
            │ Firewall  │ Disabled          │ Unverified   │ ⚠️ WARNING │
            └───────────┴───────────────────┴──────────────┴───────────┘

            ❌ Some system checks failed.
            Do you want to continue anyway? [y/N]:

      .. dropdown:: Step 3. Complete the SDK setup
         :animate: fade-in
         :color: secondary
         :open:

         Confirm to proceed, then select the SDK images to start. Enter a workspace directory
         when prompted — this is the directory mounted inside the container.

         .. code-block:: console
            :substitutions:

            Do you want to continue anyway? [y/N]: y
            ⚠️  Proceeding despite warnings.
            ╭───────────────── 📘 SiMa.ai SDK Image Selection ──────────────────╮
            │ • Use ↑/↓ and Space to select one or more images.                │
            │ • Press Enter to confirm.                                        │
            │ • Containers will be started automatically.                      │
            │ • Press CTRL+C to cancel anytime.                                │
            ╰──────────────────────────────────────────────────────────────────╯
            Single SDK version detected: latest_master
            ? Select SDK images to start: 2 selected

            🔍 Checking for running SDK containers...
            ℹ️  No running SDK containers found.
            Enter workspace directory [/home/sima/workspace]:
            ✅ Workspace set to: /home/sima/workspace

            ====================[ 🔄 STARTING: mpk_cli_toolset-latest_master ]====================

            ✅ Created configuration file at: /home/sima/workspace/config.json
            🚀 Starting container 'mpk_cli_toolset-latest_master'
            ✅ Container started on port 49152.
            ✅ Container configured successfully.
            ✅ All selected containers started successfully!

            ╭─ Post-Installation Summary ────────────────────────────────────────────╮
            │ sima-cli sdk setup — Initialize the SDK environment.                   │
            │ sima-cli sdk start — Start SDK containers.                             │
            │ sima-cli sdk stop — Stop running SDK containers.                       │
            │ sima-cli sdk remove — Remove installed SDK containers.                 │
            │ sima-cli sdk mpk — Access the MPK CLI container.                       │
            │ sima-cli sdk model — Access the Model SDK container.                   │
            │ sima-cli sdk yocto — Work inside the Yocto SDK container.              │
            │ sima-cli sdk elxr — Work inside the eLxr SDK container.                │
            │                                                                        │
            │ Tip: Use ``docker ps`` to verify running containers.                   │
            │ Setup complete! Run ``sima-cli sdk start`` to begin.                   │
            ╰────────────────────────────────────────────────────────────────────────╯
            ✅ Installation completed successfully.

         .. note::

            The SDK setup can be re-run at any time using ``sima-cli sdk setup`` to modify your
            SDK configuration after the initial installation.

      .. dropdown:: Step 4. Access the SDKs
         :animate: fade-in
         :color: secondary
         :open:

         Use ``sima-cli`` to enter any SDK container:

         .. code-block:: console
            :substitutions:

            sima-user@sima-user-machine:~$ sima-cli sdk mpk
            sima-user@sima-user-machine:~$ sima-cli sdk model

         You can also run commands directly inside a container by appending a subcommand:

         .. code-block:: console
            :substitutions:

            sima@SiMa-AE-002:~/workspace$ sima-cli sdk mpk mpk

      .. rubric:: Offline Installation

      Use this method when the target host has limited or no internet access. The process requires
      two machines: one with internet access to download the artifacts, and the target host to install them.

      .. dropdown:: Step 1. Download SDK artifacts (internet-connected machine)
         :animate: fade-in
         :color: secondary
         :open:

         On a machine **with internet access**, run the following commands to download all required
         installation files:

         .. code-block:: console
            :substitutions:

            sima-user@sima-user-machine:~/$ mkdir sdk-install && cd sdk-install
            sima-user@sima-user-machine:~/$ sima-cli install sdk -t offline --force

      .. dropdown:: Step 2. Transfer files to the target host
         :animate: fade-in
         :color: secondary
         :open:

         Once the download is complete, transfer the entire ``sdk-install`` directory to the target
         host using your preferred method (e.g. USB drive, SCP, shared network drive).

      .. dropdown:: Step 3. Install on the target host
         :animate: fade-in
         :color: secondary
         :open:

         On the target host, run the following commands to complete the installation:

         .. code-block:: console
            :substitutions:

            sima-user@sima-user-machine:~/$ cd sdk-install
            sima-user@sima-user-machine:~/$ python3 install.py && sima-cli sdk setup

         .. note::

            The target host must have ``sima-cli`` installed before running these commands.

         After the setup completes, the SDK environment is ready for use.

      .. rubric:: Uninstalling the Palette Software

      To remove the installed SDK containers, run:

      .. code-block:: console
         :substitutions:

         sima-user@sima-user-machine:~$ sima-cli sdk remove

   .. tab:: Windows

      **Installing on Windows using Hyper-V**

      The Palette software supports Windows OS in Hyper-V mode, the setup and installation steps are described below.

      .. note::

        The Docker application (Docker Desktop or Docker Engine) must be installed before installing the Palette software.

      Follow the link below for downloading and installing the Docker Desktop application.
      https://docs.docker.com/desktop/install/windows-install/

      Use the build version 4.26.1 or lower. See, https://docs.docker.com/desktop/release-notes/ for details.

      In the **Configuration** window, do not click in the first checkbox, thereby the Hyper-V option will be enabled in the Docker Desktop application.

      .. image:: media/Palette_windows_Hyper_V.png
              :scale: 50%
              :align: center

      **Steps**

      #. Reboot your PC and make sure that the Hyper-V option is enabled automatically as shown in the below image. If not, please select Hyper-V manually.

         .. image:: media/windows_hyperv_setting.png
              :scale: 50%
              :align: center

      #. Launch the Docker Desktop application and open settings. Under resources, increase the memory to 6 GB as shown in the below image and choose ``Apply & Restart`` option.

         .. image:: media/docker_resources.png
              :scale: 50%
              :align: center

      #. Unzip the Palette software file.

      #. Launch Windows powershell as an administrator and navigate to the sima-cli folder of the downloaded Palette software uncompressed file.

      #. Install the Palette software.

         .. code-block:: powershell
            :substitutions:

             PS C:\Users\SiMaUser\Downloads\|var_palette_reqs_version|\sima-cli> sima-cli install sdk

      #. Enter the workspace directory of your choice (this is the directory which gets mounted in the container) and wait untill installation completes. Typical flow is mentioned below.

      #. If prompted for file sharing permission from Docker, accept it.

         .. image:: media/docker_permissions.png
                :scale: 50%
                :align: center

      #. Launch the Palette software.

         .. code-block:: powershell
            :substitutions:

             PS C:\Users\SiMaUser\Downloads\|var_palette_reqs_version|\sima-cli> sima-cli sdk mpk