Skip to content

fix(docker): forward LAYA_REVISION so a Compose deployment can actually pin - #715

Merged
NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
Bruce-Yii:fix/compose-forward-revision
Sep 29, 2026
Merged

NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
Bruce-Yii:fix/compose-forward-revision

Conversation

@Bruce-Yii

Copy link
Copy Markdown
Contributor

fix(docker): forward LAYA_REVISION so a Compose deployment can actually 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: #528 and #656 insert at the laya-serve environment block, and #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.

…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`.
@NandhaKishorM
NandhaKishorM merged commit 0714b5a into NandhaKishorM:main Sep 29, 2026
20 of 21 checks passed
@NandhaKishorM

Copy link
Copy Markdown
Owner

Passed checks and merged. Thank you @Bruce-Yii! It ships in 0.3.22.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants