Version: 10

Configure NVIDIA Jetson

Required Jetson Platform

JetPack 7.2 / Jetson Linux L4T r39.2 on Ubuntu 24.04 (Noble) is required for the ROS 2 Jazzy Jetson image. The image uses CUDA 13.2.1, cuDNN 9.20.0, TensorRT 10.16.2, and the runtime MOVEIT_TARGET=-jetson-cuda13.2-cudnn9 suffix. Generic arm64 images are not Jetson images.

Configuring JetPack for GPU Acceleration

info

The following instructions assume that you already have Docker installed and that your system has internet access.

GPU acceleration for MoveIt Pro requires installing the nvidia-container-toolkit. On NVIDIA Jetson platforms with JetPack, this package is provided in an APT repository which is already configured on the system. To install and configure the package, open a terminal and run:

sudo apt update && sudo apt install nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Confirm the host is running the required JetPack 7.2 / L4T r39.2 stack before continuing. tegrastats monitors host telemetry; it does not verify the Docker NVIDIA runtime.

Start host telemetry before starting the workload:

sudo tegrastats

While tegrastats is running, start the workload that will use the GPU and confirm that GPU and memory activity are reported. Verify the configured Docker NVIDIA runtime with the published MoveIt Pro Jetson workload during Jetson hardware qualification; a CUDA/TensorRT application smoke test requires the published image and supported hardware.

MoveIt Pro GPU Inference Availability

MoveIt Pro detects the supported JetPack 7.2 / L4T r39.2 Jetson host and sets MOVEIT_TARGET=-jetson-cuda13.2-cudnn9. This runtime target is separate from generic arm64 and from the amd64 MOVEIT_TARGET=-cuda13.2-cudnn9 image.

NVIDIA AGX Orin Onboard Storage Limitations

The NVIDIA AGX Orin is provided with 64GB of eMMC 5.1 onboard storage. This eMMC storage is capable of a theoretical maximum linear transfer speed of 100MB/s. The NVIDIA AGX Orin Developer Kit is also provided with a PCIe x4 Gen4 M.2 slot for expansion which is capable of transfer speeds many times that of the onboard eMMC. For this reason, PickNik recommends installing a compatible M.2 NVMe storage device and configuring Docker to use this device for image storage using the instructions below.

Choosing a Drive

For the NVIDIA AGX Orin Developer Kit, NVIDIA recommends an NVMe storage device which has the following specifications:

M.2 key M
2280 form factor
PCIe Gen4 (Gen3 supported with Gen3 speeds / Gen5 supported at Gen4 speeds)
At least 1TB capacity

Installing the NVMe Drive

warning

In addition to the instructions below, follow all best-practices for safe electronics handling such as anti-static procedures.

Power off the NVIDIA AGX Orin Developer Kit and disconnect power and data cables.
Flip the Developer Kit upside-down.
Identify connector J1 using the Carrier Board Component Identification Diagram.
Remove the mounting screw in the stand-off directly across from connector J1.
Fully insert the M.2 NVMe drive edge connector into the carrier board connector J1 at a 45 degree angle.
Gently push the drive down toward the carrier board until the semi-circular cutout in the end of the drive aligns with the stand-off from which you removed the screw in step 4.
While holding the drive down, re-install the screw into the stand-off to affix the drive to the carrier board. Take care not to over-tighten this screw.
Flip the Developer Kit right-side-up and reconnect power and data cables.

Formatting and Mounting

Power on the NVIDIA AGX Orin Developer Kit.
Log in using your username and password.
Open a terminal window (keyboard shortcut: CTRL+ALT+T).
In the terminal window type lsblk and hit enter. If your new drive was detected correctly, there should be an entry at the bottom of the output similar to nvme0n1 259:0 0 931.5G 0 disk. If your device is named differently, write down the name and use it in the following steps.
Type sudo fdisk /dev/nvme0n1, hit enter, enter your password, then hit enter again.
1. Type g and hit enter to create a new GPT partition table.
2. Type n and hit enter to create a new partition.
3. Hit enter to accept the default partition number.
4. Hit enter to accept the default first sector.
5. Hit enter to accept the default last sector and use the remaining drive capacity.
6. Type w and hit enter to write the changes and exit fdisk.
Type lsblk and hit enter. Confirm that the drive nvme0n1 now has a new partition below it named similarly to nvme0n1p1.
Type sudo mkfs.ext4 /dev/nvme0n1p1 which will format the new partition as ext4 (common Linux extended filesystem format).
Type sudo mkdir /mnt/nvme which will create a new folder that we will use as the mount point for the new partition.
Type lsblk -f which will print the partition information but also include the UUID field which we will use in the following steps. Highlight the UUID of the new partition with your mouse and copy it to your clipboard (right-click -> Copy).
Edit the /etc/fstab file with a terminal editor like vim or nano. Add a new line to the end of this file with the format UUID=<partition_uuid> /mnt/nvme ext4 defaults 0 2, replacing <partition_uuid> with the UUID that you copied in step 9 (right-click -> Paste).
Save and exit the editor.
Type sudo reboot and hit enter to reboot the NVIDIA AGX Orin.
Once the Orin has rebooted and you have logged in again, you can verify that the new partition is mounted using the command ls /mnt/nvme in a terminal to see the contents of the new partition.

Migrating Docker Storage Location

note

The following instructions assume that you already have Docker installed and that you carefully followed the instructions above to install and configure an NVMe drive.

Confirm that /mnt/nvme is the intended mounted filesystem and not a symlink:

test -d /mnt/nvme && test ! -L /mnt/nvme &&
  mountpoint --quiet /mnt/nvme ||
  { echo "NVMe target validation failed." >&2; exit 1; }

Detect whether this Docker installation uses the containerd image store, then back up the current service configuration. Do not infer the backend from the Docker version: upgraded Docker 29 installations can still use the legacy image store.

set -euo pipefail
DRIVER_STATUS="$(docker info --format '{{json .DriverStatus}}')"
STORAGE_DRIVER="$(docker info --format '{{.Driver}}')"
case "$DRIVER_STATUS" in
  *io.containerd.snapshotter.v1*) MIGRATE_CONTAINERD=true ;;
  *)
    test -n "$STORAGE_DRIVER" ||
      { echo "Could not determine Docker's active image store." >&2; exit 1; }
    MIGRATE_CONTAINERD=false
    ;;
esac

sudo install -d -m 0755 /var/backups
BACKUP_DIR="$(sudo mktemp -d -p /var/backups moveit-pro-docker-storage.XXXXXXXX)"
sudo chmod 0700 "$BACKUP_DIR"

if sudo test -e /etc/docker/daemon.json; then
  sudo cp -a /etc/docker/daemon.json "$BACKUP_DIR/daemon.json"
else
  sudo touch "$BACKUP_DIR/daemon.json.absent"
fi

if sudo test -e /etc/containerd/config.toml; then
  sudo cp -a /etc/containerd/config.toml "$BACKUP_DIR/containerd-config.toml"
else
  sudo touch "$BACKUP_DIR/containerd-config.toml.absent"
fi

if $MIGRATE_CONTAINERD; then
  sudo touch "$BACKUP_DIR/containerd-migration.enabled"
fi
printf 'Configuration backup: %s\n' "$BACKUP_DIR"

Record the printed backup path; the rollback commands require it. The marker records the backend reported by docker info; do not create or remove it based only on the Docker version.

Record the current images and named volumes, then stop Docker and containerd:

set -euo pipefail
docker image ls
docker volume ls
sudo systemctl stop docker.socket docker.service containerd
for unit in docker.socket docker.service containerd; do
  if sudo systemctl is-active --quiet "$unit"; then
    echo "$unit is still active; refusing to touch live data." >&2
    exit 1
  fi
done

Copy the active data without deleting its source. Copy containerd only when step 2 created the migration marker:

set -euo pipefail
sudo test ! -e /mnt/nvme/docker ||
  { echo "/mnt/nvme/docker already exists; refusing to merge data." >&2; exit 1; }
sudo install -d -m 0711 /mnt/nvme/docker
sudo rsync -aHAXx --numeric-ids /var/lib/docker/ /mnt/nvme/docker/ ||
  { echo "Docker data copy failed." >&2; exit 1; }

if sudo test -e "$BACKUP_DIR/containerd-migration.enabled"; then
  sudo test ! -e /mnt/nvme/containerd ||
    { echo "/mnt/nvme/containerd already exists; refusing to merge data." >&2; exit 1; }
  sudo install -d -m 0711 /mnt/nvme/containerd
  if sudo test -d /var/lib/containerd; then
    sudo rsync -aHAXx --numeric-ids /var/lib/containerd/ /mnt/nvme/containerd/ ||
      { echo "containerd data copy failed." >&2; exit 1; }
    sudo touch "$BACKUP_DIR/containerd-data-source.present"
  fi
fi

Set "data-root": "/mnt/nvme/docker" in /etc/docker/daemon.json, preserving any existing settings. If $BACKUP_DIR/containerd-migration.enabled exists, ensure a version-appropriate containerd configuration exists, then set root = "/mnt/nvme/containerd" in it. Do not change the containerd root otherwise.
```
set -euo pipefail
if sudo test -e "$BACKUP_DIR/containerd-migration.enabled" &&
   ! sudo test -e /etc/containerd/config.toml; then
  sudo install -d -m 0755 /etc/containerd
  containerd config default | sudo tee /etc/containerd/config.toml >/dev/null
fi
```

Start the services and verify the migration before changing the old directories:

set -euo pipefail
sudo systemctl start containerd docker
test "$(docker info --format '{{ .DockerRootDir }}')" = /mnt/nvme/docker ||
  { echo "Docker is not using the NVMe data root." >&2; exit 1; }
if sudo test -e "$BACKUP_DIR/containerd-migration.enabled"; then
  sudo containerd config dump |
    grep -Eq '^[[:space:]]*root[[:space:]]*=[[:space:]]*"/mnt/nvme/containerd"' ||
    { echo "containerd is not using the NVMe root." >&2; exit 1; }
fi
docker image ls
docker volume ls
sudo systemctl --no-pager --full status containerd docker
mountpoint --quiet /mnt/nvme
test "$(findmnt -n -o TARGET -T /mnt/nvme/docker)" = /mnt/nvme
if sudo test -e "$BACKUP_DIR/containerd-migration.enabled"; then
  test "$(findmnt -n -o TARGET -T /mnt/nvme/containerd)" = /mnt/nvme
fi

Confirm that the expected images, named volumes, and volume contents are present. If validation fails, the original data still exists under /var/lib; restore the exact pre-migration configuration before restarting the services:

set -euo pipefail
# If this is a new shell, set BACKUP_DIR to the path printed in step 2.
sudo test -d "$BACKUP_DIR" || { echo "Backup directory not found." >&2; exit 1; }
sudo systemctl stop docker.socket docker.service containerd
for unit in docker.socket docker.service containerd; do
  ! sudo systemctl is-active --quiet "$unit" ||
    { echo "$unit is still active; aborting rollback." >&2; exit 1; }
done
if sudo test -e "$BACKUP_DIR/daemon.json.absent"; then
  sudo rm -f /etc/docker/daemon.json
else
  sudo cp -a "$BACKUP_DIR/daemon.json" /etc/docker/daemon.json
fi
if sudo test -e "$BACKUP_DIR/containerd-config.toml.absent"; then
  sudo rm -f /etc/containerd/config.toml
else
  sudo cp -a "$BACKUP_DIR/containerd-config.toml" /etc/containerd/config.toml
fi
sudo systemctl start containerd docker

After the migrated system has been validated, stop the services and quarantine only the data roots that were migrated. Refuse to overwrite an earlier quarantine:

set -euo pipefail
sudo test -d "$BACKUP_DIR" || { echo "Backup directory not found." >&2; exit 1; }
mountpoint --quiet /mnt/nvme ||
  { echo "NVMe target is not mounted; refusing to quarantine data." >&2; exit 1; }
test "$(findmnt -n -o TARGET -T /mnt/nvme/docker)" = /mnt/nvme ||
  { echo "Docker destination is not on the NVMe mount." >&2; exit 1; }
if sudo test -e "$BACKUP_DIR/containerd-migration.enabled"; then
  test "$(findmnt -n -o TARGET -T /mnt/nvme/containerd)" = /mnt/nvme ||
    { echo "containerd destination is not on the NVMe mount." >&2; exit 1; }
fi
if sudo test -e "$BACKUP_DIR/daemon.json.absent"; then
  :
else
  sudo test -f "$BACKUP_DIR/daemon.json" ||
    { echo "Docker configuration backup not found." >&2; exit 1; }
fi
if sudo test -e "$BACKUP_DIR/containerd-config.toml.absent"; then
  :
else
  sudo test -f "$BACKUP_DIR/containerd-config.toml" ||
    { echo "containerd configuration backup not found." >&2; exit 1; }
fi
sudo test -d /var/lib/docker || { echo "Docker data root not found." >&2; exit 1; }
if sudo test -e /var/lib/docker.pre-nvme-migration; then
  echo "Docker quarantine already exists." >&2
  exit 1
fi
if sudo test -e "$BACKUP_DIR/containerd-data-source.present"; then
  sudo test -d /var/lib/containerd ||
    { echo "containerd data root not found." >&2; exit 1; }
  if sudo test -e /var/lib/containerd.pre-nvme-migration; then
    echo "containerd quarantine already exists." >&2
    exit 1
  fi
fi

sudo systemctl stop docker.socket docker.service containerd
for unit in docker.socket docker.service containerd; do
  ! sudo systemctl is-active --quiet "$unit" ||
    { echo "$unit is still active; refusing to move live data." >&2; exit 1; }
done
sudo mv /var/lib/docker /var/lib/docker.pre-nvme-migration
if sudo test -e "$BACKUP_DIR/containerd-data-source.present"; then
  sudo mv /var/lib/containerd /var/lib/containerd.pre-nvme-migration
fi
sudo systemctl start containerd docker

Verify the Docker root, images, volumes, and application data again. Keep the quarantined directories until the deployment has operated successfully and you have a separate backup.

To roll back after quarantine, preflight every backup and destination before stopping services. Then preserve any directories recreated by the failed configuration, restore the old data to its exact path, restore or remove each configuration file according to its marker, and restart the services:

set -euo pipefail
# Set BACKUP_DIR to the path printed in step 2.
sudo test -d "$BACKUP_DIR" || { echo "Backup directory not found." >&2; exit 1; }
if sudo test -e "$BACKUP_DIR/daemon.json.absent"; then
  :
else
  sudo test -f "$BACKUP_DIR/daemon.json" ||
    { echo "Docker configuration backup not found." >&2; exit 1; }
fi
if sudo test -e "$BACKUP_DIR/containerd-config.toml.absent"; then
  :
else
  sudo test -f "$BACKUP_DIR/containerd-config.toml" ||
    { echo "containerd configuration backup not found." >&2; exit 1; }
fi

ROLLBACK_SUFFIX="failed-nvme-$(date +%Y%m%d-%H%M%S)"
sudo test -d /var/lib/docker.pre-nvme-migration ||
  { echo "Docker quarantine not found." >&2; exit 1; }
sudo test ! -e "/var/lib/docker.$ROLLBACK_SUFFIX" ||
  { echo "Docker failure quarantine already exists." >&2; exit 1; }
