Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Docker ROCm Studio image: ship JupyterLab with the notebooks, as the CUDA image does (#11286)

Leo Borcherdingb19b41bcab2f
diff --git a/.github/workflows/docker-publish-rocm.yml b/.github/workflows/docker-publish-rocm.yml
index 51229e45627..5aebc536e31 100644
--- a/.github/workflows/docker-publish-rocm.yml
+++ b/.github/workflows/docker-publish-rocm.yml
@@ -1,6 +1,6 @@
# Builds and publishes the AMD ROCm Unsloth Docker images: the training base
-# (docker/Dockerfile.rocm, :latest) and Studio on top of it
-# (docker/Dockerfile.studio-rocm, :studio).
+# (docker/Dockerfile.rocm, :latest) and Studio, JupyterLab and the notebooks on
+# top of it (docker/Dockerfile.studio-rocm, :studio).
#
# No GPU runner needed: the ROCm torch wheels do not probe a device at install
# time, and the build-time check reads torch.version.hip, a constant baked into
@@ -33,6 +33,10 @@ on:
description: 'unsloth-zoo git ref to bake in'
required: false
default: 'main'
+ notebooks_ref:
+ description: 'unslothai/notebooks git ref to bake into :studio (resolved to one commit)'
+ required: false
+ default: 'main'
rocm_version:
description: 'ROCm base image version (blank = the Dockerfile default, 7.2.4)'
required: false
@@ -81,6 +85,7 @@ jobs:
outputs:
unsloth_ref: ${{ steps.unsloth_ref.outputs.ref }}
zoo_ref: ${{ steps.zoo_ref.outputs.ref }}
+ notebooks_commit: ${{ steps.notebooks.outputs.commit }}
rocm_version: ${{ steps.build_args.outputs.rocm_version }}
torch_index_url: ${{ steps.build_args.outputs.torch_index_url }}
rocm_gfx: ${{ steps.build_args.outputs.rocm_gfx }}
@@ -154,6 +159,28 @@ jobs:
echo "ref=${SHA}" >> "$GITHUB_OUTPUT"
echo "unsloth-zoo ref: ${SHA}"
+ # One commit for the notebooks the Studio image bakes, as docker-publish.yml
+ # does: the layer is keyed on this string, so a mutable "main" would be a
+ # cache hit on a later run and ship the old set under a new digest.
+ - name: Resolve unsloth/notebooks commit
+ id: notebooks
+ env:
+ INPUT_REF: ${{ github.event.inputs.notebooks_ref }}
+ run: |
+ REF="${INPUT_REF:-main}"
+ if printf '%s' "$REF" | grep -Eq '^[0-9a-f]{40}$'; then
+ SHA="$REF"
+ else
+ if ! LS_OUT="$(git ls-remote https://github.com/unslothai/notebooks "$REF")"; then
+ echo "::error::unslothai/notebooks unreachable; cannot freeze ref '${REF}' to a sha"
+ exit 1
+ fi
+ SHA="$(printf '%s\n' "$LS_OUT" | awk 'NR==1{print $1}')"
+ [ -n "$SHA" ] || SHA="$REF"
+ fi
+ echo "commit=${SHA}" >> "$GITHUB_OUTPUT"
+ echo "notebooks commit: ${SHA}"
+
# :latest and the release tags name the DEFAULT build. A dispatch that
# changed any input (an older ROCm, another index, a per-arch build) gets
# SHA tags only, so it can never overwrite what `docker pull` hands out.
@@ -162,6 +189,7 @@ jobs:
env:
IN_UNSLOTH: ${{ github.event.inputs.unsloth_ref }}
IN_ZOO: ${{ github.event.inputs.unsloth_zoo_ref }}
+ IN_NOTEBOOKS: ${{ github.event.inputs.notebooks_ref }}
IN_ROCM: ${{ github.event.inputs.rocm_version }}
IN_INDEX: ${{ github.event.inputs.torch_index_url }}
IN_GFX: ${{ github.event.inputs.rocm_gfx }}
@@ -196,6 +224,7 @@ jobs:
DEFAULTS=true
[ -z "$IN_UNSLOTH" ] || DEFAULTS=false
case "$IN_ZOO" in ""|main) ;; *) DEFAULTS=false ;; esac
+ case "$IN_NOTEBOOKS" in ""|main) ;; *) DEFAULTS=false ;; esac
[ "$ROCM" = "$DEF_ROCM" ] || DEFAULTS=false
[ "$INDEX" = "$DEF_INDEX" ] || DEFAULTS=false
STABLE=$DEFAULTS
@@ -269,13 +298,62 @@ jobs:
UNSLOTH_REF=${{ needs.prepare.outputs.unsloth_ref }}
UNSLOTH_ZOO_REF=${{ needs.prepare.outputs.zoo_ref }}
+ # Attach human-readable tags to the digest pushed above. Only once the Studio
+ # build has its digest too: the Hub page promises every base tag a -studio twin
+ # on the same base, and a :latest that moved while the Studio build then failed
+ # would leave :studio on the previous base. Both digests exist before either tag
+ # moves, and the two tag jobs then run back to back in the same run.
+ tag:
+ runs-on: ubuntu-latest
+ needs: [prepare, build, build-studio]
+ timeout-minutes: 15
+ outputs:
+ tags: ${{ steps.meta.outputs.tags }}
+ steps:
+ - uses: docker/setup-buildx-action@v3
+
+ - name: Log in to Docker Hub
+ uses: docker/login-action@v4
+ with:
+ username: ${{ env.REGISTRY_USERNAME }}
+ password: ${{ secrets.DOCKER_API_KEY }}
+
+ - name: Resolve tags
+ id: meta
+ uses: docker/metadata-action@v6
+ with:
+ images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+ # latest: a default-input build of the default branch (schedule or dispatch).
+ # A per-arch build gets its gfx in the tag so it is findable, never latest.
+ # An override build's sha tag carries the run id: two experiments at the same
+ # commit would otherwise overwrite each other's only name.
+ tags: |
+ type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && needs.prepare.outputs.stable == 'true' }}
+ type=ref,event=tag,enable=${{ needs.prepare.outputs.stable == 'true' }}
+ type=schedule,pattern=nightly,enable=${{ needs.prepare.outputs.stable == 'true' }}
+ type=raw,value=${{ needs.prepare.outputs.rocm_gfx }},enable=${{ needs.prepare.outputs.gfx_tag == 'true' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+ type=sha,prefix=sha-,format=short,suffix=${{ needs.prepare.outputs.rocm_gfx != '' && format('-{0}', needs.prepare.outputs.rocm_gfx) || '' }}${{ needs.prepare.outputs.stable != 'true' && format('-r{0}', github.run_id) || '' }}
+
+ - name: Create manifest
+ env:
+ DIGEST: ${{ needs.build.outputs.digest }}
+ run: |
+ TAG_FLAGS=()
+ while IFS= read -r t; do TAG_FLAGS+=(-t "$t"); done < <(jq -r '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON")
+ docker buildx imagetools create "${TAG_FLAGS[@]}" "${REGISTRY}/${IMAGE_NAME}@${DIGEST}"
+
+ - name: Inspect the result
+ run: |
+ for tag in $(jq -r '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON"); do
+ echo "=== $tag ==="
+ docker buildx imagetools inspect "$tag"
+ done
+
# Studio on the base this run pushed (docker/Dockerfile.studio-rocm), the ROCm
# half of docker-publish.yml's build-studio. The base by DIGEST, not by tag:
# :latest can already be a newer run's by the time this job starts. The Studio
# refs are the ones the base baked, so both venvs run the same commit even if
- # upstream moved mid-run. Before tag: no stable tag moves until both digests
- # exist, so :latest and :studio always come from one run (unlike the CUDA
- # workflow, where :core moves before its Studio build starts).
+ # upstream moved mid-run. Before tag, which waits on this job's digest (see there).
build-studio:
needs: [prepare, build]
runs-on: ubuntu-latest
@@ -329,6 +407,7 @@ jobs:
BASE_IMAGE=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.build.outputs.digest }}
UNSLOTH_STUDIO_REF=${{ needs.prepare.outputs.unsloth_ref }}
UNSLOTH_STUDIO_ZOO_REF=${{ needs.prepare.outputs.zoo_ref }}
+ UNSLOTH_NOTEBOOKS_REF=${{ needs.prepare.outputs.notebooks_commit }}
# The Dockerfile hands install.sh UNSLOTH_ALLOW_CPU=1 for the GPU-less build
# only. Image-wide it would reach every process and turn off Unsloth's TRL
@@ -343,13 +422,13 @@ jobs:
echo "$ENV_JSON" | jq -e 'map(select(startswith("UNSLOTH_ALLOW_CPU="))) | length == 0' >/dev/null \
|| { echo "::error::Studio image env carries UNSLOTH_ALLOW_CPU, which disables Unsloth's TRL patches on GPU hosts"; exit 1; }
- # Attach human-readable tags to the digest pushed above.
- tag:
+ # The base's tag rules, each with a -studio leaf and the same gates: :studio
+ # beside :latest, v1.2.3-studio, nightly-studio, gfx1151-studio, sha-<commit>-studio.
+ # After tag, so a :studio never points past its :latest.
+ tag-studio:
runs-on: ubuntu-latest
- needs: [prepare, build, build-studio]
+ needs: [prepare, build-studio, tag]
timeout-minutes: 15
- outputs:
- tags: ${{ steps.meta.outputs.tags }}
steps:
- uses: docker/setup-buildx-action@v3
@@ -364,42 +443,8 @@ jobs:
uses: docker/metadata-action@v6
with:
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
- # latest: a default-input build of the default branch (schedule or dispatch).
- # A per-arch build gets its gfx in the tag so it is findable, never latest.
- # An override build's sha tag carries the run id: two experiments at the same
- # commit would otherwise overwrite each other's only name.
- tags: |
- type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && needs.prepare.outputs.stable == 'true' }}
- type=ref,event=tag,enable=${{ needs.prepare.outputs.stable == 'true' }}
- type=schedule,pattern=nightly,enable=${{ needs.prepare.outputs.stable == 'true' }}
- type=raw,value=${{ needs.prepare.outputs.rocm_gfx }},enable=${{ needs.prepare.outputs.gfx_tag == 'true' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
- type=sha,prefix=sha-,format=short,suffix=${{ needs.prepare.outputs.rocm_gfx != '' && format('-{0}', needs.prepare.outputs.rocm_gfx) || '' }}${{ needs.prepare.outputs.stable != 'true' && format('-r{0}', github.run_id) || '' }}
-
- - name: Create manifest
- env:
- DIGEST: ${{ needs.build.outputs.digest }}
- run: |
- TAG_FLAGS=()
- while IFS= read -r t; do TAG_FLAGS+=(-t "$t"); done < <(jq -r '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON")
- docker buildx imagetools create "${TAG_FLAGS[@]}" "${REGISTRY}/${IMAGE_NAME}@${DIGEST}"
-
- - name: Inspect the result
- run: |
- for tag in $(jq -r '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON"); do
- echo "=== $tag ==="
- docker buildx imagetools inspect "$tag"
- done
-
- # The same rules with a -studio leaf, in this job and right after the base's:
- # a second job could be scheduled with another run's tag job in between, and
- # the twins would then come from different builds. format(), not a bare
- # ${{ }}-studio: the raw gfx line above is matched by name in
- # tests/python/test_docker_rocm.py and must stay unique.
- - name: Resolve Studio tags
- id: meta_studio
- uses: docker/metadata-action@v6
- with:
- images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+ # format(), not a bare ${{ }}-studio: the raw gfx line is matched by name
+ # in tests/python/test_docker_rocm.py and must stay unique to the base.
tags: |
type=raw,value=studio,enable=${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && needs.prepare.outputs.stable == 'true' }}
type=ref,event=tag,suffix=-studio,enable=${{ needs.prepare.outputs.stable == 'true' }}
@@ -407,20 +452,17 @@ jobs:
type=raw,value=${{ format('{0}-studio', needs.prepare.outputs.rocm_gfx) }},enable=${{ needs.prepare.outputs.gfx_tag == 'true' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
type=sha,prefix=sha-,format=short,suffix=${{ needs.prepare.outputs.rocm_gfx != '' && format('-{0}', needs.prepare.outputs.rocm_gfx) || '' }}${{ needs.prepare.outputs.stable != 'true' && format('-r{0}', github.run_id) || '' }}-studio
- - name: Create Studio manifest
+ - name: Create manifest
env:
DIGEST: ${{ needs.build-studio.outputs.digest }}
- TAGS_JSON: ${{ steps.meta_studio.outputs.json }}
run: |
TAG_FLAGS=()
- while IFS= read -r t; do TAG_FLAGS+=(-t "$t"); done < <(jq -r '.tags[]' <<<"$TAGS_JSON")
+ while IFS= read -r t; do TAG_FLAGS+=(-t "$t"); done < <(jq -r '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON")
docker buildx imagetools create "${TAG_FLAGS[@]}" "${REGISTRY}/${IMAGE_NAME}@${DIGEST}"
- - name: Inspect the Studio result
- env:
- TAGS_JSON: ${{ steps.meta_studio.outputs.json }}
+ - name: Inspect the result
run: |
- for tag in $(jq -r '.tags[]' <<<"$TAGS_JSON"); do
+ for tag in $(jq -r '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON"); do
echo "=== $tag ==="
docker buildx imagetools inspect "$tag"
done
@@ -438,7 +480,8 @@ jobs:
# prepare as well as tag: the `if` reads needs.prepare.outputs.stable, and a
# job not listed in needs is simply absent from the context, which would make
# the condition silently false and the page never update.
- needs: [prepare, tag]
+ # tag-studio too: the page describes both images, so it moves once both did.
+ needs: [prepare, tag, tag-studio]
if: ${{ github.ref == format('refs/heads/{0}', github.event.repository.default_branch) && needs.prepare.outputs.stable == 'true' }}
runs-on: ubuntu-latest
timeout-minutes: 5
diff --git a/docker/DOCKERHUB-ROCM.md b/docker/DOCKERHUB-ROCM.md
index a0610c8a611..fff7289cf55 100644
--- a/docker/DOCKERHUB-ROCM.md
+++ b/docker/DOCKERHUB-ROCM.md
@@ -75,7 +75,7 @@ That runs a real 5-step LoRA on a 1B model and fails loudly if the GPU is not us
| `sha-<commit>` | the same image, pinned to the commit it was built from |
| `nightly` | the scheduled weekly build |
| `gfx1150`, `gfx1151`, `gfx1152`, `gfx1200`, `gfx1201` | builds using AMD's per-architecture wheels, when published |
-| `studio` | `latest` plus Unsloth Studio's web UI on port 8000, from [`docker/Dockerfile.studio-rocm`](https://github.com/unslothai/unsloth/blob/main/docker/Dockerfile.studio-rocm). The other tags above have a `-studio` twin built on the same base: `nightly-studio`, `sha-<commit>-studio`, `gfx1151-studio`; there is no `latest-studio`, `studio` is that one |
+| `studio` | `latest` plus Unsloth Studio's web UI on port 8000, JupyterLab with the Unsloth notebooks on port 8888, from [`docker/Dockerfile.studio-rocm`](https://github.com/unslothai/unsloth/blob/main/docker/Dockerfile.studio-rocm). Every tag above has a `-studio` twin built on the same base |
Pin a digest for anything reproducible. `latest` moves.
@@ -111,10 +111,10 @@ Included: PyTorch with ROCm, Unsloth, unsloth-zoo, transformers, TRL, PEFT, acce
Not included in `latest`, unlike `unsloth/unsloth`: Unsloth Studio and its web UI, JupyterLab, prebuilt llama.cpp and whisper.cpp, vLLM and xformers. `latest` is a training image.
-The `studio` tag adds Unsloth Studio and a CPU llama.cpp for GGUF chat, still without JupyterLab, whisper.cpp, vLLM or xformers. Training and the UI use the GPU; GGUF chat runs on the CPU, since a ROCm llama.cpp bundle is per-architecture and would pin the image to one card. Studio's data (accounts, chats, outputs) lives at `/opt/unsloth-studio`, so mount a volume there to keep it, with `GPU_FLAGS` set as in the quick start:
+The `studio` tag adds Unsloth Studio, JupyterLab with the Unsloth notebooks (the `AMD-*` set first) and a CPU llama.cpp for GGUF chat, still without whisper.cpp, vLLM or xformers. Training, the notebooks and the UI use the GPU; GGUF chat runs on the CPU, since a ROCm llama.cpp bundle is per-architecture and would pin the image to one card. Studio's data (accounts, chats, outputs) lives at `/opt/unsloth-studio`, so mount a volume there to keep it, with `GPU_FLAGS` set as in the quick start:
```bash
-docker run --rm $GPU_FLAGS --ipc=host -p 127.0.0.1:8000:8000 \
+docker run --rm $GPU_FLAGS --ipc=host -p 127.0.0.1:8000:8000 -p 127.0.0.1:8888:8888 \
-v unsloth-studio-rocm:/opt/unsloth-studio \
-v "$HOME/.cache/huggingface":/workspace/.cache/huggingface \
unsloth/unsloth-rocm:studio
diff --git a/docker/Dockerfile.studio-rocm b/docker/Dockerfile.studio-rocm
index f35b036ca0a..eb81e94cd90 100644
--- a/docker/Dockerfile.studio-rocm
+++ b/docker/Dockerfile.studio-rocm
@@ -1,40 +1,71 @@
-# Unsloth Studio on AMD (ROCm): the ROCm training image + Studio's web UI.
+# Unsloth Studio + JupyterLab on AMD (ROCm): the ROCm training image, Studio's web
+# UI and JupyterLab with the Unsloth notebooks, run by supervisord.
#
-# The AMD counterpart to Dockerfile.studio, which layers Studio on the CUDA core
-# image. Kept as its own file rather than a branch in that one: the CUDA build
-# bakes a CUDA llama.cpp, stages NVRTC and dedups the nvidia-* wheels against the
-# base venv, and none of those steps have a ROCm meaning.
-#
-# Not here yet, unlike unsloth/unsloth:studio: JupyterLab, sshd and supervisord.
-# The ROCm base ships no jupyterlab, so that whole chain (labextension build,
-# branding, the three-service supervisor) is a follow-up. This runs Studio alone.
+# The AMD counterpart to Dockerfile.studio, which layers the same services on the
+# CUDA core image. Kept as its own file rather than a branch in that one: the CUDA
+# build bakes a CUDA llama.cpp, stages NVRTC and dedups the nvidia-* wheels against
+# the base venv, and none of those steps have a ROCm meaning. The CUDA core image
+# also ships JupyterLab, the notebook tooling and the notebooks, so Dockerfile.studio
+# inherits them; the ROCm base ships none of that, so it is all installed here.
#
# llama.cpp is installed as the CPU bundle: the builder has no GPU, and a ROCm
# bundle is per-gfx-family, so baking one would pin this image to one arch. GGUF
-# chat therefore runs on the CPU here; training and the UI use the GPU.
+# chat therefore runs on the CPU here; training, the notebooks and the UI use the GPU.
#
# Build (on the published ROCm base, or one built from docker/Dockerfile.rocm):
# docker buildx build --build-arg BASE_IMAGE=unsloth/unsloth-rocm:latest \
# -f docker/Dockerfile.studio-rocm -t unsloth/unsloth-rocm:studio docker/
+# Pass UNSLOTH_STUDIO_REF / UNSLOTH_NOTEBOOKS_REF as commit shas for a build that
+# does not reuse a cached layer after upstream moves; docker-publish-rocm.yml does.
# Run (Linux) with the wrapper, which adds the device nodes, the NUMERIC group ids
# and the Studio volume, but publishes no port and picks :latest unless told:
-# UNSLOTH_IMAGE=unsloth/unsloth-rocm:studio UNSLOTH_PORTS="-p 127.0.0.1:8000:8000" \
+# UNSLOTH_IMAGE=unsloth/unsloth-rocm:studio \
+# UNSLOTH_PORTS="-p 127.0.0.1:8000:8000 -p 127.0.0.1:8888:8888" \
# UNSLOTH_STUDIO_VOLUME=unsloth-studio-rocm bash docker/run.sh --rocm
# or by hand (group ids as numbers: the names do not exist inside the image):
# docker run --rm --device /dev/kfd --device /dev/dri \
# --group-add "$(getent group video | cut -d: -f3)" \
# --group-add "$(getent group render | cut -d: -f3)" \
-# --ipc=host -p 127.0.0.1:8000:8000 \
+# --ipc=host -p 127.0.0.1:8000:8000 -p 127.0.0.1:8888:8888 \
+# -v $HOME/.cache/huggingface:/workspace/.cache/huggingface \
# -v unsloth-studio-rocm:/opt/unsloth-studio unsloth/unsloth-rocm:studio
# Windows/WSL2 has no /dev/kfd: the card is reached over /dev/dxg, which the
# wrapper and the entrypoint only learn in #11212. Until that lands, pass
# /dev/dxg, the host's librocdxg and HSA_ENABLE_DXG_DETECTION=1 by hand, with
# UNSLOTH_SKIP_GPU_CHECK=1 to get past the entrypoint's /dev/kfd gate.
-# UNSLOTH_STUDIO_PASSWORD sets the initial admin password, first boot only;
-# unset, Studio generates one.
+#
+# Studio on :8000 (user unsloth; UNSLOTH_STUDIO_PASSWORD env, else a generated one is
+# printed in the logs; persisted under /opt/unsloth-studio/auth/); JupyterLab on :8888
+# (JUPYTER_PASSWORD env, else a random one is printed), opening on the by-topic view
+# of the notebooks with the AMD-* set shown. No sshd: openssh-server is left out of
+# this image, so studio_launch.sh's `command -v sshd` gate never fires and the shared
+# supervisord program stays down, whatever PUBLIC_KEY / SSH_KEY is set to.
+# /opt/unsloth-studio (UNSLOTH_STUDIO_HOME) holds only Studio's data; the code
+# lives in /opt/unsloth-studio-app (UNSLOTH_STUDIO_APP) and unsloth-studio-home links
+# it into the home at build time and at every start, so a named volume on the home
+# keeps accounts, chats and outputs without pinning the first image's code.
ARG BASE_IMAGE=unsloth/unsloth-rocm:latest
+# Builds the "Unsloth Dark" (Monokai) theme + Colab-style cell-nav keymap, as
+# Dockerfile.studio does. Node lives only in this throwaway stage; the final image
+# copies just the prebuilt labextension (runtime stays Node-free). The ROCm base has
+# no jupyterlab, so jlpm is installed into this stage's venv, at the final stage's pin.
+FROM ${BASE_IMAGE} AS labext-builder
+ENV DEBIAN_FRONTEND=noninteractive
+# JupyterLab 4.6 needs Node >=20; Ubuntu 24.04 ships 18, so pull Node 20 LTS from
+# NodeSource. This stage is thrown away, so the apt sources never reach runtime.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates curl gnupg git \
+ && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+ && apt-get install -y --no-install-recommends nodejs \
+ && rm -rf /var/lib/apt/lists/*
+RUN /opt/unsloth-venv/bin/uv pip install --python /opt/unsloth-venv/bin/python "jupyterlab==4.6.0"
+COPY jupyter/unsloth_labext /opt/labext-src
+RUN cd /opt/labext-src \
+ && /opt/unsloth-venv/bin/jlpm install \
+ && /opt/unsloth-venv/bin/jlpm build:prod
+
FROM ${BASE_IMAGE}
# Studio source ref to clone. Defaults to main; docker-publish-rocm.yml pins it
@@ -43,19 +74,54 @@ ARG UNSLOTH_STUDIO_REF=main
# unsloth-zoo ref overlaid into the Studio venv by install.sh --local, so Studio
# runs the same zoo as the base.
ARG UNSLOTH_STUDIO_ZOO_REF=main
+# unslothai/notebooks commit/branch/tag to bake; a sha for a reproducible build.
+ARG UNSLOTH_NOTEBOOKS_REF=main
+# Services run as root, as in Dockerfile.studio. The JUPYTER_PORT default lets
+# supervisord's %(ENV_*)s resolve; UNSLOTH_ENABLE_SSHD is there for the same reason
+# and stays false, since supervisord.conf is shared with the CUDA image and still
+# carries an sshd program this image has no binary for.
# UV_CACHE_DIR lives in the app dir: install.sh defaults it to
# $UNSLOTH_STUDIO_HOME/cache/uv, which would fill a volume on the home with wheels.
ENV UNSLOTH_STUDIO_HOME=/opt/unsloth-studio \
UNSLOTH_STUDIO_APP=/opt/unsloth-studio-app \
UV_CACHE_DIR=/opt/unsloth-studio-app/uv-cache \
+ JUPYTER_PORT=8888 \
UNSLOTH_STUDIO_PORT=8000 \
+ UNSLOTH_ENABLE_SSHD=false \
+ UNSLOTH_STUDIO_SHUTDOWN_STOP_TIMEOUT_S=120 \
+ UNSLOTH_STUDIO_STOP_WAIT_S=150 \
DEBIAN_FRONTEND=noninteractive
+# install.sh needs curl + git; supervisor runs Studio and JupyterLab together;
+# ffmpeg is what the notebooks' audio decode shells out to (docker/Dockerfile bakes
+# it for the same reason), and it is not in the ROCm base.
RUN apt-get update \
- && apt-get install -y --no-install-recommends curl git ca-certificates \
+ && apt-get install -y --no-install-recommends \
+ curl git ca-certificates supervisor ffmpeg \
&& rm -rf /var/lib/apt/lists/*
+# JupyterLab and the notebooks' runtime packages into the base venv, so the kernel
+# is the ROCm torch. The same pins as the CUDA core image (docker/Dockerfile, which
+# says what each one is for); a test keeps them equal. Left out of that set:
+# torchcodec no ROCm wheel on any pytorch.org rocm leaf (see the note in
+# studio/install_python_stack.py), so a notebook's own
+# `pip install torchcodec` is forwarded by the shim rather than baked
+# protobuf the base already carries a newer one than the CUDA pin
+# Pure Python plus decord (amd64 only, which this image is), but the resolve runs
+# against pypi alone, where a torch it chose to move would be a CUDA wheel, and
+# librosa pulls numba, which constrains numpy; both are asserted unmoved.
+RUN set -eux \
+ && BASE_TORCH="$(/opt/unsloth-venv/bin/python -c "from importlib.metadata import version; print(version('torch'))")" \
+ && BASE_NUMPY="$(/opt/unsloth-venv/bin/python -c "from importlib.metadata import version; print(version('numpy'))")" \
+ && /opt/unsloth-venv/bin/uv pip install --python /opt/unsloth-venv/bin/python \
+ "jupyterlab==4.6.0" "notebook==7.6.0" "ipywidgets==8.1.8" "matplotlib==3.11.0" \
+ "soundfile==0.14.0" "evaluate==0.4.6" "jiwer==4.0.0" "tensorboard==2.20.0" \
+ "langid==1.1.6" "easydict==1.13" "omegaconf==2.3.1" "einx==0.4.3" \
+ "librosa==0.11.0" "ftfy==6.3.1" "decord==0.6.0" \
+ && /opt/unsloth-venv/bin/python -c "from importlib.metadata import version; v = version('torch'); assert v == '${BASE_TORCH}', 'the notebook-deps install moved torch from ${BASE_TORCH} to ' + v; n = version('numpy'); assert n == '${BASE_NUMPY}', 'the notebook-deps install moved numpy from ${BASE_NUMPY} to ' + n; import jupyterlab, jupyter_server, numba, soundfile, librosa, evaluate, jiwer, decord, omegaconf, einx, matplotlib, tensorboard, langid, easydict, ftfy; print('jupyterlab', jupyterlab.__version__, 'jupyter_server', jupyter_server.__version__, 'torch', v, 'numpy', n, 'numba', numba.__version__)" \
+ && rm -rf /root/.cache/uv
+
# The linker this build finishes with, and the entrypoint reruns.
COPY studio_home.sh /usr/local/bin/unsloth-studio-home
@@ -66,6 +132,10 @@ COPY studio_home.sh /usr/local/bin/unsloth-studio-home
# the index it actually resolved against: the pytorch.org rocm leaf normally, or
# repo.amd.com/rocm/whl/<family>/ on a per-arch (ROCM_GFX) build. Letting
# install.sh detect instead would land on CPU wheels, since the builder has no GPU.
+# ROCM_GFX goes along as UNSLOTH_ROCM_GFX_ARCH for the same reason: with the index
+# pinned, install.sh learns gfx906 only from that variable or a live probe, and
+# without it a gfx906 build would put the prebuilt bitsandbytes (no gfx906
+# kernels) into the Studio venv that the base deliberately leaves out.
#
# fetch+checkout FETCH_HEAD, not `clone --branch`: CI passes a commit SHA.
RUN set -eux \
@@ -78,12 +148,8 @@ RUN set -eux \
&& git checkout -q FETCH_HEAD \
&& UNSLOTH_STUDIO_HOME="${UNSLOTH_STUDIO_HOME}" \
UNSLOTH_TORCH_INDEX_URL="${TORCH_INDEX_URL}" \
- UNSLOTH_ZOO_REF="${UNSLOTH_STUDIO_ZOO_REF}" \
- # ROCM_GFX from the base's record too: install.sh leaves bitsandbytes out of a
- # gfx906 install (no wheel carries its kernels) only when told the arch, since
- # the GPU-less builder cannot probe it. Empty on a generic build, which
- # install.sh reads as unset.
UNSLOTH_ROCM_GFX_ARCH="${ROCM_GFX}" \
+ UNSLOTH_ZOO_REF="${UNSLOTH_STUDIO_ZOO_REF}" \
UNSLOTH_LLAMA_CPP_BACKEND=cpu \
UNSLOTH_SKIP_WHISPER_INSTALL=1 \
UNSLOTH_PYTHON=3.12 \
@@ -97,8 +163,6 @@ RUN set -eux \
# ROCm. The cost is two torch copies in one image; deduping them is a follow-up.
&& BASE_ROCM="$(/opt/unsloth-venv/bin/python -c "from importlib.metadata import version; print(version('torch').split('+')[1])")" \
&& "${UNSLOTH_STUDIO_HOME}/unsloth_studio/bin/python" -c "import sys; from importlib.metadata import version; v = version('torch'); assert '+rocm' in v, 'Studio venv torch ' + v + ' is not a ROCm build'; assert v.split('+')[1] == '${BASE_ROCM}', 'Studio venv torch ' + v + ' is not the base venv ROCm leaf ${BASE_ROCM}'; print('Studio venv python %d.%d torch' % sys.version_info[:2], v, 'on base ROCm leaf ${BASE_ROCM}')" \
- # A gfx906 Studio venv must not expose the 4-bit backend the base removed.
- && "${UNSLOTH_STUDIO_HOME}/unsloth_studio/bin/python" -c "import importlib.util as u; has = u.find_spec('bitsandbytes') is not None; assert not (has and '${ROCM_GFX}' == 'gfx906'), 'Studio venv has bitsandbytes on a gfx906 base'; print('Studio venv bitsandbytes:', has, 'ROCM_GFX:', '${ROCM_GFX}' or '(generic)')" \
# The UI is the point of this image, so a missing frontend build is fatal here
# rather than a 404 at runtime.
&& test -f "${UNSLOTH_STUDIO_HOME}/src/studio/frontend/dist/index.html" \
@@ -111,16 +175,129 @@ RUN set -eux \
&& bash /usr/local/bin/unsloth-studio-home \
&& "${UNSLOTH_STUDIO_HOME}/unsloth_studio/bin/python" -c "import os, sys, studio; print('Studio venv', sys.prefix, 'imports studio from', studio.__file__); assert os.path.realpath(studio.__file__).startswith(os.path.realpath('${UNSLOTH_STUDIO_HOME}/src') + '/'), studio.__file__"
-# unsloth-studio-run is the CUDA image's Studio program: it hands Studio the
-# initial password only while none is stored. The launcher is this image's own,
-# since the CUDA one starts supervisord.
+COPY supervisord.conf /etc/supervisor/supervisord.conf
+COPY studio_launch.sh /usr/local/bin/unsloth-studio-launch
+COPY studio_password.sh /usr/local/bin/unsloth-studio-password
COPY studio_run.sh /usr/local/bin/unsloth-studio-run
-COPY studio_launch_rocm.sh /usr/local/bin/unsloth-studio-launch
-RUN chmod +x /usr/local/bin/unsloth-studio-home /usr/local/bin/unsloth-studio-run \
- /usr/local/bin/unsloth-studio-launch
+# Optional public Cloudflare tunnel for JupyterLab (UNSLOTH_JUPYTER_CLOUDFLARE=1,
+# or `unsloth-jupyter-tunnel --force`); supervisord runs it as jupyter-cloudflare.
+COPY unsloth_jupyter_tunnel.sh /usr/local/bin/unsloth-jupyter-tunnel
+# JupyterLab defaults baked for every container (theme, non-advancing run button,
+# labeled "Restart & Run All", windowing off, cell-nav keymap, news prompt off).
+# overrides.json is the settings override; theme + keymap + logo ship as the
+# prebuilt labextension from labext-builder above.
+COPY jupyter/overrides.json /opt/unsloth-venv/share/jupyter/lab/settings/overrides.json
+COPY --from=labext-builder /opt/labext-src/unsloth-jupyterlab/labextension /opt/unsloth-venv/share/jupyter/labextensions/unsloth-jupyterlab
+# Unsloth branding (applied to jupyter_server's site-packages): replace favicon +
+# logo, brand login.html, disable+lock the stock top-left logo. Only the
+# sloth-sticker install is fail-soft (`|| echo`); the copies above stay fatal.
+COPY jupyter/favicon.ico /tmp/unsloth-branding/favicon.ico
+COPY jupyter/logo.png /tmp/unsloth-branding/logo.png
+COPY jupyter/login.html /tmp/unsloth-branding/login.html
+COPY jupyter/install_sloth_stickers.py /tmp/unsloth-branding/install_sloth_stickers.py
+RUN JS="$(/opt/unsloth-venv/bin/python -c 'import os, jupyter_server; print(os.path.dirname(jupyter_server.__file__))')" \
+ && for n in favicon.ico favicon-notebook.ico favicon-file.ico favicon-terminal.ico; do \
+ cp /tmp/unsloth-branding/favicon.ico "${JS}/static/favicons/${n}"; \
+ done \
+ && cp /tmp/unsloth-branding/logo.png "${JS}/static/logo/logo.png" \
+ && cp /tmp/unsloth-branding/login.html "${JS}/templates/login.html" \
+ && { /opt/unsloth-venv/bin/python /tmp/unsloth-branding/install_sloth_stickers.py \
+ --src "${UNSLOTH_STUDIO_HOME}/src/studio/frontend/public/Sloth emojis" \
+ --dest "${JS}/static/sloth" \
+ || echo ">> sloth stickers not installed (login falls back to the Unsloth logo)"; } \
+ && rm -rf /tmp/unsloth-branding \
+ && /opt/unsloth-venv/bin/jupyter labextension disable @jupyterlab/application-extension:logo \
+ && /opt/unsloth-venv/bin/jupyter labextension lock @jupyterlab/application-extension:logo \
+ && /opt/unsloth-venv/bin/jupyter labextension disable @jupyterlab/apputils-extension:splash \
+ && /opt/unsloth-venv/bin/jupyter labextension lock @jupyterlab/apputils-extension:splash \
+ && /opt/unsloth-venv/bin/jupyter labextension lock unsloth-jupyterlab
+# Branding integrity guard: the attribution checker (a jupyter_server extension),
+# the AGPLv3 license text, and its enabling config, into the base venv. --verify
+# FAILS the build if any attribution / license asset is missing or altered.
+COPY jupyter/unsloth_branding.py /tmp/unsloth-branding-guard/unsloth_branding.py
+COPY jupyter/jupyter_server_config.d/unsloth_branding_guard.json /tmp/unsloth-branding-guard/unsloth_branding_guard.json
+RUN SP="$(/opt/unsloth-venv/bin/python -c 'import sysconfig; print(sysconfig.get_path("purelib"))')" \
+ && cp /tmp/unsloth-branding-guard/unsloth_branding.py "${SP}/unsloth_branding.py" \
+ && mkdir -p /opt/unsloth-venv/etc/jupyter/jupyter_server_config.d \
+ && cp /tmp/unsloth-branding-guard/unsloth_branding_guard.json \
+ /opt/unsloth-venv/etc/jupyter/jupyter_server_config.d/unsloth_branding_guard.json \
+ && cp "${UNSLOTH_STUDIO_HOME}/src/studio/LICENSE.AGPL-3.0" \
+ /opt/unsloth-venv/share/jupyter/UNSLOTH_LICENSE.AGPL-3.0 \
+ && rm -rf /tmp/unsloth-branding-guard \
+ && /opt/unsloth-venv/bin/python -m unsloth_branding --verify
+
+# The notebook tooling of the CUDA core image (docker/Dockerfile), so the notebooks
+# run UNCHANGED here too (see unsloth_nb_compat.py):
+# * pip/uv shim on a PATH dir AHEAD of the venv bin: an install cell cannot clobber
+# the baked ROCm stack (torch, triton-rocm, bitsandbytes, unsloth, ...); a
+# transformers pin is recorded, everything else passes through.
+# * unsloth_nb_pip_magic.py re-points %pip/%uv and `!python -m pip` at that shim.
+# * the IPython startup hook (IPYTHONDIR below) loads both, plus the Colab
+# cell-magic compat, for every kernel.
+# * unsloth-sync-notebooks populates /workspace/unsloth-notebooks on every start and
+# builds the by-topic view; it shows the AMD-* notebooks when rocm-smi is on PATH.
+# * unsloth-run: headless `unsloth-run <notebook|url>`.
+# No transformers sidecars are baked: the CUDA image derives its set from the vLLM
+# it carries, and this image carries none, so a recorded transformers pin resolves
+# to the base venv's transformers.
+COPY unsloth_nb_compat.py unsloth_pip_shim.py unsloth_nb_pip_magic.py unsloth_ipython_startup.py unsloth_run.py unsloth_sync_notebooks.sh unsloth_nb_content_sig.py unsloth_nb_view.py unsloth_nb_strip_colab.py unsloth_colab_compat.py /opt/unsloth-nb/
+RUN set -eux \
+ && SP="$(/opt/unsloth-venv/bin/python -c 'import sysconfig; print(sysconfig.get_path("purelib"))')" \
+ && cp /opt/unsloth-nb/unsloth_nb_compat.py "$SP/unsloth_nb_compat.py" \
+ && cp /opt/unsloth-nb/unsloth_nb_pip_magic.py "$SP/unsloth_nb_pip_magic.py" \
+ && cp /opt/unsloth-nb/unsloth_colab_compat.py "$SP/unsloth_colab_compat.py" \
+ && chmod +x /opt/unsloth-nb/unsloth_pip_shim.py /opt/unsloth-nb/unsloth_run.py /opt/unsloth-nb/unsloth_sync_notebooks.sh /opt/unsloth-nb/unsloth_nb_content_sig.py /opt/unsloth-nb/unsloth_nb_view.py /opt/unsloth-nb/unsloth_nb_strip_colab.py \
+ && mkdir -p /opt/unsloth-nb/bin \
+ && for t in pip pip3 uv; do ln -sf /opt/unsloth-nb/unsloth_pip_shim.py /opt/unsloth-nb/bin/$t; done \
+ && ln -sf /opt/unsloth-nb/unsloth_run.py /usr/local/bin/unsloth-run \
+ && ln -sf /opt/unsloth-nb/unsloth_sync_notebooks.sh /usr/local/bin/unsloth-sync-notebooks \
+ && ln -sf /opt/unsloth-nb/unsloth_nb_content_sig.py /usr/local/bin/unsloth-nb-content-sig \
+ && ln -sf /opt/unsloth-nb/unsloth_nb_view.py /usr/local/bin/unsloth-nb-view \
+ && ln -sf /opt/unsloth-nb/unsloth_nb_strip_colab.py /usr/local/bin/unsloth-nb-strip-colab \
+ && mkdir -p /opt/unsloth-nb/ipython/profile_default/startup \
+ && cp /opt/unsloth-nb/unsloth_ipython_startup.py /opt/unsloth-nb/ipython/profile_default/startup/00-unsloth-nb.py \
+ && chmod -R a+rX /opt/unsloth-nb/ipython \
+ && chmod 1777 /opt/unsloth-nb/ipython /opt/unsloth-nb/ipython/profile_default \
+ && /opt/unsloth-venv/bin/python -c "import sys; sys.path.insert(0, '$SP'); import unsloth_nb_compat, unsloth_colab_compat; print('nb-compat OK')" \
+ && /opt/unsloth-venv/bin/python /opt/unsloth-nb/unsloth_pip_shim.py --unsloth-selfcheck-value-flags
+# Shim dir AHEAD of the venv bin so `!pip`/`!uv` resolve to the shim, not the real tool.
+ENV PATH=/opt/unsloth-nb/bin:${PATH}
+# The shared IPython profile, writable by any uid (the 1777 above), so every kernel
+# loads the startup hook; see docker/Dockerfile for why /root/.ipython would not do.
+ENV IPYTHONDIR=/opt/unsloth-nb/ipython
+
+# Pre-clone unslothai/notebooks as the CUDA core image does: a READ-ONLY template
+# (.git stripped) that the entrypoint copies to /workspace/unsloth-notebooks on boot
+# and best-effort refreshes from GitHub, never overwriting a user-touched notebook
+# (see unsloth_sync_notebooks.sh). The AMD-* set is what this image is for, so a
+# ref without one fails the build.
+RUN set -eux \
+ && git init -q /opt/unsloth-notebooks \
+ && git -C /opt/unsloth-notebooks remote add origin https://github.com/unslothai/notebooks \
+ && git -C /opt/unsloth-notebooks fetch -q --depth 1 origin "${UNSLOTH_NOTEBOOKS_REF}" \
+ && git -C /opt/unsloth-notebooks checkout -q FETCH_HEAD \
+ && git -C /opt/unsloth-notebooks rev-parse HEAD > /opt/unsloth-notebooks/.unsloth_template_commit \
+ && rm -rf /opt/unsloth-notebooks/.git \
+ && AMD_NB="$(ls /opt/unsloth-notebooks/nb | grep -c '^AMD-' || true)" \
+ && echo "unslothai/notebooks@$(cat /opt/unsloth-notebooks/.unsloth_template_commit): ${AMD_NB} AMD-* notebooks" \
+ && [ "${AMD_NB}" -gt 0 ] \
+ && du -sh /opt/unsloth-notebooks
+
+RUN chmod +x /usr/local/bin/unsloth-studio-home \
+ /usr/local/bin/unsloth-studio-launch \
+ /usr/local/bin/unsloth-studio-password \
+ /usr/local/bin/unsloth-studio-run \
+ /usr/local/bin/unsloth-jupyter-tunnel
+
+# Studio and JupyterLab. Both bind 0.0.0.0 in the container; publish with -p.
+EXPOSE 8000 8888
-EXPOSE 8000
+# BASE_IMAGE defaults to the PUBLISHED base, whose baked entrypoint predates the two
+# Studio hooks (link the code into the home, sync the notebooks): without this copy
+# supervisord would start Studio against an unlinked home.
+COPY entrypoint-rocm.sh /usr/local/bin/unsloth-entrypoint-rocm
+RUN chmod +x /usr/local/bin/unsloth-entrypoint-rocm
-# The base ENTRYPOINT (unsloth-entrypoint-rocm) runs its GPU pre-flight first,
-# then execs this.
+# The base ENTRYPOINT (unsloth-entrypoint-rocm) runs its GPU pre-flight first, then
+# hands off to the service launcher.
CMD ["/usr/local/bin/unsloth-studio-launch"]
diff --git a/docker/entrypoint-rocm.sh b/docker/entrypoint-rocm.sh
index 48e51c919ed..425cd9c7d24 100644
--- a/docker/entrypoint-rocm.sh
+++ b/docker/entrypoint-rocm.sh
@@ -13,6 +13,24 @@
# docker run -e UNSLOTH_SKIP_GPU_CHECK=1 ...
set -euo pipefail
+# Studio image: relink its code into the home (maybe an earlier image's volume) before
+# anything reads the venv, as entrypoint.sh does on the CUDA image. Fatal on failure
+# (a half-linked home); no-op on the base image, which has no linker.
+if [[ -x /usr/local/bin/unsloth-studio-home ]]; then
+ /usr/local/bin/unsloth-studio-home || {
+ echo "ERROR: could not link Unsloth Studio's code into ${UNSLOTH_STUDIO_HOME:-/opt/unsloth-studio}; see the messages above" >&2
+ exit 1
+ }
+fi
+
+# best-effort, gated by UNSLOTH_SKIP_NOTEBOOK_SYNC, never blocks the container;
+# no-op on the base image, which ships no notebooks
+sync_notebooks() {
+ if [[ -x /usr/local/bin/unsloth-sync-notebooks ]]; then
+ /usr/local/bin/unsloth-sync-notebooks || true
+ fi
+}
+
err() { printf "\033[1;31mERROR:\033[0m %s\n" "$*" >&2; }
warn() { printf "\033[1;33mWARN:\033[0m %s\n" "$*" >&2; }
note() { printf "\033[1;36mNOTE:\033[0m %s\n" "$*" >&2; }
@@ -42,6 +60,7 @@ esac
# The skip flag bypasses the diagnostics only; the override cleanup above
# still applies, since it changes what the command sees.
if [[ "${UNSLOTH_SKIP_GPU_CHECK:-0}" == "1" ]]; then
+ sync_notebooks
exec "$@"
fi
@@ -362,4 +381,5 @@ for i in range(torch.cuda.device_count()):
sys.exit(0)
PY
+sync_notebooks
exec "$@"
diff --git a/docker/studio_launch.sh b/docker/studio_launch.sh
index 61fe9a41313..adbea478b75 100644
--- a/docker/studio_launch.sh
+++ b/docker/studio_launch.sh
@@ -55,9 +55,10 @@ export UNSLOTH_JUPYTER_CLOUDFLARE="${UNSLOTH_JUPYTER_CLOUDFLARE:-0}"
# SSH login shells lack the `docker run -e` vars. Secrets are excluded on purpose,
# and every value is shlex.quote()d because this file is sourced by every login shell.
+# The ROCm prefixes are the image's ROCBLAS_USE_HIPBLASLT and a user's HSA_OVERRIDE_GFX_VERSION.
python - > /etc/profile.d/unsloth_env.sh <<'PY' || true
import os, re, shlex
-keep = re.compile(r"^(HF_|CUDA_|NCCL_|JUPYTER_|UNSLOTH_|WANDB_|TRITON_)|^PATH$")
+keep = re.compile(r"^(HF_|CUDA_|NCCL_|HSA_|HIP_|ROCM_|ROCR_|ROCBLAS_|JUPYTER_|UNSLOTH_|WANDB_|TRITON_)|^PATH$")
secret = re.compile(r"(_TOKEN|_API_KEY|_PASSWORD|_SECRET|_LICENSE)$")
for key, value in sorted(os.environ.items()):
if keep.search(key) and not secret.search(key):
diff --git a/docker/supervisord.conf b/docker/supervisord.conf
index 09d4b5976e5..f72c87009e2 100644
--- a/docker/supervisord.conf
+++ b/docker/supervisord.conf
@@ -1,4 +1,4 @@
-# Service manager for the full Unsloth image (Dockerfile.studio):
+# Service manager for the full Unsloth images (Dockerfile.studio, Dockerfile.studio-rocm):
# studio Unsloth Studio web UI port $UNSLOTH_STUDIO_PORT (default 8000)
# jupyter JupyterLab for the notebooks port $JUPYTER_PORT (default 8888)
# sshd key-only SSH for cloud hosts port 22
diff --git a/tests/python/test_docker_rocm.py b/tests/python/test_docker_rocm.py
index 0820b3671de..2d3fe71cd09 100644
--- a/tests/python/test_docker_rocm.py
+++ b/tests/python/test_docker_rocm.py
@@ -829,7 +829,16 @@ class TestRocmEntrypoint:
out.write_text("")
env = {"PATH": os.environ["PATH"], "GITHUB_OUTPUT": str(out)}
env.update({k: str(v) for k, v in wf["env"].items()})
- env.update({"IN_UNSLOTH": "", "IN_ZOO": "", "IN_ROCM": "", "IN_INDEX": "", "IN_GFX": ""})
+ env.update(
+ {
+ "IN_UNSLOTH": "",
+ "IN_ZOO": "",
+ "IN_NOTEBOOKS": "",
+ "IN_ROCM": "",
+ "IN_INDEX": "",
+ "IN_GFX": "",
+ }
+ )
env.update(inputs)
proc = subprocess.run(
["bash", "-e", "-c", step["run"]], env = env, capture_output = True, text = True
@@ -879,50 +888,67 @@ class TestRocmEntrypoint:
assert "load_in_4bit = four_bit" in smoke and "ROCM_GFX=gfx906" in smoke
entry = open(_ENTRYPOINT, encoding = "utf-8").read()
assert "ROCM_GFX=gfx906 ROCM_VERSION=6.3.4" in entry
+ # The Studio venv is installed by install.sh with the index pinned, which
+ # skips the reroute that would notice gfx906, and the builder has no GPU
+ # to probe, so the arch has to be forwarded or the prebuilt wheel goes in.
+ studio = open(os.path.join(_DOCKER, "Dockerfile.studio-rocm"), encoding = "utf-8").read()
+ install = studio[
+ studio.index(". /etc/unsloth-rocm-build") : studio.index("bash install.sh --local")
+ ]
+ assert 'UNSLOTH_TORCH_INDEX_URL="${TORCH_INDEX_URL}"' in install
+ assert 'UNSLOTH_ROCM_GFX_ARCH="${ROCM_GFX}"' in install
def test_the_studio_image_is_published_from_the_base_digest_with_the_same_refs(self):
"""docker/Dockerfile.studio-rocm is built by the same run as the base, on the
base by digest (a tag can already be a newer run's) with the refs the base
- baked, and takes the base's tags with a -studio leaf under the same gates."""
+ baked, and takes the base's tags with a -studio leaf under the same gates.
+ Neither tag set moves until both digests exist: a :latest that moved while the
+ Studio build then failed would leave :studio on the previous base."""
import yaml
wf = yaml.safe_load(open(_WORKFLOW, encoding = "utf-8"))
build = wf["jobs"]["build-studio"]
- assert build["needs"] == ["prepare", "build"]
+ assert "build" in build["needs"] and "tag" not in build["needs"], build["needs"]
+ assert "build-studio" in wf["jobs"]["tag"]["needs"], wf["jobs"]["tag"]["needs"]
step = next(s for s in build["steps"] if s.get("id") == "build")
assert step["with"]["file"] == "./docker/Dockerfile.studio-rocm"
args = dict(ln.split("=", 1) for ln in step["with"]["build-args"].splitlines() if ln)
assert args["BASE_IMAGE"].endswith("@${{ needs.build.outputs.digest }}"), args
assert args["UNSLOTH_STUDIO_REF"] == "${{ needs.prepare.outputs.unsloth_ref }}"
assert args["UNSLOTH_STUDIO_ZOO_REF"] == "${{ needs.prepare.outputs.zoo_ref }}"
-
- # no stable tag moves until both digests exist, and both manifests are created in ONE
- # job, back to back. That orders the two writes WITHIN a run; it does not order two
- # RUNS, which the per-run concurrency group deliberately lets overlap. Same shape as
- # docker-publish.yml for latest + core, so the pairing window is repo-wide rather
- # than this workflow's, and closing it needs a real lock: a shared concurrency group
- # cancels a PENDING job (tests/studio/test_main_runs_survive_merge_bursts.py), which
- # would drop a whole run's tags instead.
- tag = wf["jobs"]["tag"]
- assert tag["needs"] == ["prepare", "build", "build-studio"]
- ids = [s.get("id") for s in tag["steps"]]
- names = [s.get("name") for s in tag["steps"]]
- assert ids.index("meta") < ids.index("meta_studio")
- assert names.index("Create manifest") < names.index("Create Studio manifest")
- assert "tag-studio" not in wf["jobs"]
-
- def tag_lines(step_id):
- meta = next(s for s in tag["steps"] if s.get("id") == step_id)
+ # the notebooks too: the layer is keyed on this string, so a mutable ref
+ # would be a cache hit on the next run and ship the old set
+ assert args["UNSLOTH_NOTEBOOKS_REF"] == "${{ needs.prepare.outputs.notebooks_commit }}"
+ prepare = wf["jobs"]["prepare"]
+ assert prepare["outputs"]["notebooks_commit"] == "${{ steps.notebooks.outputs.commit }}"
+ resolve = next(s for s in prepare["steps"] if s.get("id") == "notebooks")
+ assert "git ls-remote https://github.com/unslothai/notebooks" in resolve["run"]
+
+ def tag_lines(job):
+ meta = next(s for s in wf["jobs"][job]["steps"] if s.get("id") == "meta")
return [ln for ln in meta["with"]["tags"].splitlines() if ln.strip()]
- studio, base = tag_lines("meta_studio"), tag_lines("meta")
+ tag = wf["jobs"]["tag-studio"]
+ assert "build-studio" in tag["needs"] and "tag" in tag["needs"], tag["needs"]
+ studio, base = tag_lines("tag-studio"), tag_lines("tag")
assert len(studio) == len(base) == 5
for s_ln, b_ln in zip(studio, base):
assert "studio" in s_ln, s_ln
# the same enable= gate as the base line it mirrors
assert s_ln.split(",enable=", 1)[1:] == b_ln.split(",enable=", 1)[1:], (s_ln, b_ln)
- create = next(s for s in tag["steps"] if s.get("name") == "Create Studio manifest")
- assert create["env"]["DIGEST"] == "${{ needs.build-studio.outputs.digest }}"
+ # the page describes both images, so it syncs only once both moved
+ assert "tag-studio" in wf["jobs"]["hub-readme"]["needs"]
+
+ def test_a_notebooks_override_gets_sha_tags_only(self, tmp_path):
+ """A dispatch that bakes another notebooks ref is an experiment like any
+ other override: :studio and :latest name the default build only."""
+ for ref in ("", "main"):
+ rc, got, out = self._build_args(tmp_path, IN_NOTEBOOKS = ref)
+ assert rc == 0 and got["stable"] == "true", (ref, out)
+ rc, got, out = self._build_args(tmp_path, IN_NOTEBOOKS = "some-branch")
+ assert rc == 0 and got["stable"] == "false", out
+ rc, got, out = self._build_args(tmp_path, IN_NOTEBOOKS = "some-branch", IN_GFX = "gfx1151")
+ assert rc == 0 and got["gfx_tag"] == "false", out
def test_the_gfx_tag_needs_every_other_input_at_its_default(self):
"""A feature-branch ref plus rocm_gfx=gfx1151 must not replace the public
@@ -1033,11 +1059,12 @@ class TestStudioLaunchRocm:
body = open(_STUDIO_DOCKERFILE, encoding = "utf-8").read()
assert 'CMD ["/usr/local/bin/unsloth-studio-launch"]' in body
assert "COPY studio_run.sh /usr/local/bin/unsloth-studio-run" in body
- assert "COPY studio_launch_rocm.sh /usr/local/bin/unsloth-studio-launch" in body
- # the CUDA image's studio-password program waits on JupyterLab, which this
- # image does not run; nothing here may invoke or ship it
- assert "studio_password" not in body
+ # The single-service ROCm launcher was replaced by the shared studio_launch.sh
+ # under supervisord once this image gained JupyterLab (#11286); the
+ # program list itself is asserted in test_docker_studio_rocm_jupyter.py.
+ assert "COPY studio_launch.sh /usr/local/bin/unsloth-studio-launch" in body
+ assert "COPY supervisord.conf /etc/supervisor/supervisord.conf" in body
# the gfx906 base removes bitsandbytes; the Studio venv must be told the arch
assert 'UNSLOTH_ROCM_GFX_ARCH="${ROCM_GFX}"' in body
ignore = open(os.path.join(_DOCKER, ".dockerignore"), encoding = "utf-8").read()
- assert "!studio_launch_rocm.sh" in ignore and "!studio_run.sh" in ignore
+ assert "!studio_launch.sh" in ignore and "!studio_run.sh" in ignore
diff --git a/tests/python/test_docker_studio_rocm_jupyter.py b/tests/python/test_docker_studio_rocm_jupyter.py
new file mode 100644
index 00000000000..5eaf85d0ecd
--- /dev/null
+++ b/tests/python/test_docker_studio_rocm_jupyter.py
@@ -0,0 +1,380 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-Present the Unsloth team. See /studio/LICENSE.AGPL-3.0
+
+"""docker/Dockerfile.studio-rocm ships JupyterLab and the notebooks beside Unsloth
+Studio, as unsloth/unsloth:studio does on CUDA, minus its sshd. Dockerfile.studio
+inherits JupyterLab and the notebook tooling from the CUDA core image; the ROCm base
+carries none of that, so the ROCm file installs it itself, and the two can drift
+apart without any build noticing. These pin each piece to the CUDA file it mirrors,
+and the entrypoint hooks the services depend on. Static reads: no AMD GPU, no
+Docker, no network.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DOCKER = REPO_ROOT / "docker"
+CUDA_BASE = DOCKER / "Dockerfile"
+CUDA_STUDIO = DOCKER / "Dockerfile.studio"
+ROCM_BASE = DOCKER / "Dockerfile.rocm"
+ROCM_STUDIO = DOCKER / "Dockerfile.studio-rocm"
+ENTRYPOINT = DOCKER / "entrypoint-rocm.sh"
+CUDA_ENTRYPOINT = DOCKER / "entrypoint.sh"
+SUPERVISORD = DOCKER / "supervisord.conf"
+LAUNCH = DOCKER / "studio_launch.sh"
+DOCKERIGNORE = DOCKER / ".dockerignore"
+WORKFLOW = REPO_ROOT / ".github" / "workflows" / "docker-publish-rocm.yml"
+LABEXT_PKG = DOCKER / "jupyter" / "unsloth_labext" / "package.json"
+BRANDING = DOCKER / "jupyter" / "unsloth_branding.py"
+
+VENV = "/opt/unsloth-venv"
+
+
+def _read(path: Path) -> str:
+ return path.read_text(encoding = "utf-8")
+
+
+def _logical_lines(text: str) -> list[str]:
+ """Dockerfile instructions with their backslash continuations joined."""
+ return [ln.strip() for ln in re.sub(r"\\\r?\n", " ", text).splitlines()]
+
+
+def _instructions(path: Path, name: str) -> list[str]:
+ return [
+ ln[len(name) :].strip() for ln in _logical_lines(_read(path)) if ln.startswith(name + " ")
+ ]
+
+
+def _copies(path: Path) -> list[tuple[str, list[str], str]]:
+ """(--from stage or '', sources, destination) for every COPY."""
+ out = []
+ for args in _instructions(path, "COPY"):
+ words = args.split()
+ stage = ""
+ if words and words[0].startswith("--from="):
+ stage = words.pop(0)[len("--from=") :]
+ out.append((stage, words[:-1], words[-1]))
+ return out
+
+
+def _env(path: Path) -> dict[str, str]:
+ env: dict[str, str] = {}
+ for args in _instructions(path, "ENV"):
+ for m in re.finditer(r"(\w+)=(\S+)", args):
+ env[m.group(1)] = m.group(2)
+ return env
+
+
+def _pins(text: str, packages) -> dict[str, set[str]]:
+ return {pkg: set(re.findall(rf'"{re.escape(pkg)}==([0-9][^"]*)"', text)) for pkg in packages}
+
+
+def _branding_module():
+ spec = importlib.util.spec_from_file_location("unsloth_branding_under_test", BRANDING)
+ assert spec is not None and spec.loader is not None
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[spec.name] = module
+ spec.loader.exec_module(module)
+ return module
+
+
+# ── JupyterLab itself ────────────────────────────────────────────────────────
+
+JUPYTER_PINS = ("jupyterlab", "notebook", "ipywidgets")
+
+
+def test_jupyterlab_is_pinned_to_the_cuda_core_image():
+ cuda = _pins(_read(CUDA_BASE), JUPYTER_PINS)
+ rocm = _pins(_read(ROCM_STUDIO), JUPYTER_PINS)
+ for pkg in JUPYTER_PINS:
+ assert len(cuda[pkg]) == 1, f"{pkg} is pinned {cuda[pkg] or 'nowhere'} in docker/Dockerfile"
+ assert rocm[pkg] == cuda[pkg], (
+ f"{pkg}=={rocm[pkg] or '(unpinned)'} in Dockerfile.studio-rocm but "
+ f"{cuda[pkg]} in docker/Dockerfile: the two images would ship different notebook stacks"
+ )
+ # the labext-builder stage builds the extension against the jupyterlab it will run under
+ (jl,) = cuda["jupyterlab"]
+ assert (
+ _read(ROCM_STUDIO).count(f'"jupyterlab=={jl}"') == 2
+ ), "the labext-builder stage and the final stage must install the same jupyterlab"
+
+
+NOT_MIRRORED = {
+ # no ROCm wheel on any pytorch.org rocm leaf; the shim forwards a notebook's own install
+ "torchcodec",
+ # the ROCm base already carries a newer protobuf than the CUDA pin
+ "protobuf",
+}
+
+
+def test_the_notebook_runtime_pins_match_the_cuda_core_image():
+ """docker/Dockerfile bakes what the notebooks' install cells declare (soundfile,
+ evaluate, librosa, decord, ...); the shim then keeps those cells from moving the
+ stack. The ROCm image runs the same notebooks, so it carries the same pins, or the
+ AMD-* audio, TTS and vision notebooks fail on their first import here."""
+ cuda = _read(CUDA_BASE)
+ cuda_runs = [
+ r for r in _instructions(CUDA_BASE, "RUN") if '"soundfile==' in r or '"decord==' in r
+ ]
+ assert len(cuda_runs) == 2, "the CUDA notebook-deps and decord layers moved"
+ wanted = dict(re.findall(r'"([A-Za-z0-9_.-]+)==([0-9][^"]*)"', " ".join(cuda_runs)))
+ assert {"soundfile", "librosa", "decord", "evaluate"} <= set(wanted), wanted
+ rocm = _read(ROCM_STUDIO)
+ for pkg, ver in wanted.items():
+ if pkg in NOT_MIRRORED:
+ continue
+ assert (
+ f'"{pkg}=={ver}"' in rocm
+ ), f"{pkg}=={ver} is baked in docker/Dockerfile but not in Dockerfile.studio-rocm"
+ for pkg in NOT_MIRRORED:
+ assert pkg in cuda, f"{pkg} is no longer in docker/Dockerfile; drop it from NOT_MIRRORED"
+ assert f'"{pkg}==' not in rocm, f"{pkg} is now baked; drop it from NOT_MIRRORED"
+ # torchcodec dlopens system ffmpeg, and the CUDA image installs it for that
+ (apt,) = [
+ r for r in _instructions(ROCM_STUDIO, "RUN") if "apt-get install" in r and "supervisor" in r
+ ]
+ assert " ffmpeg" in apt, "the notebooks' audio decode needs ffmpeg, which the ROCm base lacks"
+
+
+def test_jupyterlab_goes_into_the_base_venv_and_leaves_torch_alone():
+ """The notebook kernel has to be the venv with the ROCm torch, and a resolve
+ against pypi alone must not be allowed to replace that torch with a CUDA one."""
+ (install,) = [r for r in _instructions(ROCM_STUDIO, "RUN") if '"notebook==' in r]
+ assert f"{VENV}/bin/uv pip install --python {VENV}/bin/python" in install
+ assert (
+ "BASE_TORCH=" in install and "version('torch')" in install
+ ), "the install must assert the base venv's torch is the same before and after"
+
+
+# ── the labextension, theme and branding chain ───────────────────────────────
+
+
+def test_the_labextension_lands_where_the_branding_guard_looks():
+ branding = _branding_module()
+ # the guard joins with os.path, and it only ever runs inside the (Linux) image
+ paths = {
+ key: value.replace("\\", "/") if isinstance(value, str) else value
+ for key, value in branding.resolve_paths(
+ venv_share = f"{VENV}/share/jupyter", jupyter_server_dir = "/unused", config_dirs = []
+ ).items()
+ }
+ output_dir = json.loads(_read(LABEXT_PKG))["jupyterlab"]["outputDir"]
+
+ copies = _copies(ROCM_STUDIO)
+ (labext_src, labext_dest) = next(
+ (src[0], dest) for stage, src, dest in copies if stage == "labext-builder"
+ )
+ (staged_src,) = [dest for stage, src, dest in copies if src == ["jupyter/unsloth_labext"]]
+ assert (
+ labext_src == f"{staged_src}/{output_dir}"
+ ), "the --from copy must take the labextension from where jlpm build:prod writes it"
+ assert labext_dest == paths["labext_dir"]
+ assert paths["overrides"] in [
+ dest for _, src, dest in copies if src == ["jupyter/overrides.json"]
+ ]
+ text = _read(ROCM_STUDIO)
+ assert paths["license"] in text, "the AGPLv3 text must be staged where the guard reads it"
+ assert "-m unsloth_branding --verify" in text, "the build must run the branding guard"
+
+
+def test_the_branding_chain_matches_the_cuda_studio_image():
+ """Same assets, same destinations, same disable/lock pairs: the ROCm image is
+ the same product with a different torch, and the guard checks the same paths."""
+
+ def branding(path: Path):
+ copies = {
+ (tuple(src), dest)
+ for stage, src, dest in _copies(path)
+ if not stage and all(s.startswith("jupyter/") for s in src)
+ }
+ locks = sorted(re.findall(r"jupyter labextension (?:disable|lock) \S+", _read(path)))
+ return copies, locks
+
+ assert branding(ROCM_STUDIO) == branding(CUDA_STUDIO)
+
+
+# ── the notebooks and their tooling ──────────────────────────────────────────
+
+
+def test_the_notebook_tooling_matches_the_cuda_core_image():
+ def helpers(path: Path) -> set[str]:
+ (src,) = [src for _, src, dest in _copies(path) if dest == "/opt/unsloth-nb/"]
+ return set(src)
+
+ assert helpers(ROCM_STUDIO) == helpers(
+ CUDA_BASE
+ ), "a notebook helper added to one image and not the other"
+ cuda_env, rocm_env = _env(CUDA_BASE), _env(ROCM_STUDIO)
+ assert rocm_env["IPYTHONDIR"] == cuda_env["IPYTHONDIR"]
+ for env in (cuda_env, rocm_env):
+ assert env["PATH"].startswith(
+ "/opt/unsloth-nb/bin:"
+ ), "the pip/uv shim has to sit ahead of the venv on PATH or install cells clobber torch"
+
+
+def test_the_notebooks_are_baked_where_the_sync_script_looks():
+ text = _read(ROCM_STUDIO)
+ assert "https://github.com/unslothai/notebooks" in text
+ assert "/opt/unsloth-notebooks/.unsloth_template_commit" in text
+ assert "/opt/unsloth-notebooks" in _read(DOCKER / "unsloth_sync_notebooks.sh")
+ assert "ARG UNSLOTH_NOTEBOOKS_REF" in text, "CI has to be able to pin the notebooks commit"
+ # the AMD-* set is the point of the image, so an upstream ref without one fails the build
+ assert "grep -c '^AMD-'" in text
+
+
+# ── the services ───────────────────────────────────────────────────────
+
+
+def test_every_supervisord_program_is_installed_by_the_dockerfile():
+ conf = _read(SUPERVISORD)
+ commands = re.findall(r"^command=(\S+)", conf, re.M)
+ assert commands, "supervisord.conf lost its programs"
+ dests = {dest for _, _, dest in _copies(ROCM_STUDIO)}
+ chmod = " ".join(
+ r for r in _instructions(ROCM_STUDIO, "RUN") if r.startswith("chmod +x /usr/local/bin/")
+ )
+ apt = " ".join(r for r in _instructions(ROCM_STUDIO, "RUN") if "apt-get install" in r)
+ for command in commands:
+ if command.startswith("/usr/local/bin/"):
+ assert (
+ command in dests
+ ), f"supervisord runs {command}, which the Dockerfile never copies"
+ assert command in chmod, f"{command} is copied but not made executable"
+ elif command == "/usr/sbin/sshd":
+ # supervisord.conf is shared with the CUDA image, which does run sshd.
+ # This image leaves openssh-server out, so the program has no binary and
+ # must never be started: studio_launch.sh's `command -v sshd` gate keeps
+ # UNSLOTH_ENABLE_SSHD false, and the image default agrees.
+ assert "openssh-server" not in apt
+ assert "command -v sshd >/dev/null 2>&1" in _read(LAUNCH)
+ assert _env(ROCM_STUDIO)["UNSLOTH_ENABLE_SSHD"] == "false"
+ elif command == "jupyter":
+ pass # the venv's, pinned above
+ else:
+ raise AssertionError(f"unexpected supervisord command {command}")
+ assert "supervisor" in apt.split()
+ (conf_dest,) = [dest for _, src, dest in _copies(ROCM_STUDIO) if src == ["supervisord.conf"]]
+ assert f"exec supervisord -c {conf_dest}" in _read(LAUNCH)
+
+
+def test_the_launcher_is_the_command_and_the_ports_are_exposed():
+ (cmd,) = _instructions(ROCM_STUDIO, "CMD")
+ assert json.loads(cmd) == ["/usr/local/bin/unsloth-studio-launch"]
+ assert "unsloth-studio-home" not in cmd, "the home link moved into the entrypoint"
+ env = _env(ROCM_STUDIO)
+ (expose,) = _instructions(ROCM_STUDIO, "EXPOSE")
+ # no 22: this image has no sshd, unlike the CUDA one
+ assert set(expose.split()) == {env["UNSLOTH_STUDIO_PORT"], env["JUPYTER_PORT"]}
+ # supervisord.conf expands these before the launcher has exported anything
+ for name in ("JUPYTER_PORT", "UNSLOTH_ENABLE_SSHD", "UNSLOTH_STUDIO_STOP_WAIT_S"):
+ assert name in env, f"supervisord's %(ENV_{name})s needs an image default"
+
+
+def test_login_shells_keep_the_rocm_variables():
+ """studio_launch.sh writes the container's env into /etc/profile.d, filtered by
+ prefix. Nothing here arrives over SSH, but a JupyterLab terminal and `docker exec
+ -it ... bash -l` are both login shells, and `docker run -e` values reach neither
+ otherwise. The image's ROCBLAS_USE_HIPBLASLT and a user's HSA_OVERRIDE_GFX_VERSION
+ have to make it through, or a terminal trains on a different ROCm configuration
+ than the Studio and Jupyter processes."""
+ match = re.search(r'keep\s*=\s*re\.compile\(r"(.*?)"\)', _read(LAUNCH))
+ assert match, "the profile.d keep pattern moved"
+ keep = re.compile(match.group(1))
+ for var in (
+ "ROCBLAS_USE_HIPBLASLT",
+ "HSA_OVERRIDE_GFX_VERSION",
+ "HIP_VISIBLE_DEVICES",
+ "ROCR_VISIBLE_DEVICES",
+ "ROCM_HOME",
+ "CUDA_VISIBLE_DEVICES",
+ "PATH",
+ ):
+ assert keep.search(var), f"{var} would not reach an SSH login shell"
+ assert not keep.search("HOME") and not keep.search("LANG")
+
+
+# ── the entrypoint hooks the services depend on ──────────────────────────────
+
+
+def test_the_entrypoint_links_the_studio_home_before_anything_reads_it():
+ """supervisord starts Studio from $UNSLOTH_STUDIO_HOME/bin/unsloth, a link into
+ the app dir that unsloth-studio-home creates; a volume mounted on the home hides
+ the build-time link, so the entrypoint has to run the linker on every start,
+ before the GPU checks that may exit. Mirrors entrypoint.sh on the CUDA image."""
+ body = _read(ENTRYPOINT)
+ linker = body.index("/usr/local/bin/unsloth-studio-home")
+ assert linker < body.index("Check 1"), "the home link has to precede the GPU checks"
+ assert "/usr/local/bin/unsloth-studio-home" in _read(CUDA_ENTRYPOINT)
+ # the studio image reinstalls the entrypoint, since the published base predates the hooks
+ (base_dest,) = [dest for _, src, dest in _copies(ROCM_BASE) if src == ["entrypoint-rocm.sh"]]
+ assert (base_dest,) == tuple(
+ dest for _, src, dest in _copies(ROCM_STUDIO) if src == ["entrypoint-rocm.sh"]
+ )
+ assert not _instructions(ROCM_STUDIO, "ENTRYPOINT"), "the base ENTRYPOINT is inherited"
+
+
+def test_the_entrypoint_syncs_the_notebooks_before_every_exec():
+ body = _read(ENTRYPOINT)
+ assert "/usr/local/bin/unsloth-sync-notebooks" in body
+ assert "/usr/local/bin/unsloth-sync-notebooks" in _read(CUDA_ENTRYPOINT)
+ execs = [m.start() for m in re.finditer(r'^\s*exec "\$@"\s*$', body, re.M)]
+ assert len(execs) >= 2, "the skip path and the checked path both exec the command"
+ for pos in execs:
+ preceding = body[:pos].rstrip().splitlines()[-1].strip()
+ assert (
+ preceding == "sync_notebooks"
+ ), f"exec at offset {pos} is not preceded by sync_notebooks but by {preceding!r}"
+
+
+# ── the publisher ────────────────────────────────────────────────────────────
+
+
+def test_the_publisher_passes_every_build_arg_the_final_stage_declares():
+ """Each ARG after the final FROM is a ref a RUN layer is keyed on. One the
+ publisher leaves at its default bakes a mutable 'main' that docker matches on
+ the next run, so the published image would carry the first build's bits."""
+ import yaml
+
+ text = _read(ROCM_STUDIO)
+ final = text[text.rindex("\nFROM ") :]
+ declared = {m.group(1) for m in re.finditer(r"^ARG (\w+)=", final, re.M)}
+ assert declared, "no ARG after the final FROM"
+
+ wf = yaml.safe_load(_read(WORKFLOW))
+ step = next(s for s in wf["jobs"]["build-studio"]["steps"] if s.get("id") == "build")
+ assert step["with"]["file"] == "./docker/Dockerfile.studio-rocm"
+ passed = dict(ln.split("=", 1) for ln in step["with"]["build-args"].splitlines() if ln)
+ assert declared <= set(passed), declared - set(passed)
+ # the base by digest, so a newer run's :latest cannot slip under this build
+ assert "@${{ needs.build.outputs.digest }}" in passed["BASE_IMAGE"]
+ for name in declared:
+ assert passed[name].startswith("${{ needs.prepare.outputs."), (name, passed[name])
+
+
+# ── the build context ────────────────────────────────────────────────────────
+
+
+def test_every_copy_source_is_allowed_by_the_dockerignore():
+ """docker/.dockerignore denies everything and allow-lists by name, so a file
+ COPY'd here but not listed there fails the build with 'not found'."""
+ allowed = [ln[1:].strip() for ln in _read(DOCKERIGNORE).splitlines() if ln.startswith("!")]
+
+ def is_allowed(source: str) -> bool:
+ for pattern in allowed:
+ if pattern == source:
+ return True
+ if pattern.endswith("/**") and source.startswith(pattern[:-3] + "/"):
+ return True
+ return False
+
+ for stage, sources, _ in _copies(ROCM_STUDIO):
+ if stage:
+ continue
+ for source in sources:
+ assert is_allowed(source), f"{source} is not allow-listed in docker/.dockerignore"