Running the image

One image carries every server role. The command line selects the role and the configuration. Select the immutable image supplied for this documentation edition before starting a role:

: "${IMAGE:?Set IMAGE to the supplied matching immutable image}"
docker run --rm \
  --read-only --cap-drop ALL --security-opt no-new-privileges \
  --tmpfs /tmp \
  -v "$PWD/authority.toml:/etc/gdsgate/authority.toml:ro" \
  -v gdsgate-state:/var/lib/gdsgate \
  -p 50050:50050 -p 50051:50051 \
  "$IMAGE" --config /etc/gdsgate/authority.toml authority

The entrypoint is gdsgate. Arguments after the image name go to it: global options first, the role last. There is no default role.

Authority, Proxy and PostgreSQL under Docker Compose, with every file: Deploy, Docker Compose.

Roles and ports

Role	Command	Listens on	Set by
Authority	authority	50051 control API, 50050 enrollment	[endpoints].authority, [endpoints].authority_enroll
Proxy	proxy	50061 clients, 50062 connectors, 50063 WebSocket fallback, 50064 join relay when configured	[endpoints].proxy_*
Connector	connector	nothing inbound; dials out	[endpoints], [connector]
All-in-one	all	all of the above in one process	the same sections

Every port is above 1024; binding needs no capability. The image runs as uid 10001. To expose a port below 1024, use a published port mapping.

Where settings come from

Three inputs, each overriding the one before:

1. The file named by --config. Mount it read-only. It is the same TOML a host install uses; the templates are packaging/config/*.example.
2. GDSGATE_* environment variables. Each maps to one key. See configuration → environment overrides.
3. Command-line options.

The variables a container deployment uses most:

Variable	Sets
GDSGATE_STORE_URL	store_url, where Authority keeps cluster state
GDSGATE_AUTH_ADDR, GDSGATE_AUTH_ENROLL_ADDR	Authority's two listeners
GDSGATE_PROXY_PUBLIC_ADDR, GDSGATE_PROXY_INTERNAL_ADDR, GDSGATE_PROXY_WS_ADDR, GDSGATE_PROXY_JOIN_ADDR	the Proxy's listeners
GDSGATE_ENROLL_ENDPOINT, GDSGATE_ENROLL_TOKEN, GDSGATE_ENROLL_STATE_DIR	where a node registers, with what, and where it keeps the identity it is issued
GDSGATE_TELEMETRY_METRICS_LISTEN	the observability listener, which also serves the health endpoints

What to mount

Path	Mode	Holds
/etc/gdsgate	read-only	the role's TOML, and any certificate or keyring files it names
/var/lib/gdsgate	read-write	the enrolled identity, and the store when it is a local file
/tmp	tmpfs	scratch space; the root filesystem can stay read-only

A fresh volume mounted at /var/lib/gdsgate inherits the image's ownership; no root init step is needed.

Readiness

Endpoint	Returns
/readyz	503 until the role's listeners are up, then 200
/healthz	200 once the observability server binds

Both are served on [telemetry].metrics_listen. With it unset there are no health endpoints. A probe from outside the container cannot reach a loopback address; in Kubernetes, bind it to the pod address or to every interface.

Kubernetes

The Helm chart, the kustomize base, the Services each connector route needs, and a connector in the cluster: Deploy, Kubernetes.

Recipe: everything through the Proxy, with a certificate from Let's Encrypt

Clients reach the Proxy by its domain name over a publicly trusted certificate; a connector that can reach only the Proxy registers and renews through the join relay, and its later Authority calls go through its reverse tunnel. Authority's two listeners, the store, and the identity provider's server-to-server traffic stay internal. Certificate: Certificates, Let's Encrypt. Route: Kubernetes, the join relay, the join relay, tunnelled connector behaviour.