feat(docker): add BINARY_SOURCE selector for prebuilt Rust binaries

deploy/docker/Dockerfile.images

@@ -22,6 +22,12 @@ ARG K9S_VERSION=v0.50.18
 ARG HELM_VERSION=v3.17.3
 ARG NVIDIA_CONTAINER_TOOLKIT_VERSION=1.18.2-1
 
+# OS-128 Phase 4: select binary source for final images. `build` (default)
+# compiles Rust inside the builder stages below; `prebuilt` consumes binaries
+# staged at deploy/docker/.build/prebuilt-binaries/<arch>/. Declared at global
+# scope so BuildKit can substitute it in `FROM *-binary-${BINARY_SOURCE}`.
+ARG BINARY_SOURCE=build
+
 # ---------------------------------------------------------------------------
 # Shared Rust build stages
 # ---------------------------------------------------------------------------
@@ -178,10 +184,43 @@ RUN --mount=type=cache,id=cargo-registry-${TARGETARCH},sharing=locked,target=/us
     mkdir -p /build/out && \
     cp "$(cross_output_dir release)/openshell-sandbox" /build/out/
 
+# ---------------------------------------------------------------------------
+# Binary source selector (OS-128 Phase 4)
+# ---------------------------------------------------------------------------
+# `BINARY_SOURCE` is declared at global scope above (near the other version
+# ARGs). `build` (default) routes through the Rust builder stages above;
+# `prebuilt` routes through the scratch stages below, which COPY from
+#   deploy/docker/.build/prebuilt-binaries/<arch>/openshell-{gateway,sandbox}
+# in the build context. Prebuilt-artifact production + end-to-end workflow
+# wiring land in later Phase 4 PRs; the `prebuilt` path is inert unless a
+# caller sets BINARY_SOURCE=prebuilt and stages the binaries.
+
+FROM gateway-builder AS gateway-binary-build
+# Inherits /build/out/openshell-gateway from the cargo build stage.
+
+FROM scratch AS gateway-binary-prebuilt
+ARG TARGETARCH
+# --chmod=755 preserves the executable bit through actions/upload-artifact +
+# download-artifact, which strip exec perms during the roundtrip.
+COPY --chmod=755 deploy/docker/.build/prebuilt-binaries/${TARGETARCH}/openshell-gateway /build/out/openshell-gateway
+
+FROM gateway-binary-${BINARY_SOURCE} AS gateway-binary
+
+FROM supervisor-builder AS supervisor-binary-build
+# Inherits /build/out/openshell-sandbox from the cargo build stage.
+
+FROM scratch AS supervisor-binary-prebuilt
+ARG TARGETARCH
+# --chmod=755 preserves the executable bit through actions/upload-artifact +
+# download-artifact, which strip exec perms during the roundtrip.
+COPY --chmod=755 deploy/docker/.build/prebuilt-binaries/${TARGETARCH}/openshell-sandbox /build/out/openshell-sandbox
+
+FROM supervisor-binary-${BINARY_SOURCE} AS supervisor-binary
+
 # Minimal extraction stage for fast-deploy: exports only the supervisor
 # binary (~20-40 MB) instead of the entire build environment (~968 MB).
 FROM scratch AS supervisor-output
-COPY --from=supervisor-builder /build/out/openshell-sandbox /openshell-sandbox
+COPY --from=supervisor-binary /build/out/openshell-sandbox /openshell-sandbox
 
 # ---------------------------------------------------------------------------
 # Final gateway image
@@ -197,7 +236,7 @@ RUN useradd --create-home --user-group openshell
 
 WORKDIR /app
 
-COPY --from=gateway-builder /build/out/openshell-gateway /usr/local/bin/
+COPY --from=gateway-binary /build/out/openshell-gateway /usr/local/bin/
 
 RUN mkdir -p /build/crates/openshell-server
 COPY --chmod=755 crates/openshell-server/migrations /build/crates/openshell-server/migrations
@@ -222,7 +261,7 @@ RUN useradd --create-home --user-group openshell
 
 WORKDIR /app
 
-COPY --from=supervisor-builder /build/out/openshell-sandbox /usr/local/bin/
+COPY --from=supervisor-binary /build/out/openshell-sandbox /usr/local/bin/
 
 USER openshell
 
@@ -292,7 +331,7 @@ COPY --from=nvidia-container-toolkit /usr/bin/nvidia-cdi-hook /usr/bin/
 COPY --from=nvidia-container-toolkit /usr/bin/nvidia-container-runtime /usr/bin/
 COPY --from=nvidia-container-toolkit /usr/bin/nvidia-ctk /usr/bin/
 COPY --from=nvidia-container-toolkit /etc/nvidia-container-runtime /etc/nvidia-container-runtime
-COPY --from=supervisor-builder /build/out/openshell-sandbox /opt/openshell/bin/openshell-sandbox
+COPY --from=supervisor-binary /build/out/openshell-sandbox /opt/openshell/bin/openshell-sandbox
 
 RUN mkdir -p /var/lib/rancher/k3s/server/manifests \
              /var/lib/rancher/k3s/server/static/charts \

tasks/scripts/docker-build-image.sh

@@ -152,6 +152,25 @@ if [[ -n "${CI:-}" ]]; then
 	CODEGEN_ARGS=(--build-arg "CARGO_CODEGEN_UNITS=1")
 fi
 
+# OS-128 Phase 4: opt in to consuming pre-built Rust binaries instead of
+# compiling inside Docker. Default path (`build`) is unchanged. When
+# USE_PREBUILT_BINARIES=true, the Dockerfile's BINARY_SOURCE=prebuilt stages
+# are selected, which COPY from deploy/docker/.build/prebuilt-binaries/<arch>/
+# in the build context. Callers must stage the binaries before invoking.
+BINARY_SOURCE_ARGS=()
+if [[ "${USE_PREBUILT_BINARIES:-}" == "true" ]]; then
+  case "${TARGET}" in
+    gateway|supervisor|cluster|supervisor-output)
+      if [[ ! -d deploy/docker/.build/prebuilt-binaries ]]; then
+        echo "Error: USE_PREBUILT_BINARIES=true but deploy/docker/.build/prebuilt-binaries/ does not exist" >&2
+        echo "  Stage binaries at deploy/docker/.build/prebuilt-binaries/<arch>/openshell-{gateway,sandbox}" >&2
+        exit 1
+      fi
+      BINARY_SOURCE_ARGS=(--build-arg "BINARY_SOURCE=prebuilt")
+      ;;
+  esac
+fi
+
 TAG_ARGS=()
 if [[ "${IS_FINAL_IMAGE}" == "1" ]]; then
 	TAG_ARGS=(-t "${IMAGE_NAME}:${IMAGE_TAG}")
@@ -190,6 +209,7 @@ ce_build \
 	${VERSION_ARGS[@]+"${VERSION_ARGS[@]}"} \
 	${K3S_ARGS[@]+"${K3S_ARGS[@]}"} \
 	${CODEGEN_ARGS[@]+"${CODEGEN_ARGS[@]}"} \
+	${BINARY_SOURCE_ARGS[@]+"${BINARY_SOURCE_ARGS[@]}"} \
 	${FEATURE_ARGS[@]+"${FEATURE_ARGS[@]}"} \
 	--build-arg "CARGO_TARGET_CACHE_SCOPE=${CARGO_TARGET_CACHE_SCOPE}" \
 	-f "${DOCKERFILE}" \