User Story
As an operator or downstream packager deploying OpenShell's supervisor container in an environment with specific registry-trust, compliance, or support constraints (e.g. a registry allowlist, a FIPS-validated base image requirement, or an internal support SLA tied to a specific image vendor), I want to override the supervisor's base image at build time, so that I can satisfy my environment's constraints without forking the Dockerfile.
Problem Statement
deploy/docker/Dockerfile.gateway already exposes its base image as a build ARG:
ARG GATEWAY_BASE_IMAGE=gcr.io/distroless/cc-debian13:nonroot@sha256:54df941ed0d06a1bd95ef5e0ce391fd8d9f94b64782dc9a60062727849ee3f97
FROM ${GATEWAY_BASE_IMAGE} AS gatewaydeploy/docker/Dockerfile.supervisor does not. It hardcodes:
FROM gcr.io/distroless/base-nossl-debian13@sha256:af5cb8dd589b8520b8c06bebb9efb73d7e16406cab58e85c51761fff49d370a0 AS supervisor
There is no equivalent override point, so substituting an alternate base image for the supervisor today requires forking/patching the Dockerfile.
Impact / Why This Matters
Downstream consumers building in a registry-restricted environment, needing a FIPS-validated base, or needing a base image they can patch/support on their own schedule currently have to maintain a forked Dockerfile to get a different supervisor base image. A fork drifts from upstream over time (missed binary/build-step changes) and duplicates this maintenance burden across every downstream consumer who needs it. The gateway already solves this cleanly; the supervisor's inconsistency with that pattern is the actual gap, not a missing capability invented from scratch.
Proposed Design
Add a build ARG to deploy/docker/Dockerfile.supervisor (e.g. SUPERVISOR_BASE_IMAGE) defaulting to the current pinned image/digest, mirroring GATEWAY_BASE_IMAGE's existing pattern. This is purely additive: no default behavior change, and no change to published images unless a builder explicitly overrides the ARG. Exact ARG naming/defaulting mechanics are left to the implementing PR.
Acceptance Criteria
Alternatives Considered
- Status quo (hardcoded base, consumers fork the Dockerfile if they need something else) — rejected: duplicates maintenance effort per downstream consumer and drifts from upstream over time.
- Change the default base image itself (e.g. to Red Hat's Project Hummingbird
registry.access.redhat.com/hi/core-runtime) — rejected for now: a direct comparison (skopeo inspect against both) shows Hummingbird's core-runtime image is larger and has more layers than the current default (12.82 MB / 23 layers vs. the current base's 5.94 MB / 14 layers), and its image config sets CMD ["/bin/bash"], suggesting a shell may be present where the current distroless base has none. It is not a demonstrated improvement, and changing the project's default base is a larger decision needing broader maintainer alignment, not a mechanical change.
- Make the sandbox image configurable the same way (
deploy/docker/Dockerfile.sandbox, FROM scratch) — rejected: the sandbox image has no runtime base to swap, it's a bare static binary with no base at all, so this axis doesn't apply there.
Agent Investigation
Confirmed by reading the current Dockerfiles directly and inspecting published images/registries with skopeo inspect:
deploy/docker/Dockerfile.gateway already has the GATEWAY_BASE_IMAGE ARG described above.deploy/docker/Dockerfile.supervisor has no equivalent ARG.deploy/docker/Dockerfile.sandbox is FROM scratch with no base image to parameterize.- Published
ghcr.io/nvidia/openshell/supervisor:dev is 15 layers / ~19.6 MB total; its base (distroless/base-nossl-debian13) is 14 layers / ~5.94 MB.
registry.access.redhat.com/hi/core-runtime:latest (Project Hummingbird's comparable minimal base) is 23 layers / ~12.82 MB, with image config CMD ["/bin/bash"].
No RFC needed — this is a small, additive, non-breaking build-configuration change, not a change to OpenShell's architecture or default behavior.
User Story
As an operator or downstream packager deploying OpenShell's supervisor container in an environment with specific registry-trust, compliance, or support constraints (e.g. a registry allowlist, a FIPS-validated base image requirement, or an internal support SLA tied to a specific image vendor), I want to override the supervisor's base image at build time, so that I can satisfy my environment's constraints without forking the Dockerfile.
Problem Statement
deploy/docker/Dockerfile.gatewayalready exposes its base image as a build ARG:deploy/docker/Dockerfile.supervisordoes not. It hardcodes:FROM gcr.io/distroless/base-nossl-debian13@sha256:af5cb8dd589b8520b8c06bebb9efb73d7e16406cab58e85c51761fff49d370a0 AS supervisorThere is no equivalent override point, so substituting an alternate base image for the supervisor today requires forking/patching the Dockerfile.
Impact / Why This Matters
Downstream consumers building in a registry-restricted environment, needing a FIPS-validated base, or needing a base image they can patch/support on their own schedule currently have to maintain a forked Dockerfile to get a different supervisor base image. A fork drifts from upstream over time (missed binary/build-step changes) and duplicates this maintenance burden across every downstream consumer who needs it. The gateway already solves this cleanly; the supervisor's inconsistency with that pattern is the actual gap, not a missing capability invented from scratch.
Proposed Design
Add a build ARG to
deploy/docker/Dockerfile.supervisor(e.g.SUPERVISOR_BASE_IMAGE) defaulting to the current pinned image/digest, mirroringGATEWAY_BASE_IMAGE's existing pattern. This is purely additive: no default behavior change, and no change to published images unless a builder explicitly overrides the ARG. Exact ARG naming/defaulting mechanics are left to the implementing PR.Acceptance Criteria
deploy/docker/Dockerfile.supervisoraccepts a build ARG for its base image, with the current image pinned as the default.GATEWAY_BASE_IMAGEoverride is documented (e.g.architecture/build.md) is updated to document the supervisor's new equivalent consistently.Alternatives Considered
registry.access.redhat.com/hi/core-runtime) — rejected for now: a direct comparison (skopeo inspectagainst both) shows Hummingbird'score-runtimeimage is larger and has more layers than the current default (12.82 MB / 23 layers vs. the current base's 5.94 MB / 14 layers), and its image config setsCMD ["/bin/bash"], suggesting a shell may be present where the current distroless base has none. It is not a demonstrated improvement, and changing the project's default base is a larger decision needing broader maintainer alignment, not a mechanical change.deploy/docker/Dockerfile.sandbox,FROM scratch) — rejected: the sandbox image has no runtime base to swap, it's a bare static binary with no base at all, so this axis doesn't apply there.Agent Investigation
Confirmed by reading the current Dockerfiles directly and inspecting published images/registries with
skopeo inspect:deploy/docker/Dockerfile.gatewayalready has theGATEWAY_BASE_IMAGEARG described above.deploy/docker/Dockerfile.supervisorhas no equivalent ARG.deploy/docker/Dockerfile.sandboxisFROM scratchwith no base image to parameterize.ghcr.io/nvidia/openshell/supervisor:devis 15 layers / ~19.6 MB total; its base (distroless/base-nossl-debian13) is 14 layers / ~5.94 MB.registry.access.redhat.com/hi/core-runtime:latest(Project Hummingbird's comparable minimal base) is 23 layers / ~12.82 MB, with image configCMD ["/bin/bash"].No RFC needed — this is a small, additive, non-breaking build-configuration change, not a change to OpenShell's architecture or default behavior.