Merge pull request #169 from AMDResearch/develop

chore: merge develop to main

Author: KerwinTsaiii

README.md

@@ -42,7 +42,7 @@ The simplest way to deploy AUP Learning Cloud on a single machine in a developme
 
 ```bash
 # Ryzen AI APU only: OEM kernel for ROCm on Ubuntu 24.04 (reboot required)
-sudo apt update && sudo apt install linux-image-6.14.0-1018-oem
+sudo apt update && sudo apt install linux-oem-6.14
 
 # Install Docker
 curl -fsSL https://get.docker.com | sh

auplc_installer/rocm.py

@@ -58,8 +58,8 @@ def _wait_daemonset_ready(name: str) -> None:
 
 
 def _patch_image_pull_policy(daemonset: str) -> None:
-    """For offline mode: avoid pulling the device plugin image from a registry."""
-    patch = '[{"op":"replace","path":"/spec/template/spec/containers/0/imagePullPolicy","value":"IfNotPresent"}]'
+    """Avoid pulling ROCm DaemonSet images when they already exist locally."""
+    patch = '[{"op":"add","path":"/spec/template/spec/containers/0/imagePullPolicy","value":"IfNotPresent"}]'
     run(
         [
             "kubectl",
@@ -90,7 +90,6 @@ def deploy_rocm_gpu_device_plugin(*, offline_mode: bool, bundle_dir: Path | None
                     str(bundle_dir / "manifests/k8s-ds-amdgpu-dp.yaml"),
                 ]
             )
-            _patch_image_pull_policy("amdgpu-device-plugin-daemonset")
         else:
             url = (
                 "https://raw.githubusercontent.com/ROCm/k8s-device-plugin/"
@@ -101,9 +100,11 @@ def deploy_rocm_gpu_device_plugin(*, offline_mode: bool, bundle_dir: Path | None
             verify_sha256(tmp, ROCM_DEVICE_PLUGIN_SHA256)
             run(["kubectl", "create", "-f", tmp])
             os.remove(tmp)
-        _wait_daemonset_ready("amdgpu-device-plugin-daemonset")
         log("Successfully deployed ROCm GPU device plugin.")
 
+    _patch_image_pull_policy("amdgpu-device-plugin-daemonset")
+    _wait_daemonset_ready("amdgpu-device-plugin-daemonset")
+
     deploy_rocm_gpu_node_labeller(offline_mode=offline_mode, bundle_dir=bundle_dir)
 
 
@@ -117,28 +118,27 @@ def deploy_rocm_gpu_node_labeller(*, offline_mode: bool, bundle_dir: Path | None
     log("Deploying ROCm GPU node labeller...")
     if _exists_daemonset("amdgpu-labeller-daemonset"):
         log("ROCm GPU node labeller already exists.")
-        return
-
-    if offline_mode and bundle_dir is not None:
-        run(
-            [
-                "kubectl",
-                "create",
-                "-f",
-                str(bundle_dir / "manifests/k8s-ds-amdgpu-labeller.yaml"),
-            ]
-        )
-        _patch_image_pull_policy("amdgpu-labeller-daemonset")
     else:
-        url = (
-            "https://raw.githubusercontent.com/ROCm/k8s-device-plugin/"
-            f"{ROCM_DEVICE_PLUGIN_COMMIT}/k8s-ds-amdgpu-labeller.yaml"
-        )
-        tmp = "/tmp/k8s-ds-amdgpu-labeller.yaml"
-        run(["wget", url, "-O", tmp])
-        verify_sha256(tmp, ROCM_LABELLER_SHA256)
-        run(["kubectl", "create", "-f", tmp])
-        os.remove(tmp)
+        if offline_mode and bundle_dir is not None:
+            run(
+                [
+                    "kubectl",
+                    "create",
+                    "-f",
+                    str(bundle_dir / "manifests/k8s-ds-amdgpu-labeller.yaml"),
+                ]
+            )
+        else:
+            url = (
+                "https://raw.githubusercontent.com/ROCm/k8s-device-plugin/"
+                f"{ROCM_DEVICE_PLUGIN_COMMIT}/k8s-ds-amdgpu-labeller.yaml"
+            )
+            tmp = "/tmp/k8s-ds-amdgpu-labeller.yaml"
+            run(["wget", url, "-O", tmp])
+            verify_sha256(tmp, ROCM_LABELLER_SHA256)
+            run(["kubectl", "create", "-f", tmp])
+            os.remove(tmp)
+        log("Successfully deployed ROCm GPU node labeller.")
 
+    _patch_image_pull_policy("amdgpu-labeller-daemonset")
     _wait_daemonset_ready("amdgpu-labeller-daemonset")
-    log("Successfully deployed ROCm GPU node labeller.")

deploy/ansible/playbooks/pb-pxe-controller.yml

@@ -72,8 +72,8 @@
     pxe_apt_mirror: "http://tw.archive.ubuntu.com/ubuntu"
 
     pxe_rootfs_packages:
-      - linux-image-6.14.0-1018-oem
-      - linux-headers-6.14.0-1018-oem
+      - linux-image-oem-6.14
+      - linux-headers-oem-6.14
       - initramfs-tools
       - linux-firmware
       - nfs-common

deploy/ansible/roles/pxe_controller/defaults/main.yml

@@ -106,8 +106,8 @@ pxe_web_port: 8080
 pxe_ubuntu_codename: "noble"
 
 pxe_rootfs_packages:
-  - linux-image-6.14.0-1018-oem
-  - linux-headers-6.14.0-1018-oem
+  - linux-image-oem-6.14
+  - linux-headers-oem-6.14
   - initramfs-tools
   - linux-firmware
   - nfs-common

deploy/docs/images/software-stack.png

@@ -94,3 +94,5 @@ COPY --from=runtime-status-builder --chown=1000:100 /build/runtime/notebook/jupy
 
 RUN python3 -mpip install --no-cache-dir /tmp/auplc-jupyterlab-runtime-status && \
     rm -rf /tmp/auplc-jupyterlab-runtime-status
+
+WORKDIR /home/jovyan

dockerfiles/Base/Dockerfile.cpu

@@ -129,6 +129,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
   run-one \
   libatomic1 \
   unzip \
+  libavutil-dev \
   && apt-get clean \
   && rm -rf /var/lib/apt/lists/*
 
@@ -266,6 +267,6 @@ RUN echo '#!/bin/bash' > /entrypoint.sh && \
 EXPOSE 8888
 
 USER $NB_UID
-WORKDIR /opt/workspace
+WORKDIR /home/jovyan
 
 CMD ["/bin/bash", "/entrypoint.sh"]

dockerfiles/Base/Dockerfile.rocm

@@ -86,6 +86,32 @@ docker build \
 docker build -t ghcr.io/amdresearch/auplc-default:latest --file Dockerfile.cpu .
 ```
 
