Document non-root Docker volume fix for XR teleop startup#6060
Conversation
Greptile SummaryThis PR adds documentation-only warnings to two RST files explaining a permissions regression introduced in Isaac Lab 3.0.0-beta2, where the switch to a non-root container user (uid/gid 1000) causes startup failures when bind-mounted host directories are owned by
Confidence Score: 4/5Safe to merge — docs-only change with no code impact; two minor clarity issues in the XR teleoperation admonition. Both changes are documentation additions that correctly describe a real permissions regression and its fix. The docker.rst addition is straightforward and accurate. The cloudxr_teleoperation.rst addition is mostly correct but includes a Docker Compose cleanup option directly beneath a paragraph that explicitly tells users not to use Docker Compose, without clarifying this is for legacy volume cleanup. It also uses a hardcoded docker_isaac-data volume name that assumes a specific Compose project prefix. These reduce clarity for users encountering the error for the first time. docs/source/how-to/cloudxr_teleoperation.rst — the Docker Compose bullet and hardcoded volume name warrant a second look for clarity. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[User pulls Isaac Lab 3.0.0-beta2+ image] --> B{Host bind-mount dirs exist\nand owned by uid/gid 1000?}
B -- Yes --> C[Container starts successfully\nExtension registry syncs]
B -- No --> D[Docker auto-creates dir as root\nOR stale root-owned volume]
D --> E[PermissionError on /root/.local/share/ov/data/exts]
E --> F[Extension registry sync fails]
F --> G[XR bundle dependency solver fails\nApp exits]
B -- No, fix needed --> H{Setup type}
H -- Docker Compose legacy volumes --> I[docker compose down --volumes\nor chown via alpine container]
H -- Single container bind mounts --> J[mkdir -p ~/docker/isaac-sim/...\nsudo chown -R 1000:1000 ~/docker/isaac-sim]
I --> C
J --> C
Reviews (1): Last reviewed commit: "Fix XR in docker" | Re-trigger Greptile |
| * **Docker Compose:** recreate the named volumes, e.g. | ||
|
|
||
| .. code-block:: bash | ||
|
|
||
| docker compose --file docker-compose.yaml --profile base --env-file .env.base down --volumes | ||
|
|
||
| See :ref:`deployment-docker` for details. To preserve cached data instead of | ||
| deleting it, ``chown`` the volume: ``docker run --rm -v docker_isaac-data:/data alpine | ||
| chown -R 1000:1000 /data``. |
There was a problem hiding this comment.
The section header explicitly says "Do not use Docker Compose" for XR teleop in this release, yet this bullet immediately recommends docker compose down --volumes. A reader following the single-container path will be confused about whether Compose applies to them at all. The intent (cleaning up legacy volumes left over from a 2.x Compose setup) is never stated, so it reads like Compose is a valid current workflow. Consider prefacing this with a phrase like "If you previously used Docker Compose with Isaac Lab 2.x and have stale named volumes:" to make the scope unambiguous.
| deleting it, ``chown`` the volume: ``docker run --rm -v docker_isaac-data:/data alpine | ||
| chown -R 1000:1000 /data``. |
There was a problem hiding this comment.
docker_ Compose project-name prefix may not match user's setup
The inline chown example uses the volume name docker_isaac-data, which assumes the Compose project name is docker (the default when the project lives in a directory named docker). Users who cloned to a differently-named directory or set COMPOSE_PROJECT_NAME will have a different prefix and the command will silently fail because Docker will just create a new, empty volume under that name. It would help to note that users should confirm their actual volume name with docker volume ls | grep isaac before running the command.
There was a problem hiding this comment.
📋 Documentation Review — PR #6060
Summary: Documentation-only change that explains a non-root Docker volume permission issue affecting XR teleop startup. No code changes, no runtime impact.
🔬 Design Assessment
Placement: Both documentation additions are well-placed:
docs/source/deployment/docker.rst— The admonition is correctly positioned in the "Running Pre-Built Isaac Lab Container" section, immediately after thedocker pullinstruction and before thedocker runexamples that reference the bind-mount paths. Users will see the warning before they hit the problem.docs/source/how-to/cloudxr_teleoperation.rst— The admonition sits in the "Run with Docker" section, right after the note about single-container architecture. This is where users following the XR teleop workflow will encounter the failure.
Cross-reference: The CloudXR doc correctly references :ref:deployment-docker`` for details, creating good discoverability between the two pages.
Verdict: ✅ Ship it — well-structured, actionable documentation.
Findings
💡 Minor: docker.rst — image tag mismatch with admonition context
The admonition states the non-root change was introduced in 3.0.0-beta2, but the docker pull command immediately above it references nvcr.io/nvidia/isaac-lab:3.0.0-beta1 (the older root-based image). Users pulling beta1 won't hit this issue — it only affects beta2+. Consider either:
- Adding a note that this applies when pulling
3.0.0-beta2or later tags, or - Updating the
docker pullexample to reference3.0.0-beta2(if available)
This isn't blocking since the admonition itself clearly states "3.0.0-beta2 and later", but the proximity to the beta1 pull command could confuse readers scanning quickly.
💡 Minor: cloudxr_teleoperation.rst — Docker Compose reference may confuse single-container users
The admonition's first bullet mentions docker compose ... down --volumes as a fix. However, the paragraph immediately preceding the admonition says:
Do not use Docker Compose, which is a multi-container setup as we had in Isaac Lab 2.x.
This creates a slight contradiction — users are told not to use Compose, then the fix offers a Compose command. The note likely targets users migrating from an older Compose-based setup who have stale named volumes. Consider clarifying this bullet, e.g.:
Migrating from an older Docker Compose setup: If you previously used Compose and still have its named volumes, recreate them…
💡 Nit: RST indentation inconsistency
In docker.rst, the admonition body uses 2-space indentation, while the surrounding RST content uses 3-space indentation (visible in the existing .. note:: blocks). This won't break rendering, but for consistency with the file's style, 3-space indent would match. (pre-commit passed, so this is purely cosmetic.)
CI Status
The license-check failure is unrelated to this PR — it failed due to disk space exhaustion on the CI runner while downloading a 1.4 GB wheel (isaacsim-extscache-kit-sdk). All other relevant checks passed (pre-commit ✅, broken links ✅, changelog ✅, build wheel ✅).
🧪 Test Coverage
No tests needed. This is a pure documentation change with no runtime code impact.
Overall: Clean, well-written documentation that will save users significant debugging time. The error cascade described (permission denied → registry sync failure → dependency solver failure) is genuinely confusing without this context. The suggestions above are minor polish — this is ready to merge as-is.
Description
Since the non-root Docker migration (#5618, first shipped in 3.0.0-beta2), the
container runs as user
isaaclab(uid/gid 1000) withHOME=/root. Persistentmounts at
/root/.local/share/ov/datathat were created by an older root-basedimage (stale named volumes) or by Docker as auto-created bind-mount dirs are
owned by
root, so the runtime user cannot write the extension-registry cache.For XR teleop this aborts startup with a confusing, seemingly-unrelated error:
PermissionError: [Errno 13] Permission denied: '/root/.local/share/ov/data/exts'
...
No versions of omni.kit.xr.bundle.generic that satisfies: isaaclab.python.xr.openxr-3.0.0 ...
Exiting app because of dependency solver failure...
The XR bundle isn't actually missing — the registry never synced because its
cache dir couldn't be created. This PR documents the cause and fix:
docs/source/how-to/cloudxr_teleoperation.rst: adds an admonition to the"Run with Docker" section explaining the failure and the fix (recreate/chown
volumes for Compose, pre-create/chown host dirs for single-container).
docs/source/deployment/docker.rst: warns that non-root prebuilt imagesneed bind-mount host dirs pre-created and chowned to uid/gid 1000, with a
copy-paste snippet.
Docs-only; no code changes and no changelog fragment (no
source/<pkg>/packagetouched).
Fixes # (issue)
Type of change
Checklist
pre-commitchecks with./isaaclab.sh --formatconfig/extension.tomlfileCONTRIBUTORS.mdor my name already exists there