You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d25036a
Browse filesBrowse the repository at this point in the historyBrowse files
docs(container-gateway): fix Docker driver setup for containerized gateway
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.
Copy file name to clipboardExpand all lines: docs/about/container-gateway.mdx
+82-6Lines changed: 82 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,37 +12,79 @@ Use this approach when you want to run the OpenShell gateway as a container inst
12
12
13
13
The gateway image is published at `ghcr.io/nvidia/openshell/gateway`.
14
14
15
+
## Prerequisites for the Docker Driver
16
+
17
+
When the gateway runs as a container and creates Docker-backed sandboxes, the gateway container
18
+
communicates with the host Docker daemon via the mounted socket. This requires three things beyond
19
+
a basic `docker run`:
20
+
21
+
1.**Docker socket access.** The gateway process must be able to read and write the Docker socket.
22
+
Add the `docker` group (or the GID of `/var/run/docker.sock`) so the socket is accessible
23
+
without running as root.
24
+
25
+
2.**gRPC endpoint.** Sandbox containers call back to the gateway over the `OPENSHELL_GRPC_ENDPOINT`
26
+
address. Set this to `http://127.0.0.1:8080` so the driver knows the scheme and port. The
27
+
docker driver automatically binds the gateway to the bridge network interface so sandbox
28
+
containers can reach it — you do not need to expose the port on `0.0.0.0`.
29
+
30
+
3.**Supervisor binary on the host.** The gateway bind-mounts the `openshell-sandbox` supervisor
31
+
binary into each sandbox container. Because bind-mount paths are resolved by the host Docker
32
+
daemon (not inside the gateway container), the binary must exist at a path on the host
33
+
filesystem. Extract it before starting the gateway and mount it at the same path.
34
+
15
35
## Quick Start
16
36
17
-
This example runs the gateway locally with TLS disabled. It is suitable for development on a single machine. Binding to `127.0.0.1` prevents remote access without authentication.
37
+
Extract the supervisor binary to the host once, then start the gateway:
Disabling TLS removes authentication. Binding to `127.0.0.1` limits access to the local machine. If you expose the port on `0.0.0.0`, enable TLS and local mTLS user authentication, or put the gateway behind a trusted proxy with its own authentication.
85
+
Disabling TLS removes authentication. This example binds to `127.0.0.1` so only local
86
+
connections are accepted. To accept remote connections, enable mTLS or restrict access with
This writes the server and client certificates under `~/.local/state/openshell/tls/`, writes sandbox JWT signing keys under `~/.local/state/openshell/tls/jwt/`, and copies the client bundle to `~/.config/openshell/gateways/openshell/mtls/` so the CLI picks it up automatically.
@@ -69,10 +113,14 @@ Start the gateway with mTLS enabled:
0 commit comments