feat: add support to build with docker and natively #430

wambitz · 2026-01-22T05:40:27Z

This pull request introduces robust support for building and running Isaac Sim in Docker containers, with a focus on simplifying the setup process for Ubuntu 24.04+ (which ships with an incompatible GCC version). The changes add a containerized build workflow, update documentation to guide users through both native and containerized builds, and provide scripts for building, running, and cleaning Docker artifacts. These updates make it much easier to build and deploy Isaac Sim on systems with newer compilers or minimal host dependencies.

Key changes include:

Containerized Build and Deployment Support

Added a --docker-build option to prep_docker_build.sh to build Isaac Sim inside a Docker container, ensuring compatibility with Ubuntu 24.04+ and hosts lacking GCC 11. The script now builds a builder image with GCC 11 and runs the build inside the container, mounting necessary volumes for correct artifact ownership and caching. [1] [2] [3] [4] [5]
Updated tools/docker/Dockerfile to install GCC 11 and set it as the default compiler, enabling containerized builds regardless of the host's GCC version. [1] [2]
Added tools/docker/clean_docker.sh to clean up Docker build artifacts and runtime cache, ensuring a clean environment for repeated builds.
Enhanced tools/docker/run_docker.sh to properly handle cache directory ownership and X11 display forwarding, improving GUI support and cache persistence in containers.

Documentation Updates

Expanded README.md and tools/docker/README.md with detailed instructions for both native and containerized builds, including example commands, prerequisites (like NVIDIA Container Toolkit), troubleshooting tips, and guidance for Ubuntu 24.04+ users. [1] [2] [3] [4] [5] [6]
Clarified the difference between native (--build) and containerized (--docker-build) build options and updated troubleshooting and important notes sections to reflect the new workflow.

Minor Corrections

Fixed a typo in CONTRIBUTING.md ("acccept" → "accept").

- Install gcc-11, g++-11, and build-essential packages - Allows containerized builds on newer Ubuntu versions - Maintains compatibility with existing functionality

- Introduce --docker-build option to build Isaac Sim inside container - Eliminates native GCC 11 installation requirement on Ubuntu 24.04+ - Mount packman cache at same path to preserve symlinks - Auto-create _isaac_cache with correct permissions for runtime - Maintains backward compatibility with --build flag

- Enable X11 forwarding for GUI support (xhost + DISPLAY + socket mount) - Mount _isaac_cache for persistent extension/shader storage - Preserve NVIDIA's original script structure with minimal additions - Reduces extension download time on subsequent runs

- Document --docker-build option for Ubuntu 24.04+ users - Add Running section with examples and persistent cache explanation - Extend troubleshooting with GCC, X11, and permission issues - Preserve original NVIDIA documentation structure

- Link to tools/docker/README.md for containerized deployments - Provide quick overview of Docker build/run workflow

…-24.04 feat: containerized build ubuntu 24.04

Copilot

Pull request overview

This pull request adds comprehensive Docker containerization support for building and running Isaac Sim, addressing compatibility issues with Ubuntu 24.04+ which ships with GCC 13 (Isaac Sim requires GCC 11). The changes introduce a new --docker-build option that enables building within a container with the correct compiler version, alongside enhanced documentation and supporting scripts for the Docker workflow.

Changes:

Added --docker-build flag to enable containerized builds with GCC 11, providing a complete workflow for building Isaac Sim in Docker without host compiler dependencies
Enhanced Docker runtime support with persistent caching, X11 display forwarding, and proper file ownership handling
Expanded documentation with detailed instructions for both native and containerized builds, including troubleshooting guidance

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
tools/docker/prep_docker_build.sh	Added `--docker-build` option and containerized build/prep workflow with packman cache support
tools/docker/Dockerfile	Installed GCC 11 and build tools to enable containerized compilation
tools/docker/run_docker.sh	Enhanced with cache directory management, X11 forwarding, and volume mounts for persistent storage
tools/docker/clean_docker.sh	New script to clean Docker build artifacts and runtime cache
tools/docker/README.md	Updated with containerized build instructions, usage examples, and troubleshooting
README.md	Added Docker deployment section with quick-start commands
CONTRIBUTING.md	Fixed typo ("acccept" → "accept")

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-22T05:48:44Z

tools/docker/run_docker.sh

