DEV Community

Cover image for [Beginner] Docker Tutorial for jetson-containers on Jetson AGX Orin
Sergio Andres Usma
Sergio Andres Usma

Posted on

[Beginner] Docker Tutorial for jetson-containers on Jetson AGX Orin

#jetson #agxorin #jetsoncontainers #docker

Abstract

This tutorial explains how to use Docker with the jetson-containers project on an NVIDIA Jetson AGX Orin 64 GB running Ubuntu 22.04 and JetPack 6.2.2, focusing on beginner-friendly concepts and commands. It introduces basic container terminology, shows how to safely back up configuration files, and then walks through everyday Docker operations like starting, stopping, rebuilding, and re-running containers. The goal is to give new users a practical, copy‑pasteable reference they can keep open on the Jetson while working with jetson-containers.

1. Basic Concepts: Images, Containers, Volumes

For beginners, it helps to understand a few core terms before running commands.

  • Image: A read‑only template that contains an application and its OS-level dependencies (for example, a pre-built PyTorch + CUDA environment for Jetson).
  • Container: A running instance of an image with its own filesystem, processes, and network configuration; you can start, stop, and delete containers without touching the original image.
  • Dockerfile: A text file with instructions on how to build an image (which base image to use, what packages to install, what commands to run).
  • Volume: A directory from the host (your Jetson) that is mounted inside the container so changes persist on disk even if you delete the container.
  • Registry: A server that stores images (for example, Docker Hub or the GitHub Container Registry used by many Jetson projects).

Mental model: the image is like an ISO of a Linux distro, and the container is like the running system you boot from that ISO, with volumes acting as your persistent home folder.

2. Safety First: Backing Up Configuration Files

Before experimenting with Docker and jetson-containers, you should back up any configuration files or project directories you are going to modify.

2.1. Backing up directories on the Jetson

Pick a backup directory on your Jetson, for example ~/backups/jetson-containers.

mkdir -p ~/backups/jetson-containers
Enter fullscreen mode Exit fullscreen mode

To back up a directory that will be mounted into a container (for example ~/projects/my-app):

# Backup with timestamp
cp -a ~/projects/my-app \
  ~/backups/jetson-containers/my-app_$(date +%Y%m%d-%H%M%S)
Enter fullscreen mode Exit fullscreen mode

To back up a single file that might be edited (for example docker-compose.yml or a config file):

cp docker-compose.yml \
  docker-compose.yml.bak_$(date +%Y%m%d-%H%M%S)
Enter fullscreen mode Exit fullscreen mode

If you are about to edit a file inside a project:

# From inside the project directory
cp config.yaml config.yaml.bak_$(date +%Y%m%d-%H%M%S)
Enter fullscreen mode Exit fullscreen mode

Restoring is just the reverse:

cp ~/backups/jetson-containers/my-app_20260405-120000/* \
   ~/projects/my-app/
Enter fullscreen mode Exit fullscreen mode

3. Checking Docker on Jetson AGX Orin

You already have Docker 29.3.1 installed on your Jetson with arm64 support, which is what you need for jetson-containers.

Verify Docker is running:

docker version
docker info
Enter fullscreen mode Exit fullscreen mode

If docker info shows errors about permissions, add your user to the docker group and re‑login:

sudo usermod -aG docker $USER
# Then log out and log back in, or reboot
Enter fullscreen mode Exit fullscreen mode

To test with a simple container:

docker run --rm arm64v8/ubuntu:22.04 uname -a
Enter fullscreen mode Exit fullscreen mode

This command pulls an arm64 Ubuntu image and prints the kernel info, confirming Docker is working.

4. Using jetson-containers: Typical Workflow

This section uses generic patterns you can adapt to the jetson-containers project (git clone, build, and run commands are similar across JetPack 6 projects).

4.1. Cloning the jetson-containers repository

From your home directory:

cd ~
git clone https://github.com/dusty-nv/jetson-containers.git
cd jetson-containers
Enter fullscreen mode Exit fullscreen mode

Back up the repository before heavy changes:

cp -a ~/jetson-containers \
  ~/backups/jetson-containers/jetson-containers_$(date +%Y%m%d-%H%M%S)
Enter fullscreen mode Exit fullscreen mode

4.2. Building a jetson-containers image

Within the jetson-containers repository, there are scripts or Dockerfiles to build images optimized for your JetPack version.

Example pattern:

# Example: build an image for a specific package or stack
./scripts/build.sh <image-name>
# or directly with Docker
docker build -t my-jetson-image -f Dockerfile .
Enter fullscreen mode Exit fullscreen mode

Replace <image-name> with the target defined by jetson-containers (for example, a PyTorch or L4T base image name).

Key flags for docker build:

docker build \
  -t my-jetson-image \        # Tag (name) for your image
  -f Dockerfile .             # Dockerfile and build context
Enter fullscreen mode Exit fullscreen mode

5. Running, Stopping, and Inspecting Containers

This is the heart of day‑to‑day container usage.

5.1. Starting a new container with jetson-containers

A typical docker run command for Jetson should:

  • Use the correct image (from jetson-containers).
  • Pass through GPU access.
  • Mount your project directory as a volume.
  • Optionally set the container name.

Generic pattern:

docker run -it --rm \
  --gpus all \
  --network host \
  --ipc host \
  -v ~/projects/my-app:/workspace/my-app \
  --name my-jetson-container \
  my-jetson-image \
  /bin/bash
Enter fullscreen mode Exit fullscreen mode

Explanation of key flags:

  • -it: Interactive terminal.
  • --rm: Delete the container when it exits (good for experiments).
  • --gpus all: Give the container access to the Jetson GPU.
  • --network host: Share the host network stack (useful for ROS, web services, etc).
  • --ipc host: Share IPC for better performance with some frameworks.
  • -v host:container: Mount a host directory into the container.
  • --name: Easy name for managing the container later.

5.2. Listing running and stopped containers 

# Only running containers
docker ps

# All containers (running and stopped)
docker ps -a
Enter fullscreen mode Exit fullscreen mode

5.3. Attaching and entering a running container

If a container is running in the background:

docker exec -it my-jetson-container /bin/bash
Enter fullscreen mode Exit fullscreen mode

This opens a shell inside the running container.

5.4. Stopping and removing containers

To stop a running container:

docker stop my-jetson-container
Enter fullscreen mode Exit fullscreen mode

To forcibly stop (if it hangs):

docker kill my-jetson-container
Enter fullscreen mode Exit fullscreen mode

To remove a stopped container:

docker rm my-jetson-container
Enter fullscreen mode Exit fullscreen mode

To remove all stopped containers:

docker container prune
Enter fullscreen mode Exit fullscreen mode

6. Re-running and Rebuilding Images

When you change a Dockerfile or the jetson-containers configuration, you often need to rebuild images.

6.1. Re-running a container with the same configuration

If you used --name my-jetson-container, Docker keeps the container configuration until it is removed.

To start it again after it has been stopped:

docker start my-jetson-container
docker exec -it my-jetson-container /bin/bash
Enter fullscreen mode Exit fullscreen mode

If you used --rm, the container is deleted on exit, so you must run docker run again (the image itself remains).

6.2. Forcing a rebuild of an image

When you modify a Dockerfile or build context and want Docker to ignore previous cache layers:

docker build --no-cache -t my-jetson-image -f Dockerfile .
Enter fullscreen mode Exit fullscreen mode

If jetson-containers provides a build script, you can usually pass a similar --no-cache flag or use an environment variable, for example:

# Example pattern; adapt to the actual script interface
NO_CACHE=1 ./scripts/build.sh <image-name>
Enter fullscreen mode Exit fullscreen mode

To remove an image and force a clean rebuild:

docker rmi my-jetson-image
docker build -t my-jetson-image -f Dockerfile .
Enter fullscreen mode Exit fullscreen mode

List images to verify:

docker images
Enter fullscreen mode Exit fullscreen mode

6.3. Updating images from a registry

If jetson-containers publishes pre-built images, you can pull the latest version:

docker pull <registry>/<namespace>/<image>:<tag>
Enter fullscreen mode Exit fullscreen mode

After pulling, re-run your containers using the updated tag to test new versions safely (after backing up your mounted project directory).

7. Managing Data and Volumes Safely

To avoid losing important work when deleting containers, always use volumes (host directories mounted into containers).

7.1. Using host directories as volumes

Example:

mkdir -p ~/projects/my-app
docker run -it --rm \
  -v ~/projects/my-app:/workspace/my-app \
  my-jetson-image \
  /bin/bash
Enter fullscreen mode Exit fullscreen mode

Anything you save to /workspace/my-app inside the container appears in ~/projects/my-app on the Jetson and persists when the container is removed.

7.2. Using named Docker volumes (optional)

For simple persistent storage managed by Docker:

# Create a volume
docker volume create my-jetson-volume

# Use it in a container
docker run -it --rm \
  -v my-jetson-volume:/data \
  my-jetson-image \
  /bin/bash
Enter fullscreen mode Exit fullscreen mode

List volumes and remove unused ones:

docker volume ls
docker volume prune
Enter fullscreen mode Exit fullscreen mode

8. Useful Command Reference Table

Below is a quick reference table you can keep near your terminal.

Task Command (Jetson terminal)
Check Docker version docker version
List running containers docker ps
List all containers docker ps -a
List images docker images
Start new container docker run -it --rm --gpus all --network host --ipc host -v ~/proj:/workspace my-img
Stop container docker stop <name-or-id>
Force stop container docker kill <name-or-id>
Remove stopped container docker rm <name-or-id>
Remove image docker rmi <image>
Exec into running container docker exec -it <name-or-id> /bin/bash
Build image docker build -t my-img -f Dockerfile .
Build image without cache docker build --no-cache -t my-img -f Dockerfile .
Start stopped container docker start <name>
Backup directory before changes cp -a ~/dir ~/backups/dir_$(date +%Y%m%d-%H%M%S)
Backup single file before editing cp file.txt file.txt.bak_$(date +%Y%m%d-%H%M%S)

Table 1 — Common Docker commands on Jetson

9. Conclusion

With these concepts and commands, you can confidently use Docker and jetson-containers on your Jetson AGX Orin without risking important project data, thanks to consistent use of backups and volumes. As you become more comfortable, you can refine the docker run patterns, create your own Dockerfiles, and integrate jetson-containers more deeply into your development workflow.

Top comments (0)