+## Resource Path Contract
+
+Resource metadata in `runtime/values.yaml` can set `defaultPath` for the
+initial landing path inside the container. It controls where JupyterLab or
+code-server opens first. It is not a security boundary, an access boundary, or a
+runtime guarantee that the directory exists.
+
+The Hub chooses the target path in this order:
+
+1. Custom Repo clone path, when the user supplies a repository.
+2. Resource `defaultPath`, when configured.
+3. The image or single-user application default, normally the image `WORKDIR`.
+
+For official images, keep `custom.resources.metadata.<resource>.defaultPath` in
+sync with the image `WORKDIR`. Check the local image contracts with:
+
+```bash
+make -C dockerfiles verify-resource-contracts
+```
+
+That verifier checks the official image contract. Runtime spawning still does
+not check path existence for arbitrary or custom images. If an environment
+points at a custom image, make sure the configured `defaultPath` exists in that
+image, or omit `defaultPath` to let the image `WORKDIR` control the initial
+folder.
+
 ## Generic Code Images
 
 The base images remain the foundation for notebook and coding environments. Generic code-server images are built separately from `dockerfiles/Code/`:

dockerfiles/Base/README.md

@@ -38,7 +38,7 @@ those tools to Base notebook images or Course images. CPU and GPU Code images
 are built from the same Dockerfile and differ only by `BASE_IMAGE`, so the Code
 layer stays consistent across hardware targets.
 
