Improve Docker multi-user isolation and document suffix behavior

[zhexulong]

Description

This PR improves Docker multi-user isolation for IsaacLab development environments.

When --suffix is omitted, the container naming now defaults to a sanitized user-derived suffix. This suffix is also propagated to COMPOSE_PROJECT_NAME so each user gets an isolated Compose namespace. The startup flow now detects conflicting containers in the same Compose project before starting, while preserving legacy behavior when --suffix '' is explicitly used.

This change reduces cross-user naming/project collisions on shared machines and keeps backward compatibility for existing no-suffix workflows.

In addition, this PR updates deployment documentation, adds a changelog entry, bumps the extension version, and updates the contributors list to align with checklist expectations.

Fixes # (issue)

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Documentation update

Screenshots

Not applicable (CLI/container orchestration behavior change).

Checklist

• I have read and understood the [contribution guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
• I have run the pre-commit checks with ./isaaclab.sh --format (equivalent check executed via pre-commit run --all-files and targeted file runs in this environment)
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• I have updated the changelog and the corresponding version in the extension's config/extension.toml file (maintained by the current develop branch)
• I have added my name to the CONTRIBUTORS.md or my name already exists there

Validation Notes

• Verified suffix mapping behavior for omitted / empty / custom --suffix.
• Verified COMPOSE_PROJECT_NAME follows suffix for user-level isolation.
• Verified pre-start conflict detection catches same-project conflicts and excludes the current target container.
• Verified compatibility path remains for explicit --suffix ''.
• pre-commit run --all-files passes; docs/changelog/version/contributor updates were validated with targeted checks.

[greptile-apps]

Greptile Summary

This PR successfully implements multi-user Docker isolation by defaulting omitted --suffix to a username-derived value and propagating it to COMPOSE_PROJECT_NAME for namespace isolation. The implementation adds pre-start conflict detection to prevent accidental container recreation while preserving backward compatibility through explicit --suffix ''.

Key changes:

• Suffix defaults to sanitized username when omitted, enabling per-user isolation on shared machines
• COMPOSE_PROJECT_NAME set based on suffix to isolate Docker Compose namespaces
• Conflict detection with label filtering and graceful fallback prevents cross-user collisions
• Legacy no-suffix behavior explicitly preserved with --suffix ''
• Comprehensive documentation, tests, and changelog updated
• Breaking change clearly documented with migration guidance

The implementation is well-structured with proper error handling and fallback logic. Previous reviewer performance concerns about N+1 docker inspect calls in the fallback path are valid but not critical since the primary path uses efficient label filtering.

Confidence Score: 4/5

• This PR is safe to merge with minor performance considerations in edge cases
• Well-implemented feature with comprehensive tests, documentation, and backward compatibility. Previous reviewer concerns were addressed. The N+1 docker inspect performance issue in the fallback path is a valid optimization opportunity but not a blocker since the primary code path uses efficient label filtering and the fallback only triggers on older Docker versions.
• docker/utils/container_interface.py contains the most complex logic with conflict detection - verify the fallback path behavior on systems where label filtering is unavailable

Important Files Changed

Filename	Overview
docker/container.py	Updated --suffix argument from nargs="?" to type=str to disallow --suffix without value, with clear help text explaining new default behavior
docker/utils/container_interface.py	Added username-based default suffix, COMPOSE_PROJECT_NAME isolation, and conflict detection with graceful fallback; performance concern with N+1 docker inspect calls in fallback path noted in previous review
docs/source/deployment/docker.rst	Comprehensively documented new suffix behavior, migration notes, and conflict detection with clear examples

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Start[User runs container.py start] --> ParseSuffix{Parse --suffix argument}
    ParseSuffix -->|Omitted| DefaultUser[Generate suffix from username]
    ParseSuffix -->|Empty string ''| LegacyMode[Use empty suffix - legacy mode]
    ParseSuffix -->|Custom value| CustomSuffix[Use custom suffix with hyphen]
    
    DefaultUser --> SetProject[Set COMPOSE_PROJECT_NAME<br/>isaac-lab-username]
    LegacyMode --> SetProjectLegacy[Set COMPOSE_PROJECT_NAME<br/>isaac-lab]
    CustomSuffix --> SetProjectCustom[Set COMPOSE_PROJECT_NAME<br/>isaac-lab-custom]
    
    SetProject --> CheckConflicts
    SetProjectLegacy --> CheckConflicts
    SetProjectCustom --> CheckConflicts
    
    CheckConflicts[Detect conflicting containers] --> TryFilter{Try docker ps<br/>with label filter}
    TryFilter -->|Success| FilterResults[Return containers in<br/>same project]
    TryFilter -->|Fails| Fallback[Fallback: inspect<br/>all containers]
    
    Fallback --> InspectLoop[Loop through containers<br/>check project labels]
    InspectLoop --> FilterResults
    
    FilterResults --> HasConflicts{Found conflicts?}
    HasConflicts -->|No| StartContainer[Build and start container]
    HasConflicts -->|Yes| ShowError[Show conflict error<br/>with resolution options]
    
    ShowError --> ForceCheck{ISAACLAB_FORCE_START=1?}
    ForceCheck -->|Yes| StartContainer
    ForceCheck -->|No| AbortStart[Abort with RuntimeError]
    
    StartContainer --> End[Container running]
    AbortStart --> End

Loading

_{Last reviewed commit: e44fcbd}

[greptile-apps]

_{6 files reviewed, 4 comments}

_{Edit Code Review Agent Settings | Greptile}

[zhexulong]

@greptile

[greptile-apps]

_{6 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[zhexulong]

@greptile

[greptile-apps]

_{5 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[zhexulong]

@greptile

[greptile-apps]

_{5 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[zhexulong]

@greptile

[greptile-apps]

_{5 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[zhexulong]

@greptile

[greptile-apps]

_{5 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Additional Comments (1)

docker/container.py
Missing const makes --suffix (no value) ambiguous

With nargs="?", argparse distinguishes three cases:

• --suffix omitted → uses default (= None)
• --suffix present but no value → uses const (defaults to None when unset)
• --suffix '' → value is ""

Since const is not set, typing --suffix without a value produces None, which the new ContainerInterface code treats identically to omitting --suffix (i.e., it generates a user-derived suffix). This is a subtle behavior change from the original code where both None and "" mapped to empty suffix.

A user who types ./container.py start --suffix expecting legacy behavior will instead get a user-derived suffix. Adding const="" would make --suffix (alone) give the legacy empty-suffix behavior, which better matches user expectations:

    parent_parser.add_argument(
        "--suffix",
        nargs="?",
        default=None,
        const="",
        help=(
            "Optional docker image and container name suffix. If omitted (default), a per-user suffix"
            " derived from the current username is used to avoid name collisions in multi-user environments."
            " If you explicitly pass an empty string (``--suffix ''``), the old behavior (no suffix) is preserved."
            " A hyphen is inserted between the profile and the suffix when a nonempty suffix is used."
            " For example, with profile 'base' and suffix 'custom' the container will be named"
            " ``isaac-lab-base-custom``."
        ),
    )

[zhexulong]

@greptile

[greptile-apps]

Additional Comments (1)

docker/test/test_docker.py
Existing tests break with new default suffix

The ("base", "") and ("ros2", "") test cases pass no --suffix flag on the CLI (line 24: suffix_args = []), but expect the container name to be isaac-lab-{profile} (the old no-suffix behavior). With this PR, omitting --suffix now defaults to a username-derived suffix, so the actual container name will be isaac-lab-{profile}-{username}, causing the assertion on line 41 to fail.

These test cases need to be updated to either:

1. Pass --suffix '' explicitly to test legacy no-suffix behavior, or
2. Compute the expected username-based container name for the "omitted suffix" scenario.

    if suffix != "":
        container_name = f"isaac-lab-{profile}-{suffix}"
        suffix_args = ["--suffix", suffix]
    else:
        container_name = f"isaac-lab-{profile}"
        suffix_args = ["--suffix", ""]

[zhexulong]

@greptile