docs(docker): document the locked PyPI index requirement by Winoren · Pull Request #7011 · bytedance/deer-flow

Winoren · 2026-10-17T05:40:30Z

Why

The README recommends setting UV_INDEX_URL to a PyPI mirror for Docker builds. The gateway builder installs with uv sync --locked, while the committed lock records https://pypi.org/simple. Changing the index makes uv require a lock update, so following the documented mirror suggestion breaks the build.

What changed

Replace the mirror recommendation in the English, Portuguese and Korean READMEs with the pinned-index constraint and a reproduction command.
Add the same constraint to CONTRIBUTING.md, which already shows the working PyPI value.
Explain that NPM_REGISTRY configures the frontend independently.

No Dockerfile, dependency or lockfile changes.

Surface area

Docs / tests / CI only — no runtime behavior change

Validation

On upstream main 169002a4c995881ae046f34a540bb83b6ac828d6 plus this documentation commit, using uv 0.10.11 / CPython 3.12.13:

cd backend && UV_INDEX_URL=https://pypi.org/simple uv lock --check — exit 0, 251 packages resolved.
The same command with UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple — exit 1, lockfile needs updating because --check was provided.
Confirmed backend/Dockerfile invokes uv sync --locked and the committed lock uses the PyPI registry; uv.lock remained byte-identical during validation.
git diff --check origin/main HEAD — passed; only the four documentation files differ.

A full Docker build was not run. Runtime tests were not run for this documentation-only change.

AI assistance

Tool(s) used: Codex.

How you used it: AI-assisted documentation preparation and read-only verification of the index/lock mismatch, duplicate search and PR preparation. This draft continues an existing contributor branch previously linked from #7003.

I've read and understand every line of this change and take responsibility for it — it's not unreviewed AI output.

Draft pending the contributor's final human review and completion of the checkbox above.

willem-bd

Verified the locked-index documentation against head fbb9616: backend/Dockerfile line 74 does run uv sync --locked, every registry source in backend/uv.lock is https://pypi.org/simple, and the quoted The lockfile at uv.lockneeds to be updated, but--locked was provided error reproduces exactly when a mirror index is exported (checked with uv 0.11.19). The core guidance is accurate and a useful fix. One factual correction, repeated in all three READMEs: NPM_REGISTRY is not frontend-only - the gateway build also consumes it for the npm-installed Lark CLI.

willem-bd · 2026-10-17T11:43:24Z

 `make docker-start` starts `provisioner` only when `config.yaml` uses provisioner mode (`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider` with `provisioner_url`).

-Docker builds use the upstream `uv` registry by default. If you need faster mirrors in restricted networks, export `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple` and `NPM_REGISTRY=https://registry.npmmirror.com` before running `make docker-init` or `make docker-start`.
+Docker builds use the upstream `uv` registry by default. The gateway image installs with `uv sync --locked`, and `uv.lock` pins `https://pypi.org/simple`, so `UV_INDEX_URL` has to keep that value: exporting a mirror such as `https://pypi.tuna.tsinghua.edu.cn/simple` fails the build with ``The lockfile at `uv.lock` needs to be updated, but `--locked` was provided`` (reproduce with `cd backend && UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync --locked --check`). Installing from a mirror requires regenerating the lock or dropping `--locked`, and both change what the image installs, so keep the default index for a checkout you intend to contribute back. `NPM_REGISTRY=https://registry.npmmirror.com` is independent of this and applies to the frontend image only.


The closing claim is inaccurate: NPM_REGISTRY is not frontend-only. The gateway build consumes it too - docker/docker-compose.yaml (line 117) and docker/docker-compose-dev.yaml (line 189) both pass NPM_REGISTRY to the gateway build args, and backend/Dockerfile declares ARG NPM_REGISTRY and uses it at line 43 (npm config set registry "${NPM_REGISTRY}") when installing the Lark CLI (@larksuite/cli) via npm. So exporting NPM_REGISTRY=https://registry.npmmirror.com also redirects an npm install inside the gateway image, not just the frontend pnpm install. Suggest rewording along the lines of: it is independent of the uv index, and applies to the frontend image and the gateway image's Lark CLI install.

Confirmed, and I reproduced every hop in this tree rather than taking it on trust:

docker/docker-compose.yaml passes NPM_REGISTRY as a build arg to the frontend service (line 95) and to the gateway service (line 117).

docker/docker-compose-dev.yaml does the same at lines 154 and 189.

backend/Dockerfile declares ARG NPM_REGISTRY (line 16) and applies it at line 43: npm config set registry "${NPM_REGISTRY}", on the same RUN that installs @larksuite/cli.

So the mirror redirects an npm install inside the gateway image too, and frontend-only is simply wrong.

Fixed in d50eccf (README.md:486): the closing sentence now reads that NPM_REGISTRY is independent of the uv index and applies to the frontend pnpm install and to the gateway Lark CLI install, naming @larksuite/cli and backend/Dockerfile. Identical correction in README_ko.md:375 and README_pt.md:332.

