docs(container-gateway): fix Docker driver setup for containerized gateway#1419
Open
ericcurtin wants to merge 1 commit into
Open
docs(container-gateway): fix Docker driver setup for containerized gateway#1419ericcurtin wants to merge 1 commit into
ericcurtin wants to merge 1 commit into
Conversation
ericcurtin
requested review from
a team,
derekwaynecarr,
maxamillion and
mrunalp
as code owners
drew
reviewed
May 18, 2026
ericcurtin
force-pushed
the
docs-container-gateway-docker-driver/ec
branch
from
eafe4f7 to
c1ff3e7
Compare
…teway The existing docs omitted or misstated several requirements when running the gateway as a container with the Docker compute driver: 1. OPENSHELL_GRPC_ENDPOINT is required. The Docker driver rejects startup if this env var is missing, but it was not mentioned. 2. The supervisor binary must be extracted to a host path before starting the gateway. The gateway validates the path at startup from inside the container, and the host Docker daemon uses the same path as a bind-mount source when creating sandbox containers. Extracting to a path inside the gateway container alone is insufficient. 3. Docker socket access requires adding the docker group. The gateway image runs as nvs:nvs (UID 1000) which does not have access to the Docker socket by default. 4. Port binding should remain 127.0.0.1. The Docker driver automatically binds the gateway to the bridge network interface (gateway_bind_addresses in the driver) so sandbox containers can reach it without exposing the port on 0.0.0.0. 5. The mTLS setup section was missing --server-san host.openshell.internal on generate-certs. Sandbox containers resolve host.openshell.internal to reach the gateway, so this SAN must be present in the server cert. The mTLS docker run was also missing --group-add docker, the supervisor binary mount, OPENSHELL_GRPC_ENDPOINT, and OPENSHELL_DOCKER_SUPERVISOR_BIN. Validated by deploying OpenShell on a Fedora Kinoite (bootc) system using the updated compose.yml.
ericcurtin
force-pushed
the
docs-container-gateway-docker-driver/ec
branch
from
c1ff3e7 to
05176ab
Compare
elezar
reviewed
May 18, 2026
Comment on lines
+36
to
+37
| bind_address = "0.0.0.0:8080" | ||
| health_bind_address = "0.0.0.0:8081" |
Member
There was a problem hiding this comment.
In another PR there was a comment about not using 0.0.0.0? Should this be changed here? Is something like :8080 a better format to use?
elezar
reviewed
May 18, 2026
|
|
||
| services: | ||
| gateway: | ||
| image: ghcr.io/nvidia/openshell/gateway:latest |
Member
There was a problem hiding this comment.
Question: Does the image support envvar replacement so that one could use ${IMAGE_TAG:-latests}?
elezar
reviewed
May 18, 2026
|
|
||
| volumes: | ||
| # Docker socket — lets the gateway create and manage sandbox containers. | ||
| - /var/run/docker.sock:/var/run/docker.sock |
Member
There was a problem hiding this comment.
I was under the impression that when running dind containers, for example, one needs to run the "outer" container as privileged. Is this not the case here? What permissions are required to communicate over the socket?
elezar
reviewed
May 18, 2026
Comment on lines
+87
to
+88
| source: /var/lib/openshell | ||
| target: /var/lib/openshell |
Member
There was a problem hiding this comment.
Should this be gateway-specific?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The container-gateway docs were missing or misstating several requirements for running the gateway as a Docker container with the Docker compute driver. Validated by deploying on a Fedora Kinoite (bootc) system.
Related Issue
N/A — discovered during hands-on deployment on a bootc system.
Changes
OPENSHELL_GRPC_ENDPOINTto all Docker driver examples (required; gateway refuses to start without it)127.0.0.1:8080— the Docker driver automatically binds the gateway to the bridge network interface viagateway_bind_addresses(), so exposing on0.0.0.0is unnecessarygroup_add: [docker]to the compose service — the gateway image runs asnvs:nvs(UID 1000) which needs the docker group to access the Docker socket--remoteflag for LAN access)--server-san host.openshell.internaltogenerate-certsin the mTLS section — sandbox containers resolvehost.openshell.internalto reach the gateway, so this SAN must be present in the server cert--group-add docker, supervisor binary mount,OPENSHELL_GRPC_ENDPOINT,OPENSHELL_DOCKER_SUPERVISOR_BIN)Testing
mise run pre-commitpasses (markdownlint clean; python:proto failure is pre-existing env issue unrelated to this change)Checklist