Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

feat: make supervisor base image configurable via build ARG

Open Beginner friendly
  • Is something wrong?
#4,205 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
84/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
docker
Domain
build-system, devops

Research direction

Start by comparing deploy/docker/Dockerfile.supervisor with deploy/docker/Dockerfile.gateway and read the base-image documentation in architecture/build.md. Add the supervisor override using the current pinned image as its default, then build with and without an override to check the default behavior and configurability. Done means the documentation covers both overrides and the default remains unchanged.

Written by the indexing model from the issue text.

Description

state:triage-needed

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 gateway

deploy/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

  • deploy/docker/Dockerfile.supervisor accepts a build ARG for its base image, with the current image pinned as the default.
  • Building without overriding the ARG produces the same image as today (no default-behavior change).
  • Wherever the gateway's GATEWAY_BASE_IMAGE override is documented (e.g. architecture/build.md) is updated to document the supervisor's new equivalent consistently.

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.

Dominant language
Rust
Stars
13.2k
Forks
1.6k
Avg merge
1d 19h
Merged PRs (30d)
330

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from NVIDIA/OpenShell

All issues in NVIDIA/OpenShell

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.