TLS

Choosing an approach

Mode	Inputs	Requirement
Certificate pair	--tls-cert, --tls-key	Both PEM files
Self-signed swarm TLS	--self-signed-tls	Initialized swarm; workers pin the certificate
ACME	--acme-domain, --acme-contact-email	Domain and reachable HTTP-01 challenge

For non-loopback binds, gdc serve also requires --role and swarm identity setup. Complete Swarm setup before the examples below.

Your own certificate

gdc serve --role orchestrator --bind 0.0.0.0:7777 \
  --tls-cert /path/to/cert.pem --tls-key /path/to/key.pem

Clients must trust the certificate chain and the hostname must match.

Self-signed

gdc serve --role orchestrator --bind 0.0.0.0:7777 \
  --self-signed-tls --self-signed-san coordinator.example.com

Certificate and key are persisted under ~/.gdc/swarms/<id>/tls/. The SAN must include the hostname or IP workers use. Self-signed generation is skipped on loopback binds, where the server uses plain HTTP.

Pin the certificate on swarm clients:

gdc swarm join "swarm://..." --tls-ca /path/to/cert.pem
gdc serve --role worker --swarm-tls-ca /path/to/cert.pem

GDC_SWARM_TLS_CA and [swarm].tls_ca also configure swarm trust. These settings apply to swarm clients; gdc-tui has no certificate-pin flag. For TUI access to a self-signed deployment, use a loopback tunnel or a proxy with a certificate its client trusts.

Automatic certificates (ACME / Let's Encrypt)

gdc serve --role orchestrator --bind 0.0.0.0:443 \
  --acme-domain coordinator.example.com --acme-contact-email ops@example.com

Flag	Default	Effect
--acme-directory URL	Let's Encrypt production	Certificate authority directory
--acme-cache-dir PATH	~/.gdc/tls/<domain>/	Certificate, key and account cache
--acme-http01-bind ADDRESS	0.0.0.0:80	HTTP-01 listener

The domain must resolve to the server and port 80 must reach the challenge listener. Explicit certificates and ACME cannot be combined. Self-signed TLS conflicts with an explicit certificate or ACME domain.