TLS¶

For any connection beyond loopback, encrypt it with TLS. gdc serve supports three approaches: bring your own certificate, generate a self-signed one, or obtain certificates automatically. Choose one — they can't be combined.

Choosing an approach¶

Approach	Best for
Your own certificate	You already have a certificate (from your organisation's CA or a public one).
Self-signed	Internal or development setups where you control both ends and can pin the certificate.
Automatic (ACME)	A public server with a real domain name; certificates are issued and renewed for you.

Your own certificate¶

Provide a certificate and its private key:

gdc serve --bind 0.0.0.0:8088 \
  --tls-cert /path/to/cert.pem \
  --tls-key  /path/to/key.pem

Clients trust it through your normal certificate chain.

Self-signed¶

Have gdc generate a self-signed certificate on startup:

gdc serve --bind 0.0.0.0:8088 --self-signed-tls

Add extra names (hostnames or IPs) that clients will use to reach it:

gdc serve --bind 0.0.0.0:8088 --self-signed-tls \
  --self-signed-san gdc.internal --self-signed-san 10.0.0.5

Because a self-signed certificate isn't backed by a public authority, clients must pin it — trust exactly this certificate and nothing else. On the connecting side, point clients at the server's certificate:

export GDC_SWARM_TLS_CA=/path/to/server-cert.pem

This "pin exactly this certificate" model is fail-closed: a client configured to pin will refuse any other certificate.

Automatic certificates (ACME / Let's Encrypt)¶

For a public server with a real domain, gdc can obtain and renew certificates automatically:

gdc serve --bind 0.0.0.0:443 \
  --acme-domain gdc.example.com \
  --acme-contact-email you@example.com

Additional options let you control the process:

Flag	Description
`--acme-domain <domain>`	The domain to get a certificate for.
`--acme-contact-email <email>`	Contact address (required with a domain).
`--acme-directory <url>`	The certificate authority's directory (defaults to Let's Encrypt production).
`--acme-cache-dir <path>`	Where to cache issued certificates.
`--acme-http01-bind <addr>`	Address for the validation challenge (defaults to port 80).

The domain must resolve to this server, and the validation address must be reachable, for issuance to succeed.

One approach at a time

The three approaches are mutually exclusive. Pick the one that fits your deployment; combining them is rejected.