Update POC Docker mode to use deploy runtime

[YuanTingHsieh]

Summary

• Change generated nvflare poc prepare -d projects to record a POC Docker runtime config instead of injecting the old StaticFileBuilder Docker image option.
• Treat only poc_runtime.runtime: docker as supported POC Docker mode; old StaticFileBuilder.args.docker_image projects no longer enable POC Docker start commands.
• Prepare POC server/client kits through the same Docker preparation helpers used by nvflare deploy prepare, producing start_docker.sh and DockerJobLauncher resources.
• Remove the dead POC add_docker_builder helper so POC no longer points at the old DockerBuilder/docker-compose path.
• Pre-populate Docker POC study_data.yaml so jobs in the default study can use /data/default/poc, backed by $NVFLARE_POC_WORKSPACE/data.
• Validate malformed poc_runtime, parent, and job_launcher shapes with clear CLIExceptions, remove an unreachable runtime guard, and write POC data sources with realpath.
• Update POC Docker docs and add unit coverage for deploy-mode command selection, runtime detection, client target patching, study-data generation, malformed runtime config handling, and the unsupported old static-builder Docker path.

Validation

• /Users/yuantingh/NVFlare/venv/bin/python -m isort nvflare/tool/poc/poc_commands.py with isort==5.13.2
• /Users/yuantingh/NVFlare/venv/bin/python -m black nvflare/tool/poc/poc_commands.py with black==25.9.0
• /Users/yuantingh/NVFlare/venv/bin/python -m flake8 nvflare/tool/poc/poc_commands.py tests/unit_test/lighter/poc_commands_test.py tests/unit_test/tool/poc/poc_output_test.py with flake8==7.1.1
• git diff --check
• /Users/yuantingh/NVFlare/venv/bin/python -m pytest tests/unit_test/lighter/poc_commands_test.py tests/unit_test/tool/poc/poc_output_test.py -q (71 passed)
• Generated a Docker POC workspace and confirmed local/study_data.yaml maps default.poc.source to $NVFLARE_POC_WORKSPACE/data with mode: rw, with no default_job_mounts or NVFL_DOCKER_DATA_DIR leftovers.

[greptile-apps]

Greptile Summary

This PR replaces the legacy StaticFileBuilder Docker image injection path for POC with the same deploy-time Docker preparation used by nvflare deploy prepare, producing start_docker.sh and DockerJobLauncher resources. Only poc_runtime.runtime: docker now activates Docker POC mode; old StaticFileBuilder.args.docker_image entries no longer trigger Docker start commands. The change also pre-populates study_data.yaml with the POC workspace data mount, patches client fed_client.json server aliases for Docker networking, adds structured CLIException validation for malformed poc_runtime shapes, and is backed by 71 new unit tests.

Confidence Score: 5/5

Safe to merge; only P2 robustness suggestions remain.

No P0 or P1 findings. The two P2 comments are minor robustness nits that do not affect correctness in normal operation. The logic change is well-tested with 71 passing unit tests and all new code paths are guarded with CLIExceptions.

nvflare/tool/poc/poc_commands.py — specifically _prepare_poc_docker_deployments (participant key access) and _write_poc_docker_study_data (unconditional write).

Important Files Changed

Filename	Overview
nvflare/tool/poc/poc_commands.py	Core logic change: replaces StaticFileBuilder Docker path with poc_runtime-driven deploy-mode Docker preparation; two minor P2 issues (bare key access, unconditional YAML write).
nvflare/tool/poc/service_constants.py	Adds DOCKER_RUN_MODE and DOCKER_RUN_MODE_DEPLOY constants; straightforward and correct.
tests/unit_test/lighter/poc_commands_test.py	Comprehensive new tests cover deploy-mode command selection, runtime detection, invalid poc_runtime shapes, study_data generation, client-target patching, and deep-copy protection.
tests/unit_test/tool/poc/poc_output_test.py	Renames and adds is_docker_run test for poc_runtime path; minimal and correct.
docs/user_guide/nvflare_cli/poc_command.rst	Updates -d flag description and adds Docker POC mode behavior notes; accurate.
docs/design/nvflare_cli.md	Updates -d CLI option description in the design reference; accurate.
docs/user_guide/data_scientist_guide/job_recipe.rst	Expands docker_image parameter description to clarify SP/CP vs SJ/CJ image responsibilities; accurate.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["nvflare poc prepare -d image"] --> B["local_provision()"]
    B --> B1["add_poc_docker_runtime() writes poc_runtime to project_config"]
    B --> B2["copy.deepcopy(project_config) provision_config"]
    B2 --> B3["prepare_project / Provisioner.provision"]
    B3 --> B4["Kits generated in prod_XX/"]
    B4 --> C["prepare_poc_provision()"]
    C --> C1["_prepare_poc_docker_deployments(workspace, project_config)"]
    C1 --> C2["get_poc_docker_runtime_config() normalized docker_config"]
    C2 --> C3["for each server/client participant"]
    C3 --> D["_prepare_poc_docker_kit(kit_dir, docker_config, workspace)"]
    D --> D1["_validate_runtime_config / _validate_kit / _prepare_docker"]
    D --> D2["_write_poc_docker_study_data() local/study_data.yaml"]
    D --> D3{"role == client?"}
    D3 -->|Yes| D4["_patch_poc_docker_client_target() localhost to server alias"]
    D3 -->|No| D5["skip patch"]
    C1 --> C4["update_storage_locations()"]
    subgraph Dynamic
        E["_provision_poc_participant_only()"] --> E1["shutil.move kit to target_kit"]
        E1 --> E2["get_docker_run_mode() == deploy?"]
        E2 -->|Yes| D
    end

Loading

_{Reviews (5): Last reviewed commit: "Merge branch 'main' into codex/poc-docke..." | Re-trigger Greptile}

[Copilot]

Pull request overview

This PR updates nvflare poc prepare -d/--docker-image to provision POC workspaces using the same Docker runtime preparation path as nvflare deploy prepare, generating start_docker.sh + Docker job-launcher resources and persisting the Docker runtime config in the POC project config, while keeping legacy docker.sh -d support for older projects.

Changes:

• Introduces POC Docker runtime detection/mode selection (legacy vs deploy) and switches Docker-mode start commands to start_docker.sh for deploy-mode workspaces.
• Adds deploy-mode Docker kit preparation for POC (including client target patching) and pre-populates study_data.yaml to mount $POC_WORKSPACE/data as /data/default/poc.
• Updates docs and adds unit tests for runtime detection, command selection, client target patching, and study-data generation.

Reviewed changes

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

Show a summary per file

File	Description
tests/unit_test/tool/poc/poc_output_test.py	Updates/extends coverage for Docker runtime detection in POC configs.
tests/unit_test/lighter/poc_commands_test.py	Adds unit tests for deploy-mode Docker command selection and kit/study-data preparation helpers.
nvflare/tool/poc/service_constants.py	Adds constants for Docker run mode (legacy vs deploy).
nvflare/tool/poc/poc_commands.py	Implements deploy-mode Docker runtime config, detection, kit preparation, and study-data generation for POC.
docs/user_guide/nvflare_cli/poc_command.rst	Documents new Docker POC behavior (deploy-mode prep + dataset mount path).
docs/user_guide/data_scientist_guide/job_recipe.rst	Clarifies meaning of docker_image for Docker POC and job launcher_spec requirements.
docs/design/nvflare_cli.md	Updates CLI design table entry for --docker_image semantics.

---

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

[YuanTingHsieh]

/build

[YuanTingHsieh]

/build