Enable HTTPS

Serve a published hostname over trusted HTTPS, then redirect HTTP only after the certificate is active.

Before you start

  • Publish the service first.
  • Point each public route hostname at Clearplane; include wildcard DNS records for wildcard routes.
  • Choose HTTP validation, DNS validation, or an uploaded certificate.
  • Ensure any upstream proxy passes validation traffic unchanged.

HTTP-01 requires public TCP port 80 to reach Edge for issuance and renewal. Compose health cannot prove public DNS, firewall/NAT reachability, or certificate trust; verify those separately and correct DNS and ingress before retrying rate-limited production issuance.

Use DNS-01 for wildcard certificates or when public port 80 is unavailable. An internal-only name requires an uploaded private-CA certificate trusted by its clients.

UI

  1. Open Certificates and request a certificate for the hostname, or upload one that already covers it.
  2. Wait until the certificate status is Active.
  3. Open Proxy routes, edit the route, and enable Redirect HTTP to HTTPS.
  4. Save and apply the change when required.

Select HTTPS protocols

Open System → Settings → Edge → HTTPS protocols and independently enable HTTP/1.1, HTTP/2, and HTTP/3. You can select any nonempty combination, such as HTTP/2 only or HTTP/2 plus HTTP/3. Save the settings and restart Edge; applying configuration alone does not change its listeners.

To select HTTP/2 and HTTP/3 through Compose instead, add these labels to Edge:

services:
  clearplane-edge:
    labels:
      clearplane.edge.http1.enabled: "false"
      clearplane.edge.http2.enabled: "true"
      clearplane.edge.http3.enabled: "true"

A label overrides and locks the matching UI switch. Omit a label to use its saved UI value. Recreate Edge after changing its labels; if the Dashboard still reports that Edge needs a restart, restart it once more so it starts with the new selection.

The selection controls public HTTPS. The plain HTTP listener keeps HTTP/1.1 for HTTP-to-HTTPS redirects, ACME HTTP-01 challenges, and health checks. Disabling HTTP/1.1 on HTTPS does not disable that listener or alter route-level redirects.

For HTTP/3, allow UDP port 443 through the host firewall, NAT, and any upstream network boundary. TCP 443 is still needed when HTTP/1.1 or HTTP/2 is selected.

HTTP/3-only needs a QUIC-capable runtime and clients that can discover or directly request it. Browsers normally discover HTTP/3 through an Alt-Svc response over HTTP/1.1 or HTTP/2, which is unavailable when both are disabled. Edge reports a startup error if HTTP/3 is the only selection and QUIC is unavailable; it never silently re-enables a disabled protocol.

Docker labels

Enable certificate management and the HTTPS redirect on the application container:

labels:
  clearplane.proxy.certificate.enabled: "true"
  clearplane.proxy.redirect.http-to-https: "true"

For DNS validation, either reference a shared credential profile with clearplane.proxy.certificate.dns.profile or supply inline DNS settings on the application.

See the proxy directives for every certificate and HTTPS label.

DNS credentials in the UI

Create a shared Cloudflare DNS-01 credential profile in the UI and select it when requesting a DNS-01 certificate. Core encrypts UI-managed tokens with its Data Protection keys. Tokens are write-only: supply a token on creation or rotation; the API never returns it.

Scope the Cloudflare API token to the required zones with DNS record edit and zone read access. Keep deployment secret files out of source control and readable only by the deployment account.

Inline DNS profiles

Define the provider and token directly on an application's labels when its credentials should stay with that app:

labels:
  clearplane.proxy.enabled: "true"
  clearplane.proxy.host: "*.example.com"
  clearplane.proxy.port: "8080"
  clearplane.proxy.certificate.enabled: "true"
  clearplane.proxy.certificate.dns.provider: "Cloudflare"
  clearplane.proxy.certificate.dns.api-token: "${CLOUDFLARE_API_TOKEN:?Set CLOUDFLARE_API_TOKEN}"
  clearplane.proxy.certificate.dns.propagation-seconds: "30"
  clearplane.proxy.redirect.http-to-https: "true"

Inject the token through GitHub Actions secrets using the env example below. No JSON or separate profile setup is needed. For a standalone redirect, use the same fields under clearplane.redirect.certificate.dns.*.

Choose either inline DNS fields or certificate.dns.profile; combining them rejects the app configuration and retains its previous valid settings. Omitting both selects HTTP-01. DNS fields are ignored with a warning when certificate management is disabled.

Core creates a read-only {resource-name}-acme-dns profile, encrypts the token, and updates it when the app's labels change. Container recreation and route renaming keep the same profile. Other apps and manual certificate requests cannot reference it by name; use a shared profile for credentials or certificates used by several apps. Generated names are reserved and cannot be replaced by a later Core profile of the same name.

Stopping or removing an app retains credentials needed to renew its existing certificates. The generated profile is removed when no app requests it and no ACME certificate references it. Tokens are never returned by the API or discovery diagnostics, but Docker inspection can reveal secret labels. Avoid printing rendered Compose configuration in Actions logs.

Shared profiles on Core

Add numbered environment variables to the Core service in docker-compose.override.yml. Each number creates a named profile at startup. This example defines two profiles with separate scalar tokens:

services:
  clearplane-core:
    environment:
      CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILE_1_NAME: cloudflare-test
      CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILE_1_PROVIDER: Cloudflare
      CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILE_1_API_TOKEN: ${CLOUDFLARE_API_TOKEN:?Set CLOUDFLARE_API_TOKEN}
      CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILE_1_PROPAGATION_SECONDS: "30"
      CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILE_2_NAME: cloudflare-other-zone
      CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILE_2_API_TOKEN: ${SECOND_CLOUDFLARE_API_TOKEN:?Set SECOND_CLOUDFLARE_API_TOKEN}

Remove the _2_ entries for one profile, or add _3_ and higher numbers for more. No JSON encoding or UI setup is needed.

A GitHub Actions step that runs Compose can receive the tokens through env:

env:
  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
  SECOND_CLOUDFLARE_API_TOKEN: ${{ secrets.SECOND_CLOUDFLARE_API_TOKEN }}

Compose resolves these variables on the machine running Compose. When Actions deploys to another host, use the deployment's existing secret-injection step to supply them there; the runner's environment is not automatically forwarded. See GitHub Actions secrets and Compose interpolation.

Use a Cloudflare token with DNS record edit and zone read access for the required zones. Shared profiles keep it in Core's environment or a mounted secret file. Avoid printing the rendered Compose configuration in Actions logs. To use a mounted token, replace _API_TOKEN with _API_TOKEN_FILE and set its value to the container's secret-file path; setting both is an error.

Core environment profiles are read-only in the UI and take precedence over UI-managed profiles with the same name. Recreate Core after changing these profiles or rotating their tokens. For inline app credentials, recreate the application instead so discovery receives the changed labels.

Shared profiles can also read tokens from mounted files or a JSON bootstrap document. See the environment variable reference for both formats.

Wildcard routing and certificates

Let's Encrypt wildcard certificates require DNS-01 validation. The inline example above publishes tenant hosts. To publish the apex and tenant hosts using a shared profile instead:

labels:
  clearplane.proxy.enabled: "true"
  clearplane.proxy.host: "example.com"
  clearplane.proxy.additional-hosts: "*.example.com"
  clearplane.proxy.port: "8080"
  clearplane.proxy.certificate.enabled: "true"
  clearplane.proxy.certificate.dns.profile: "cloudflare-test"
  clearplane.proxy.redirect.http-to-https: "true"

This route accepts example.com and one subdomain level, such as tenant.example.com. The wildcard alone does not match the apex or deep.tenant.example.com. You can instead set clearplane.proxy.host: "*.example.com" and omit additional-hosts to publish only tenant hosts.

Certificate automation includes wildcard route hosts in the certificate request. The example requests example.com and *.example.com; clearplane.proxy.certificate.wildcard is not needed because the wildcard is already a route host. Exact names already covered by a wildcard are omitted from the additional certificate names.

Keep the DNS profile available for automatic renewal. Edge selects an exact certificate for the requested hostname first, then a valid wildcard certificate covering one subdomain level. Wildcard certificate coverage does not create routes: configure the route hosts separately.

Upstream proxies

HTTP validation requires /.well-known/acme-challenge/* to reach Clearplane without caching, redirecting, or rewriting the host or path. Use DNS validation when an upstream proxy cannot preserve that request.

Verify

Open the HTTPS URL and confirm the browser trusts the certificate for the exact hostname. Request the HTTP URL and confirm it redirects only after HTTPS is working.