willem-bd · 2026-10-17T11:43:24Z

 `make docker-start`는 `config.yaml`이 provisioner 모드(`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider`와 `provisioner_url` 사용)를 쓰는 경우에만 `provisioner`를 시작합니다.

-Docker 빌드는 기본적으로 업스트림 `uv` 레지스트리를 사용합니다. 제한된 네트워크에서 더 빠른 미러가 필요하다면 `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple`과 `NPM_REGISTRY=https://registry.npmmirror.com`을 export한 뒤 `make docker-init` 또는 `make docker-start`를 실행하세요.
+Docker 빌드는 기본적으로 업스트림 `uv` 레지스트리를 사용합니다. 게이트웨이 이미지는 `uv sync --locked`로 설치하고 `uv.lock`은 `https://pypi.org/simple`를 고정하므로, `UV_INDEX_URL`은 이 값을 유지해야 합니다. `https://pypi.tuna.tsinghua.edu.cn/simple` 같은 미러를 export하면 ``The lockfile at `uv.lock` needs to be updated, but `--locked` was provided`` 오류로 빌드가 실패합니다(`cd backend && UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync --locked --check`로 재현 가능). 미러에서 설치하려면 lock을 다시 생성하거나 `--locked`를 제거해야 하며, 둘 다 이미지에 설치되는 내용이 달라지므로 기여할 체크아웃에서는 기본 인덱스를 유지하세요. `NPM_REGISTRY=https://registry.npmmirror.com`은 이와 무관하며 프론트엔드 이미지에만 적용됩니다.


The closing claim is inaccurate: NPM_REGISTRY is not frontend-only. The gateway build consumes it too - docker/docker-compose.yaml (line 117) and docker/docker-compose-dev.yaml (line 189) both pass NPM_REGISTRY to the gateway build args, and backend/Dockerfile declares ARG NPM_REGISTRY and uses it at line 43 (npm config set registry "${NPM_REGISTRY}") when installing the Lark CLI (@larksuite/cli) via npm. So exporting NPM_REGISTRY=https://registry.npmmirror.com also redirects an npm install inside the gateway image, not just the frontend pnpm install. Suggest rewording along the lines of: it is independent of the uv index, and applies to the frontend image and the gateway image's Lark CLI install.

Confirmed and verified in this tree (docker-compose.yaml lines 95 and 117, docker-compose-dev.yaml lines 154 and 189, backend/Dockerfile ARG at line 16 applied at line 43 for the @larksuite/cli install): NPM_REGISTRY reaches the gateway build as well, so frontend-only was wrong.

Fixed in d50eccf (README_ko.md:375): the sentence now says NPM_REGISTRY is independent of the uv index and applies to the frontend pnpm install and to the gateway Lark CLI install, naming @larksuite/cli and backend/Dockerfile. Same correction applied to README.md:486 and README_pt.md:332.

willem-bd · 2026-10-17T11:43:24Z

 O `make docker-start` só inicia o `provisioner` quando o `config.yaml` usa o modo provisioner (`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider` com `provisioner_url`).

-Os builds do Docker usam o registry upstream do `uv` por padrão. Se você precisa de mirrors mais rápidos em redes restritas, exporte `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple` e `NPM_REGISTRY=https://registry.npmmirror.com` antes de rodar `make docker-init` ou `make docker-start`.
+Os builds do Docker usam o registry upstream do `uv` por padrão. A imagem do gateway instala com `uv sync --locked` e o `uv.lock` fixa `https://pypi.org/simple`, portanto `UV_INDEX_URL` precisa manter esse valor: exportar um mirror como `https://pypi.tuna.tsinghua.edu.cn/simple` faz o build falhar com ``The lockfile at `uv.lock` needs to be updated, but `--locked` was provided`` (reproduza com `cd backend && UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync --locked --check`). Instalar a partir de um mirror exige regerar o lock ou remover `--locked`, e as duas opções mudam o que a imagem instala, então mantenha o índice padrão em um checkout que você pretende contribuir de volta. `NPM_REGISTRY=https://registry.npmmirror.com` é independente disso e se aplica apenas à imagem do frontend.


The closing claim is inaccurate: NPM_REGISTRY is not frontend-only. The gateway build consumes it too - docker/docker-compose.yaml (line 117) and docker/docker-compose-dev.yaml (line 189) both pass NPM_REGISTRY to the gateway build args, and backend/Dockerfile declares ARG NPM_REGISTRY and uses it at line 43 (npm config set registry "${NPM_REGISTRY}") when installing the Lark CLI (@larksuite/cli) via npm. So exporting NPM_REGISTRY=https://registry.npmmirror.com also redirects an npm install inside the gateway image, not just the frontend pnpm install. Suggest rewording along the lines of: it is independent of the uv index, and applies to the frontend image and the gateway image's Lark CLI install.

Confirmed and verified in this tree (docker-compose.yaml lines 95 and 117, docker-compose-dev.yaml lines 154 and 189, backend/Dockerfile ARG at line 16 applied at line 43 for the @larksuite/cli install): NPM_REGISTRY reaches the gateway build as well, so frontend-only was wrong.

