Repository navigation
fix(docker): forward LAYA_REVISION so a Compose deployment can actually pin - #715
Merged
NandhaKishorM merged 1 commit intoSep 29, 2026
Merged
Conversation
…ly pin
`docs/docker.md` documents `LAYA_REVISION` in the shared variable table, `laya/revisions.py:51`
reads it, and no Compose file named it. Compose only puts a host variable into a container when
the variable appears in that service's `environment:` block, so:
$ printf 'LAYA_REVISION=reviewed\n' > .env
$ docker compose run --rm laya
interpolated the host value, warned about nothing, and started the container without it.
`resolve_revision` then returned `None`, `huggingface_hub` applied its default revision, and
every checkpoint loaded at whatever the mutable default branch or the warm cache held.
This is not one knob among several. `laya/revisions.py:12` gives the reason the variable exists
at all -- "so a container pins" -- and `examples/docker/quickstart.py:27` builds
`Router(device=device)` with no `revision=` argument, so in the container this repo ships the
environment variable is the *only* way to pin. `reviewed` is a supported sentinel resolving to
`PINNED_REVISIONS`. A supply-chain control the shipped deployment silently discards is the
failure mode the control exists to prevent.
`compose.yaml` forwards it, with an empty default so a deployment that never mentions it behaves
exactly as it did before.
## The gate that should have caught this, widened
`tests/test_compose_env.py` exists for precisely this class of drift. Its own docstring says the
method is derived rather than transcribed because "the same three-way drift (package, markdown,
Compose) is what hid them". But `dtype_names()` derives from `laya/agent.py` only, and only within
a few lines of a dtype decision -- which is right for the contract it was written for, and blind to
a name read by any other module. `LAYA_REVISION` is read by `laya/revisions.py`, so it fell
straight through.
The derivation is now widened to every `LAYA_*` the package reads, and the three-way agreement is
checked in both directions:
- every name the runtime reads and the page documents, minus the documented exclusions, is
forwarded by at least one Compose file, as a `"${NAME:-...}"` host passthrough;
- every name a Compose file forwards has a row in the table, so a knob cannot be set by the
deployment and missing from the page.
Granularity is "at least one file", not per-service, because per-service would be wrong the other
way: `LAYA_PORT` belongs to `laya-serve` and must not be demanded of the SDK service.
Two findings from writing the widened check, both resolved rather than papered over:
- `LAYA_THREADS` is `"${LAYA_THREADS:-${OMP_NUM_THREADS:-4}}"` -- a nested default, and still a
host passthrough. The first version of the check rejected it, so the check was wrong, not the
compose file.
- `LAYA_API_KEY_FILE` looked undocumented because the row is a combined
`` `LAYA_API_KEY` / `LAYA_API_KEY_FILE` `` cell. It is documented, in a table and in prose at
`docs/docker.md:259`. The extraction was too narrow; widening it avoids demanding a duplicate row
for a variable that already has one.
## Deliberately not fixed here
`LAYA_MAX_CONCURRENT` and `LAYA_MAX_TOKEN_BUDGET` are the same defect -- both documented in the
`laya-serve` table, both read by `laya/serve.py`, neither forwarded by any file -- and they are
NOT fixed by this change. `compose.http.yaml` is the only place they could be forwarded, and three
open PRs conflict on it: NandhaKishorM#528 and NandhaKishorM#656 insert at the `laya-serve` environment block, and NandhaKishorM#528 is
itself adding `LAYA_SHA256_DIGESTS` to that block, so the serve-side forwarding belongs with
whoever lands that cluster. A first draft of this change did edit that file and conflicted with
all three, which is what settled the scope.
They are pinned in the test as a `DEFERRED` literal and re-asserted to still be read and still
documented, the same way check 5 pins the MPS exclusion. The day those PRs close, the file fails
and the decision gets made again rather than the two names quietly staying missing.
```
python tests/test_compose_env.py 80 passed, 0 failed (was 78)
python tests/test_packaging.py 106 passed, 0 failed
python tests/test_doc_tables.py 109 passed, 0 failed
python -m compileall -q laya tests
ruff check tests/test_compose_env.py --select=E9,F63,F7,F82,F401,F811 --line-length=120
git diff --check
```
Reverting only `compose.yaml` turns the new check red, naming the variable:
`compose/at least one file forwards LAYA_REVISION`.
Not run: the `docker compose config` render check, because docker is not installed here. The file
reports that as a `NOTE` and never as a pass, so the rendered-environment half of this is
unverified by execution. `tests/test_env_docs.py` fails 1 of 9 on Windows for an unrelated
pre-existing reason (a hard-coded `/` compared against `os.path.relpath`); it fails identically on
unmodified `9d955671`.
Owner
|
Passed checks and merged. Thank you @Bruce-Yii! It ships in 0.3.22. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
fix(docker): forward LAYA_REVISION so a Compose deployment can actually pin
docs/docker.mddocumentsLAYA_REVISIONin the shared variable table,laya/revisions.py:51reads it, and no Compose file named it. Compose only puts a host variable into a container when
the variable appears in that service's
environment:block, so:interpolated the host value, warned about nothing, and started the container without it.
resolve_revisionthen returnedNone,huggingface_hubapplied its default revision, andevery checkpoint loaded at whatever the mutable default branch or the warm cache held.
This is not one knob among several.
laya/revisions.py:12gives the reason the variable existsat all -- "so a container pins" -- and
examples/docker/quickstart.py:27buildsRouter(device=device)with norevision=argument, so in the container this repo ships theenvironment variable is the only way to pin.
reviewedis a supported sentinel resolving toPINNED_REVISIONS. A supply-chain control the shipped deployment silently discards is thefailure mode the control exists to prevent.
compose.yamlforwards it, with an empty default so a deployment that never mentions it behavesexactly as it did before.
The gate that should have caught this, widened
tests/test_compose_env.pyexists for precisely this class of drift. Its own docstring says themethod is derived rather than transcribed because "the same three-way drift (package, markdown,
Compose) is what hid them". But
dtype_names()derives fromlaya/agent.pyonly, and only withina few lines of a dtype decision -- which is right for the contract it was written for, and blind to
a name read by any other module.
LAYA_REVISIONis read bylaya/revisions.py, so it fellstraight through.
The derivation is now widened to every
LAYA_*the package reads, and the three-way agreement ischecked in both directions:
forwarded by at least one Compose file, as a
"${NAME:-...}"host passthrough;deployment and missing from the page.
Granularity is "at least one file", not per-service, because per-service would be wrong the other
way:
LAYA_PORTbelongs tolaya-serveand must not be demanded of the SDK service.Two findings from writing the widened check, both resolved rather than papered over:
LAYA_THREADSis"${LAYA_THREADS:-${OMP_NUM_THREADS:-4}}"-- a nested default, and still ahost passthrough. The first version of the check rejected it, so the check was wrong, not the
compose file.
LAYA_API_KEY_FILElooked undocumented because the row is a combined`LAYA_API_KEY` / `LAYA_API_KEY_FILE`cell. It is documented, in a table and in prose atdocs/docker.md:259. The extraction was too narrow; widening it avoids demanding a duplicate rowfor a variable that already has one.
Deliberately not fixed here
LAYA_MAX_CONCURRENTandLAYA_MAX_TOKEN_BUDGETare the same defect -- both documented in thelaya-servetable, both read bylaya/serve.py, neither forwarded by any file -- and they areNOT fixed by this change.
compose.http.yamlis the only place they could be forwarded, and threeopen PRs conflict on it: #528 and #656 insert at the
laya-serveenvironment block, and #528 isitself adding
LAYA_SHA256_DIGESTSto that block, so the serve-side forwarding belongs withwhoever lands that cluster. A first draft of this change did edit that file and conflicted with
all three, which is what settled the scope.
They are pinned in the test as a
DEFERREDliteral and re-asserted to still be read and stilldocumented, the same way check 5 pins the MPS exclusion. The day those PRs close, the file fails
and the decision gets made again rather than the two names quietly staying missing.
Reverting only
compose.yamlturns the new check red, naming the variable:compose/at least one file forwards LAYA_REVISION.Not run: the
docker compose configrender check, because docker is not installed here. The filereports that as a
NOTEand never as a pass, so the rendered-environment half of this isunverified by execution.
tests/test_env_docs.pyfails 1 of 9 on Windows for an unrelatedpre-existing reason (a hard-coded
/compared againstos.path.relpath); it fails identically onunmodified
9d955671.