if sudo test -e "$BACKUP_DIR/containerd-data-source.present"; then
  sudo test -d /var/lib/containerd.pre-nvme-migration ||
    { echo "containerd quarantine not found." >&2; exit 1; }
  sudo test ! -e "/var/lib/containerd.$ROLLBACK_SUFFIX" ||
    { echo "containerd failure quarantine already exists." >&2; exit 1; }
fi

sudo systemctl stop docker.socket docker.service containerd
for unit in docker.socket docker.service containerd; do
  ! sudo systemctl is-active --quiet "$unit" ||
    { echo "$unit is still active; aborting rollback." >&2; exit 1; }
done
if sudo test -e /var/lib/docker; then
  sudo mv /var/lib/docker "/var/lib/docker.$ROLLBACK_SUFFIX"
fi
sudo mv /var/lib/docker.pre-nvme-migration /var/lib/docker

if sudo test -e "$BACKUP_DIR/containerd-data-source.present"; then
  if sudo test -e /var/lib/containerd; then
    sudo mv /var/lib/containerd "/var/lib/containerd.$ROLLBACK_SUFFIX"
  fi
  sudo mv /var/lib/containerd.pre-nvme-migration /var/lib/containerd
fi

if sudo test -e "$BACKUP_DIR/daemon.json.absent"; then
  sudo rm -f /etc/docker/daemon.json
else
  sudo cp -a "$BACKUP_DIR/daemon.json" /etc/docker/daemon.json
fi
if sudo test -e "$BACKUP_DIR/containerd-config.toml.absent"; then
  sudo rm -f /etc/containerd/config.toml
else
  sudo cp -a "$BACKUP_DIR/containerd-config.toml" /etc/containerd/config.toml
fi
sudo systemctl start containerd docker

Other Performance Considerations

NVIDIA Jetson platforms are designed to be configurable for different power and performance needs. By default, the NVIDIA AGX Orin comes configured with "medium" performance and power settings which can be changed with the nvpmodel utility. For more details on this utility, see the NVIDIA Jetson Linux Developer Guide.

MAXN Power Mode

If your environment supports higher power draw and heat output from the NVIDIA AGX Orin, you can use the command below to set the power mode to "MAXN" (or "unlimited") for better compute performance:

sudo nvpmodel -m 0

For more information on available modes, power consumption, and clock frequencies, refer to the NVIDIA Jetson Linux Developer Guide.

Jetson Clocks

Even when using "MAXN" power mode, the clock frequencies configured for each chip or accelerator are defined as ranges. When running real-time applications on these platforms, the delays introduced when scaling clock frequencies can cause "hitches" or momentary latencies. To alleviate this, NVIDIA provides another utility called jetson_clocks which pins each chip's or accelerator's frequency to the max frequency in its range. However, the configuration changes that jetson_clocks applies are not persistent across reboots.

warning

Validate MAXN and jetson_clocks with the intended workload while monitoring tegrastats for thermal and power-limit throttling. If throttling occurs, disable persistent jetson_clocks and let NVIDIA's governor manage GPU and EMC clocks. Do not disable hardware protection without hardware-owner approval.

Run and inspect jetson_clocks manually before making it persistent:

sudo jetson_clocks
sudo jetson_clocks --show

Only after the workload completes without thermal or power-limit throttling, create /etc/systemd/system/jetson-clocks.service with:

[Unit]
Description=Jetson Clocks Service
After=nvpmodel.service

[Service]
Type=oneshot
ExecStart=/usr/bin/jetson_clocks
RemainAfterExit=true

[Install]
WantedBy=multi-user.target

Reload systemd, enable the service for boot, and start it:

sudo systemctl daemon-reload
sudo systemctl enable jetson-clocks.service
sudo systemctl start jetson-clocks.service

Configuring JetPack for GPU Acceleration​

MoveIt Pro GPU Inference Availability​

NVIDIA AGX Orin Onboard Storage Limitations​

Choosing a Drive​

Installing the NVMe Drive​

Formatting and Mounting​

Migrating Docker Storage Location​

Other Performance Considerations​

MAXN Power Mode​

Jetson Clocks​