[CI/Build][Docker] Add centralized version manifest for Docker builds

[mritunjaysharma394]

Purpose

Introduces docker/versions.json as a centralized, machine-readable version manifest for all pinned dependencies in Docker builds.

Problem

Version information is currently scattered across docker/Dockerfile and various install scripts, making it hard to:

• Track version changes across releases
• Programmatically query versions for CI/tooling
• Maintain consistency

Solution

A single docker/versions.json file structured to support both human readers and tooling.

Integration with Docker Bake (#31477)

This PR is designed to complement the docker buildx bake work in #31477:

This PR	Bake PR #31477
versions.json = version data	docker-bake.hcl = build config
What versions to use	How to build

Structure for Bake Compatibility

{
  "docker": {
    "build_args": {
      "CUDA_VERSION": "12.9.1",
      "PYTHON_VERSION": "3.12",
      "TORCH_CUDA_ARCH_LIST": "7.0 7.5 8.0 8.9 9.0 10.0 12.0",
      "FLASHINFER_VERSION": "0.5.3",
      ...
    },
    "build_config": {
      "max_jobs": 16,
      "nvcc_threads": 8
    }
  }
}

• docker.build_args: Flat map matching Dockerfile ARGs exactly - easy for bake to consume
• docker.build_config: Build parallelism settings matching bake variables

Usage with Bake

# Extract build args for bake
CUDA=$(jq -r '.docker.build_args.CUDA_VERSION' docker/versions.json)
MAX_JOBS=$(jq -r '.docker.build_config.max_jobs' docker/versions.json)

# Or generate all args
jq -r '.docker.build_args | to_entries | .[] | "--set *.args.\(.key)=\(.value)"' docker/versions.json

Benefits

1. Single Source of Truth: All versions in one JSON file
2. Bake-Ready: docker.build_args maps directly to Dockerfile ARGs
3. Machine-Readable: Easy to parse with jq for CI and external tooling
4. Cleaner Diffs: Version bumps show as clear JSON changes
5. Release Comparison: git diff v0.13.0..v0.14.0 -- docker/versions.json

Files Changed

• docker/versions.json - New version manifest with bake-compatible structure
• docker/Dockerfile - Added comments pointing to versions.json

Test Plan

• JSON is valid and parseable
• docker.build_args values match current Dockerfile ARG defaults
• Pre-commit checks pass

[gemini-code-assist]

Code Review

This pull request is a great step towards centralizing version management by introducing docker/versions.json. This will significantly improve maintainability and reduce errors when updating dependencies. The new scripts (build.sh, get-version.sh, validate_versions.py) are well-structured and provide useful tooling. My review includes a few suggestions to enhance correctness and consistency, particularly by fixing a bug in the build.sh script's dry-run output and addressing a critical omission in the validate_versions.py script to ensure it provides complete validation.

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

Just a reminder: PRs would not trigger full CI run by default. Instead, it would only run fastcheck CI which starts running only a small and essential subset of CI tests to quickly catch errors.

You ask your reviewers to trigger select CI tests on top of fastcheck CI.

Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

🚀

[mergify]

Hi @mritunjaysharma394, the pre-commit checks have failed. Please run:

uv pip install pre-commit
pre-commit install
pre-commit run --all-files

Then, commit the changes and push to your branch.

For future commits, pre-commit will run automatically on changed files before each commit.

Tip

Is mypy or markdownlint failing?

mypy and markdownlint are run differently in CI. If the failure is related to either of these checks, please use the following commands to run them locally:

# For mypy (substitute "3.10" with the failing version if needed)
pre-commit run --hook-stage manual mypy-3.10
# For markdownlint
pre-commit run --hook-stage manual markdownlint

[amrmahdi]

Can we standardize on bake instead of custom scripts? I started here #31477

[mritunjaysharma394]

Thanks for the review and good call! I've simplified this PR to remove all the custom scripts (build.sh, get-version.sh, validate_versions.py).

Now it just adds docker/versions.json as a machine-readable version manifest that your bake configuration in #31477 can reference for the pinned versions.

The two PRs complement each other:

• versions.json = version data (what versions to use)
• docker-bake.hcl = build config (how to build)

[mritunjaysharma394]

I've also restructured versions.json to better support your bake approach. Added a docker section with:

docker.build_args - flat map that matches Dockerfile ARGs exactly:

{
  "CUDA_VERSION": "12.9.1",
  "PYTHON_VERSION": "3.12",
  "TORCH_CUDA_ARCH_LIST": "7.0 7.5 8.0 8.9 9.0 10.0 12.0",
  "FLASHINFER_VERSION": "0.5.3",
  ...
}

docker.build_config - build settings that match your bake variables:

{
  "max_jobs": 16,
  "nvcc_threads": 8
}

This makes it easy for bake to consume:

# Extract for bake
CUDA=$(jq -r '.docker.build_args.CUDA_VERSION' docker/versions.json)
MAX_JOBS=$(jq -r '.docker.build_config.max_jobs' docker/versions.json)

Or generate HCL variables directly from the JSON. Let me know if you'd like any other fields added!