+xhost +local:docker &>/dev/null || true
+
+# Create cache directory with container user ownership (uid 1234)
+mkdir -p "${CACHE_DIR}"


The script creates a cache directory and attempts to change its ownership using a Docker container before the image is guaranteed to exist. If the user runs this script before building the image (isaac-sim-docker:latest), the chown command will fail with "image not found". Consider checking if the image exists first, or handle the error gracefully, or document that this script should only be run after building the image.

Suggested change

mkdir -p "${CACHE_DIR}"

mkdir -p "${CACHE_DIR}"

if ! docker image inspect "${IMAGE_TAG}" > /dev/null 2>&1; then

echo "Error: Docker image '${IMAGE_TAG}' not found. Please build or pull it before running this script." >&2

exit 1

fi

Copilot · 2026-01-22T05:48:45Z

tools/docker/clean_docker.sh

+
+# _isaac_cache: runtime cache (uid 1234 ownership, use Docker to clean)
+if [[ -d "${REPO_ROOT}/_isaac_cache" ]]; then
+    docker run --rm --entrypoint rm -v "${REPO_ROOT}/_isaac_cache":/cache "${IMAGE_TAG}" -rf /cache


The cleanup script attempts to use the Docker image to change ownership before removing files, but it doesn't check if the image exists. If the image has been removed or doesn't exist, this command will fail. The script should either check for image existence first or handle the error case where the image is not available (e.g., fall back to sudo rm if needed, or skip the docker run step).

Suggested change

docker run --rm --entrypoint rm -v "${REPO_ROOT}/_isaac_cache":/cache "${IMAGE_TAG}" -rf /cache

if docker image inspect "${IMAGE_TAG}" >/dev/null 2>&1; then

docker run --rm --entrypoint rm -v "${REPO_ROOT}/_isaac_cache":/cache "${IMAGE_TAG}" -rf /cache

else

echo "Warning: Docker image '${IMAGE_TAG}' not found. Skipping Docker-based cache cleanup."

fi

Copilot · 2026-01-22T05:48:45Z

tools/docker/prep_docker_build.sh

+# Use container if --docker-build was specified (no host dependencies)
+# Otherwise use native Python (original behavior)
+if [[ "$DOCKER_BUILD" == "true" ]]; then
+    PACKMAN_CACHE_DIR="$(pwd)/_packman_cache"


The variable PACKMAN_CACHE_DIR is defined twice - once at line 10 as a global variable and again at line 140 inside the conditional block. The redefinition at line 140 is redundant since the variable is already set at the top of the script. Consider removing this duplicate assignment.

Suggested change

PACKMAN_CACHE_DIR="$(pwd)/_packman_cache"

Copilot · 2026-01-22T05:48:45Z

tools/docker/clean_docker.sh

+# Clean Docker build artifacts and runtime cache
+
+IMAGE_TAG="isaac-sim-docker:latest"
+SCRIPT_DIR=$(dirname ${BASH_SOURCE})


The variable SCRIPT_DIR uses dirname ${BASH_SOURCE} without proper quoting. This should be "${BASH_SOURCE[0]}" with quotes and array index to handle paths with spaces correctly and to follow bash best practices.

Suggested change

SCRIPT_DIR=$(dirname ${BASH_SOURCE})

SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"

Copilot · 2026-01-22T05:48:45Z

tools/docker/prep_docker_build.sh

+        -w /workspace \
+        "$BUILDER_IMAGE" \
+        -c "
+            pip install -q --break-system-packages -r tools/docker/requirements.txt && \


The --break-system-packages flag is used with pip install, which is generally discouraged as it can interfere with system-managed packages. Since this is running inside a container where the environment is controlled, consider using a virtual environment or user-level install (pip install --user) instead for better practice, even in containerized environments.

Suggested change

pip install -q --break-system-packages -r tools/docker/requirements.txt && \

python3 -m pip install -q --user -r tools/docker/requirements.txt && \

Copilot · 2026-01-22T05:48:46Z

tools/docker/prep_docker_build.sh

+if [[ "$DOCKER_BUILD" == "true" ]]; then
+    PACKMAN_CACHE_DIR="$(pwd)/_packman_cache"
+
+    if ! docker build -q -t "$BUILDER_IMAGE" -f tools/docker/Dockerfile tools/docker/ >/dev/null; then


The docker build command at line 142 uses the -q (quiet) flag and redirects output to /dev/null, which will suppress error messages if the build fails. This makes debugging difficult. Consider removing the -q flag or at least not redirecting stderr, so users can see what went wrong if the build fails.

Suggested change

if ! docker build -q -t "$BUILDER_IMAGE" -f tools/docker/Dockerfile tools/docker/ >/dev/null; then

if ! docker build -t "$BUILDER_IMAGE" -f tools/docker/Dockerfile tools/docker/; then

Copilot · 2026-01-22T05:48:46Z

tools/docker/prep_docker_build.sh

+        --docker-build)
+            DOCKER_BUILD=true
+            shift
+            ;;


The script allows both --build and --docker-build flags to be specified simultaneously. If both are provided, both build methods will execute sequentially, which is likely not the intended behavior and could be confusing. Consider adding validation to ensure these flags are mutually exclusive, or document this behavior clearly in the help message.

Copilot · 2026-01-22T05:48:46Z

tools/docker/run_docker.sh

-PRIVACY_EMAIL="${PRIVACY_EMAIL:-user@example.com}"  # Allow override via environment
+
+IMAGE_TAG="isaac-sim-docker:latest"
+PRIVACY_EMAIL="user@example.com"


The variable PRIVACY_EMAIL is now hardcoded to "user@example.com" and the ability to override it via environment variable has been removed. This is a breaking change for users who may have been setting this environment variable to a custom value. Consider keeping the environment variable override capability using: PRIVACY_EMAIL="${PRIVACY_EMAIL:-user@example.com}"

Suggested change

PRIVACY_EMAIL="user@example.com"

PRIVACY_EMAIL="${PRIVACY_EMAIL:-user@example.com}"

Copilot · 2026-01-22T05:48:46Z

tools/docker/run_docker.sh

+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+CACHE_DIR="${REPO_ROOT}/_isaac_cache"
+
+xhost +local:docker &>/dev/null || true


The xhost +local:docker call unconditionally relaxes X11 access control for your current display, effectively allowing any local client mapped to the docker user (i.e., any rootless Docker container) to connect to and control your X session. A compromised or malicious container image could then capture keystrokes, scrape window contents, or inject input into host applications. Consider narrowing X11 permissions to only the specific user/container needed and restoring the original xhost configuration after the container exits instead of leaving this broad rule in place.

wambitz added 7 commits January 21, 2026 18:07

Add GCC 11 support to Dockerfile for Ubuntu 24.04+ compatibility

e8e6d0b

- Install gcc-11, g++-11, and build-essential packages - Allows containerized builds on newer Ubuntu versions - Maintains compatibility with existing functionality

Add Docker deployment reference to main README

dbcf262

- Link to tools/docker/README.md for containerized deployments - Provide quick overview of Docker build/run workflow

Add clean_docker.sh for Docker artifact cleanup

eaec847

Merge pull request #1 from wambitz/feature/containerized-build-ubuntu…

26bce82

…-24.04 feat: containerized build ubuntu 24.04

Copilot AI review requested due to automatic review settings January 22, 2026 05:40

Copilot started reviewing on behalf of wambitz January 22, 2026 05:40 View session

Copilot AI reviewed Jan 22, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add support to build with docker and natively #430

feat: add support to build with docker and natively #430

Uh oh!

wambitz commented Jan 22, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Copilot AI Jan 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	SCRIPT_DIR=$(dirname ${BASH_SOURCE})
	SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"

	pip install -q --break-system-packages -r tools/docker/requirements.txt && \
	python3 -m pip install -q --user -r tools/docker/requirements.txt && \

	if ! docker build -q -t "$BUILDER_IMAGE" -f tools/docker/Dockerfile tools/docker/ >/dev/null; then
	if ! docker build -t "$BUILDER_IMAGE" -f tools/docker/Dockerfile tools/docker/; then

	PRIVACY_EMAIL="user@example.com"
	PRIVACY_EMAIL="${PRIVACY_EMAIL:-user@example.com}"

feat: add support to build with docker and natively #430

Are you sure you want to change the base?

feat: add support to build with docker and natively #430

Uh oh!

Conversation

wambitz commented Jan 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant