Running the image¶

One image carries every server role. The command line selects the role and the configuration.

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:

The file named by --config. Mount it read-only. It is the same TOML a host install uses; the templates are packaging/config/*.example.
GDSGATE_* environment variables. Each maps to one key. See configuration → environment overrides.
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.