Installation

Isarsoft Perception is compatible with two distinct platforms, the server and edge variants. The server platform refers to workstations and servers with dedicated NVIDIA GPUs, while the edge platform is compatible with NVIDIA Jetson devices. The initial setup for the two platforms differs slightly.

The deployment is fully containerised and orchestrated via Docker and Docker Compose. The full dependency and compatibility matrix can be found below.

Server Platform (NVIDIA GPU)Edge Platform (NVIDIA JetPack 5)Edge Platform (NVIDIA JetPack 6)

Dependency	Version
Operating System	Ubuntu Server 22.04 LTS
GPU Driver	550.54.14+
Docker	25.0.5+
Compose	2.25.0+

Info

Newer software versions for GPU Driver and Docker may be backwards compatible. Check the respective documentation to learn more.

Dependency	Version
Operating System	L4T 35.2+
JetPack	5.1+
Docker	25.0.5+
Compose	2.25.0+

Supported Jetson Devices

Jetson Orin AGX 64GB
Jetson Orin AGX 32GB
Jetson Orin NX 16GB
Jetson Xavier AGX

Dependency	Version
Operating System	L4T 36.3.0
JetPack	6.0
Docker	25.0.5+
Compose	2.25.0+

Supported Jetson Devices

Jetson Orin AGX 64GB
Jetson Orin AGX 32GB
Jetson Orin NX 16GB

Setup

The following commands set up all dependencies for Isarsoft Perception.

Server Platform (NVIDIA GPU)Edge Platform (NVIDIA JetPack 5)Edge Platform (NVIDIA JetPack 6)

Important Information on Secure Boot

If Secure Boot is enabled on your system you will be prompted with a dialog to enroll your MOK (Machine Owner Key) during the installation of the NVIDIA GPU driver. This is a safety feature of the operating system and hardware to avoid the execution of unauthorized or malicious code during the boot process. You can turn this feature off in your UEFI or follow the next steps to enroll the key.

The following dialogs will show up during the installation instructions below.

Select OK on this dialog.

Enter a secure password. It will be entered again on next boot to verify the new drivers. The next dialog will show up once the system is rebooted (before the OS will boot):

Select "Enroll MOK" and enter the password again when prompted. Continue the boot process.

To verify the drivers are loaded properly, run nvidia-smi in a terminal and verify the GPU(s) show up.

# OS Updates
sudo apt update && sudo apt upgrade

# GPU Driver
sudo apt install nvidia-headless-550 nvidia-utils-550 libnvidia-decode-550 libnvidia-encode-550

# Docker + GPU runtime
curl https://get.docker.com | sh && sudo systemctl --now enable docker
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
    && curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
    && curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
        sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
        sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update
sudo apt install nvidia-docker2

# Reboot
sudo reboot

Tip

We recommend to disable the unattended upgrades feature in Ubuntu to avoid automatically upgrading the dependencies by the following steps:

Execute the command:

sudo dpkg-reconfigure unattended-upgrades

Select No in the pop-up window.

# OS Updates
sudo apt update && sudo apt upgrade

# Remove jetpack packages
sudo apt purge nvidia-jetpack
sudo apt autoremove

# Docker + GPU runtime
curl https://get.docker.com | sh && sudo systemctl --now enable docker
sudo apt install nvidia-container-runtime

# Reboot
sudo reboot

# OS Updates
sudo apt update && sudo apt upgrade

# Remove jetpack packages
sudo apt purge nvidia-jetpack
sudo apt autoremove

# Docker + GPU runtime
curl https://get.docker.com | sh && sudo systemctl --now enable docker
sudo apt install nvidia-container-toolkit

# Reboot
sudo reboot

Docker Configuration

Add the properties default-runtime, log-opts and exec-opts to the docker deamon configuration:

/etc/docker/daemon.json

{
    "runtimes": {
        "nvidia": {
            "path": "nvidia-container-runtime",
            "runtimeArgs": []
        }
    },
    "default-runtime": "nvidia",
    "log-opts": {
        "max-size": "100m",
        "max-file": "3"
    },
    "exec-opts": ["native.cgroupdriver=cgroupfs"]
}

Warning

Disabling systemd cgroup management in Docker via the exec-opts property is the workaround for a known issue with nvidia-container-runtime resulting in loss of GPU access in containers.

Restart the docker deamon to apply new configuration:

sudo systemctl restart docker

Tip

To be able to run docker commands without sudo, add the user to the docker group:

sudo usermod -aG docker $USER

Log out and log back in so that your group membership is re-evaluated. Running groups should contain the docker group.

Tip

Changes can be verified by running docker info.

Deployment

Isarsoft Perception is installed via Deploy Token. This will fetch from a container and package registry automatically, makes deployments more convenient and enables incremental updates. Only the most recent changes between releases are pulled from the registry. It requires internet access or respective firewall exceptions / http proxies.

Note

Many instructions in the documentation of Isarsoft Perception assume the top level project folder to be named perception. Docker Compose will use this name as the project prefix and e.g. containers and volumes will be named accordingly. It is recommended to use the same naming schema as in the following instructions.

Server Platform (NVIDIA GPU)Edge Platform (NVIDIA JetPack 5)Edge Platform (NVIDIA JetPack 6)

# Create a project directory
mkdir perception && cd perception

# Add valid user and token here
export USER=<username>
export TOKEN=<token>
export VERSION=4.1.3
export PLATFORM=server

# Fetch orchestration
curl --user "$USER:$TOKEN" "https://gitlab.com/api/v4/projects/13396821/packages/generic/perception/$VERSION-$PLATFORM/perception-$VERSION-$PLATFORM.tar.gz" | tar -xzvf -
# Fetch images
docker login -u $USER -p $TOKEN registry.gitlab.com
docker compose pull
# Verify images were downloaded
docker images

# Create a project directory
mkdir perception && cd perception

# Add valid user and token here
export USER=<username>
export TOKEN=<token>
export VERSION=4.1.3
export PLATFORM=edge5

# Fetch orchestration
curl --user "$USER:$TOKEN" "https://gitlab.com/api/v4/projects/13396821/packages/generic/perception/$VERSION-$PLATFORM/perception-$VERSION-$PLATFORM.tar.gz" | tar -xzvf -
# Fetch images
docker login -u $USER -p $TOKEN registry.gitlab.com
docker compose pull
# Verify images were downloaded
docker images

# Create a project directory
mkdir perception && cd perception

# Add valid user and token here
export USER=<username>
export TOKEN=<token>
export VERSION=4.1.3
export PLATFORM=edge6

# Fetch orchestration
curl --user "$USER:$TOKEN" "https://gitlab.com/api/v4/projects/13396821/packages/generic/perception/$VERSION-$PLATFORM/perception-$VERSION-$PLATFORM.tar.gz" | tar -xzvf -
# Fetch images
docker login -u $USER -p $TOKEN registry.gitlab.com
docker compose pull
# Verify images were downloaded
docker images

Launch Software

Consider changing settings in the .env file. Launch the software:

docker compose up -d

Warning

Important: The first start will take up to 30 minutes while the device is running hardware specific optimizations. Frontend and API will be available right away, but none of the applications will run.

The frontend dashboard can now be accessed via https://[HOSTNAME/IP]:8443. Default login information is user perception with password perception.