Hosting — hostnames, ports and TLS

A service that runs is not yet a service anyone can reach. Hosting is the part of an environment that says how the outside world gets in: which hostnames answer, on which network face of the server, over which certificate, and — for a database or a game server — which TCP or UDP ports are published. This chapter covers the Hosting tab, the organization's TLS library under Servers → TLS, and the Let's Encrypt path that runs through both.

The model

Every server that serves hostnames runs a hosting Caddy on ports 80 and 443, behind a Traefik that also carries raw TCP/UDP. A hosting row is one entry the platform materializes into that Caddy's configuration: a set of hostnames (or a set of ports), a service and target port behind them, a bind scope, and the certificate to serve.

Hosting rows come from two places, and which one owns a row decides where you edit it:

• The Hosting tab — rows you add by hand for a service. Edit and delete them there.
• The compose document — rows declared under x-turbopanel.hosting[] on a service. The platform materializes them on every deploy; on the Hosting tab they are shown read-only, captioned as compose-owned, and any change goes in the document. Trying to edit one through the API is refused with hosting_owned_by_compose.

Three rules hold everywhere:

1. A hostname is unique within the organization. Two hosting rows in one organization can never claim the same hostname, even on different paths; the database enforces it, not just the form.
2. The certificate is a pin, not a copy. A hosting row points at a certificate in the organization's TLS library (tlsId). No pin means Caddy's own locally-trusted certificate (tls internal) — fine for a private hostname, wrong for a public one.
3. The Organization CA never issues hosting certificates. It signs the platform's internal traffic (daemon, managed-database ingress). Public hostnames get an uploaded certificate, a self-signed one, or Let's Encrypt.

Bind scopes

The bind is frozen into the host's Caddy at deploy time, so changing it — or a member address moving — leaves the environment marked needs redeploy until you deploy again.

Before you begin

• A deployed (or at least placed) environment — hosting rows attach to a service in one.
• For a public hostname: DNS for it pointing at the serving server's public address.
• For Let's Encrypt: an organization owner or manager has turned on Allow Let's Encrypt certificates under Servers → TLS, the hostname's bind is public, and ports 80 and 443 on that server are reachable from the internet.
• For a published TCP/UDP port: nothing else on that server already publishes the same port.

Add a hostname

Hosting variables and PHP options

Once a row is saved, it carries its own Variables panel — the hosting scope of the variable cascade, for values that differ per hostname (a SITE_URL, a per-host feature flag). For a site served by a host engine, the row also exposes PHP options: series (8.3, 8.4), memory_limit, max_execution_time, and up to 64 static environment entries (web.env) of at most 4096 characters each.

Publish a TCP or UDP port

The TLS library

Servers → TLS is the organization's certificate library. Every row has a source and a status:

Upload a certificate

Mint a self-signed certificate

Source Self-signed, list the Hostnames, save. Useful for a datacenter or local hostname, or as a placeholder before a real certificate exists.

Let's Encrypt

Let's Encrypt is off by default for every organization. Some operators do not want the platform contacting a public CA on their servers' behalf at all, so it is an explicit opt-in, and turning it back off is immediate: no new certificate can be requested, and a deploy that still pins a Let's Encrypt (managed) row is refused with acme_requires_org_opt_in until you turn the opt-in back on or pin another certificate. Certificates Caddy already issued are not revoked; they stay on the host.

If issuance fails — a hostname that does not resolve, a closed port 80, a Let's Encrypt rate limit — the daemon notices within a minute or two and the row shows Issuance failing with the reason; the deploy itself is not affected, and the hosting keeps serving Caddy's local certificate until issuance succeeds.

Revoke and retire

Revoke on a library row sets it revoked; hostings pinned to it fall back to tls internal on their next deploy. There is no CRL or OCSP: a client that already holds the certificate keeps trusting it until it expires. The organization CA is retired and rotated as a whole, from its own panel — Organization CA.

Reference

Hosting options

Compose spelling

The same row, declared on a service:

x-turbopanel:
  hosting:
    - hostname: shop.example.com
      pathPrefix: /api
      targetPort: 3000
      forceHttps: true
      tls: { mode: acme }                  # internal | certificate (+ certificateRef) | acme
      bind: { scope: public, ipRef: edge } # public | datacenter | local

certificateRef names a library certificate by its id or its display name; ipRef names a registered IP by its id or its address. An unknown reference is refused at deploy (hosting_tls_ref_unresolved, hosting_ip_ref_unresolved); the editor's linter flags it earlier when it knows the organization's library.

Certificate lifetimes

Errors

Related

• Deploying and running an environment — the deploy-time refusals in full.
• Writing compose — the x-turbopanel.hosting[] declaration.
• Hostnames and TLS — the operator view of Let's Encrypt on the serving host.
• Organization CA — the internal CA, rotation, and why it never signs hosting certificates.
• Network addressing — the IP registry a public bind can pick from.