-The default Hub resource keys are `code-cpu` and `code-gpu`. Code-server launch behavior is configured through `custom.resources.metadata.<resource>.launchMode: code-server`, alongside the same `custom.resources.images`, `custom.resources.requirements`, and `custom.teams.mapping` model as notebook resources in `runtime/values.yaml`.
+The default Hub resource keys are `code-cpu` and `code-gpu`. Code-server launch behavior is configured through `custom.resources.metadata.<resource>.launchMode: code-server`, alongside the same `custom.resources.images`, `custom.resources.requirements`, `custom.resources.metadata.<resource>.defaultPath`, and `custom.teams.mapping` model as notebook resources in `runtime/values.yaml`.
 
 ## Build Commands
 
@@ -86,7 +86,7 @@ images continue to share one package set and the Dockerfile remains small.
 The start script launches:
 
 ```bash
-code-server --auth none --bind-addr 127.0.0.1:8889 --ignore-last-opened "${AUPLC_CODE_WORKDIR:-/home/jovyan}"
+code-server --auth none --bind-addr 127.0.0.1:8889 --ignore-last-opened "${AUPLC_CODE_WORKDIR:-$(pwd)}"
 nginx -c /tmp/auplc-code-server-nginx.conf -g 'daemon off;'
 ```
 
@@ -96,6 +96,14 @@ code-server on loopback. The proxy must preserve the full browser `Host` value
 with `X-Forwarded-Host` so code-server's WebSocket origin check succeeds behind
 JupyterHub and NodePort-style local URLs.
 
+`defaultPath` is the initial landing path for a resource. The target path is
+chosen in this order: Custom Repo clone path, resource `defaultPath`, then the
+image or single-user application default, normally the image `WORKDIR`. Omitted
+and `null` `defaultPath` values do not force a Hub landing override; empty
+strings are invalid; `/` means land at the container root. This setting doesn't
+limit what users can access. It only selects the first workspace shown by the
+application.
+
 Git, Node.js LTS, `npm`, `npx`, `corepack`, pinned `pnpm`, TypeScript/frontend
 helpers, Pixi, and native build tools are installed in the image so cloned
 projects can use source control, frontend workflows, sudo-free user package
@@ -108,6 +116,13 @@ home directory instead of `/usr/local`: `NPM_CONFIG_PREFIX` defaults to
 This lets users install small project CLIs with commands such as
 `npm install -g cowsay` without sudo or write access to system directories.
 
+For code-server's outgoing link protection, the Hub automatically injects the
+current public Hub host into `AUPLC_CODE_TRUSTED_DOMAINS` so the built-in
+Back-to-Hub action can open `/hub/home` without an external-site confirmation.
+Deployments that intentionally open additional trusted sites can set
+`custom.codeServer.extraTrustedDomains` to host/domain entries such as
+`docs.example.edu`; do not include URL schemes or paths.
+
 Pixi is provided as the sudo-free, apt-like package manager for user-space
 native tools and project environments. The image writes `/etc/pixi/config.toml`
 so requests for `https://conda.anaconda.org/conda-forge` are redirected to the
@@ -138,7 +153,28 @@ downgrading a user-installed newer copy.
 
 `--auth none` is acceptable only because JupyterHub and the JupyterHub proxy remain the authentication boundary. The user pod's port `8888` must stay private to the Hub/proxy path and must not be exposed directly through an unauthenticated service, ingress, or port-forward shared with untrusted users.
 
-When users provide a Git repository on the spawn form, the existing init-container clone flow is reused. For resources with `launchMode: code-server`, the spawner points `AUPLC_CODE_WORKDIR` and the code-server `folder` URL parameter at the cloned directory so code-server opens the repository workspace. The launcher also passes `--ignore-last-opened` so a persisted previous workspace cannot override the requested folder.
+When users provide a Git repository on the spawn form, the existing init-container clone flow is reused. For resources with `launchMode: code-server`, the spawner points `AUPLC_CODE_WORKDIR` at the cloned directory or explicit resource target path, and the launcher starts code-server with that folder so it opens the requested workspace. If neither Custom Repo nor `defaultPath` is set, the launcher opens the image `WORKDIR`. The launcher also passes `--ignore-last-opened` so a persisted previous workspace cannot override the requested folder.
+
+A direct code-server URL with `?folder=<path>` works when the browser reaches
+the proxied code-server root route. Hub spawn completion, however, redirects the
+browser to the server base URL, and code-server doesn't consume
+`JUPYTERHUB_DEFAULT_URL` by itself. AUPLC therefore keeps `AUPLC_CODE_WORKDIR` as
+the reliable adapter between Hub resource selection and the code-server process.
+The local proof is recorded in
+`.sisyphus/evidence/task-1-codeserver-default-url-proof.md`.
+
+Official Code images are checked by the resource contract verifier:
+
+```bash
+make -C dockerfiles verify-resource-contracts
+```
+
+The verifier checks official image metadata, image `WORKDIR`, path existence,
+and the code-server launcher contract. Runtime spawning doesn't check path
+existence for arbitrary or custom images. If a custom code image sets a
+`defaultPath`, create that path in the image or code-server may show its own
+landing error. If the image already declares the desired `WORKDIR`, omit
+`defaultPath` to preserve it.
 
 ## Extensions
 

dockerfiles/Code/README.md

@@ -10,10 +10,12 @@ export NPM_CONFIG_PREFIX="${NPM_CONFIG_PREFIX:-${HOME:-/home/jovyan}/.local}"
 public_port="${PORT:-8888}"
 code_server_port="${AUPLC_CODE_SERVER_PORT:-8889}"
 service_prefix="${JUPYTERHUB_SERVICE_PREFIX:-/}"
-workdir="${AUPLC_CODE_WORKDIR:-/home/jovyan}"
+# Without a Hub-provided launch override, open code-server in the image WORKDIR.
+workdir="${AUPLC_CODE_WORKDIR:-$(pwd)}"
 extensions_list="${AUPLC_CODE_EXTENSIONS_LIST:-/opt/auplc/extensions/extensions.txt}"
 local_extensions_dir="${AUPLC_CODE_LOCAL_EXTENSIONS_DIR:-/opt/auplc/extensions/local}"
 extensions_dir="${AUPLC_CODE_EXTENSIONS_DIR:-/home/jovyan/.local/share/code-server/extensions}"
+trusted_domains="${AUPLC_CODE_TRUSTED_DOMAINS:-}"
 
 mkdir -p "${NPM_CONFIG_PREFIX}/bin"
 mkdir -p "${PIXI_HOME}/bin"
@@ -49,6 +51,28 @@ seed_builtin_extensions() {
   fi
 }
 
+trim() {
+  local value="$1"
+  value="${value#"${value%%[![:space:]]*}"}"
+  value="${value%"${value##*[![:space:]]}"}"
+  printf '%s' "${value}"
+}
+
+build_trusted_domain_args() {
+  local domains_csv="$1"
+  local -n output_args="$2"
+  local -a domains=()
+  local domain
+
+  IFS=',' read -ra domains <<<"${domains_csv}"
+  for domain in "${domains[@]}"; do
+    domain="$(trim "${domain}")"
+    if [ -n "${domain}" ]; then
+      output_args+=(--link-protection-trusted-domains "${domain}")
+    fi
+  done
+}
+
 case "${service_prefix}" in
   /*) ;;
   *) service_prefix="/${service_prefix}" ;;
@@ -65,6 +89,8 @@ nginx_conf="/tmp/auplc-code-server-nginx.conf"
 redirect_block=""
 
 seed_builtin_extensions
+trusted_domain_args=()
+build_trusted_domain_args "${trusted_domains}" trusted_domain_args
 
 if [ "${service_prefix}" != "/" ]; then
   redirect_block="
@@ -120,6 +146,7 @@ code-server \
   --auth none \
   --bind-addr "127.0.0.1:${code_server_port}" \
   --extensions-dir "${extensions_dir}" \
+  "${trusted_domain_args[@]}" \
   --ignore-last-opened \
   "${workdir}" &
 code_server_pid="$!"