Fixed in d50eccf (README_pt.md:332): the sentence now says NPM_REGISTRY is independent of the uv index and applies to the frontend pnpm install and to the gateway Lark CLI install, naming @larksuite/cli and backend/Dockerfile. Same correction applied to README.md:486 and README_ko.md:375.

The README told users on restricted networks to export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple, but the gateway image installs with `uv sync --locked` and uv.lock is locked to https://pypi.org/simple, so any other index fails the build with "The lockfile at `uv.lock` needs to be updated, but `--locked` was provided" (bytedance#7003). Document the constraint instead of the mirror: name the pinned index, quote the exact failure, and note that installing from a mirror requires regenerating the lock or dropping --locked. CONTRIBUTING.md already showed the working value and gains the same note, and README_pt.md and README_ko.md carried the same sentence and are updated to match.

NPM_REGISTRY is not frontend-only: the gateway build also consumes it. docker/docker-compose.yaml (lines 95 and 117) and docker/docker-compose-dev.yaml (lines 154 and 189) pass it as a build arg to both the frontend and the gateway image, and backend/Dockerfile declares ARG NPM_REGISTRY (line 16) and applies it via npm config set registry (line 43) for the @larksuite/cli install. While re-verifying the uv repro on this head, also found that the quoted uv sync --locked --check only discriminates between indexes when the local environment is already in sync; if the environment is stale it reports the stale environment for either index. Point at uv lock --check for that case. Reported-by: willem-bd

Winoren · 2026-10-17T16:08:51Z

Both items are addressed in d50eccf (branch rebased onto main 7e22e42; still 4 files, +5/-3).

NPM_REGISTRY scope (your finding). Verified all three hops myself rather than taking it on trust: docker/docker-compose.yaml passes NPM_REGISTRY to the frontend service (line 95) and the gateway service (line 117); docker-compose-dev.yaml does so at 154 and 189; backend/Dockerfile declares ARG NPM_REGISTRY (line 16) and applies it at line 43 with npm config set registry on the same RUN that installs @larksuite/cli. All three READMEs now say it is independent of the uv index and applies to the frontend pnpm install and to the gateway Lark CLI install. Replied on each thread.
A caveat in my own repro line (found while re-verifying). The quoted command does not always discriminate. uv sync --locked --check evaluates the installed environment first, so if the environment is stale it prints The environment is outdated for BOTH indexes and never reaches the registry comparison. Demonstrated by uninstalling one locked package: with default index and with the mirror, both report the stale environment. After uv sync --locked restores the environment, the same two commands behave as documented in the README (default: Would make no changes; mirror: the lockfile needs to be updated). uv lock --check reports the same staleness without depending on the installed environment, so I pointed at that as the fallback. The three READMEs now say to run it in an already-synced environment and mention uv lock --check otherwise.

Re-verified on this head that the core claim still holds: backend/uv.lock has 248 registry entries, all https://pypi.org/simple, and backend/Dockerfile line 74 still runs uv sync --locked with UV_INDEX_URL honoured.

Happy to drop item 2 if you would rather keep this PR to the single factual correction.

willem-bd reviewed Oct 17, 2026

View reviewed changes

D41910 added 2 commits October 18, 2026 00:02

Winoren force-pushed the docs/uv-index-url-locked-build branch from fbb9616 to d50eccf Compare October 17, 2026 16:06

Winoren marked this pull request as ready for review October 17, 2026 18:12

github-actions Bot added area:docs Documentation and Markdown only risk:low Low risk: docs / i18n / assets only size/XS PR changes < 20 lines labels Oct 17, 2026

WillemJiang approved these changes Oct 18, 2026

View reviewed changes

WillemJiang merged commit e1f20a6 into bytedance:main Oct 18, 2026
21 of 27 checks passed

Navigation Menu

Repository navigation

docs(docker): document the locked PyPI index requirement - #7011

docs(docker): document the locked PyPI index requirement#7011
WillemJiang merged 2 commits into
bytedance:mainfrom
Winoren:docs/uv-index-url-locked-build

Winoren commented Oct 17, 2026

Uh oh!

willem-bd left a comment

Uh oh!

willem-bd Oct 17, 2026

Uh oh!

Winoren Oct 17, 2026

Uh oh!

willem-bd Oct 17, 2026

Uh oh!

Winoren Oct 17, 2026

Uh oh!

willem-bd Oct 17, 2026

Uh oh!

Winoren Oct 17, 2026

Uh oh!

Winoren commented Oct 17, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Winoren commented Oct 17, 2026

Why

What changed

Surface area

Validation

AI assistance

Uh oh!

willem-bd left a comment

Choose a reason for hiding this comment

Uh oh!

willem-bd Oct 17, 2026

Choose a reason for hiding this comment

Uh oh!

Winoren Oct 17, 2026

Choose a reason for hiding this comment

Uh oh!

willem-bd Oct 17, 2026

Choose a reason for hiding this comment

Uh oh!

Winoren Oct 17, 2026

Choose a reason for hiding this comment

Uh oh!

willem-bd Oct 17, 2026

Choose a reason for hiding this comment

Uh oh!

Winoren Oct 17, 2026

Choose a reason for hiding this comment

Uh oh!

Winoren commented Oct 17, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants