Domains, Caddy & certificates

Add a domain mapping

Open a resource and choose Domains. A mapping contains:

• a fully-qualified public hostname;
• a public path and optional internal path rewrite;
• the target Swarm service and internal port;
• optional path stripping;
• HTTPS enablement;
• certificate strategy: Let's Encrypt with automatic renewal for production, or Caddy's internal CA for private development environments;
• reusable administrator-defined Caddy snippets.

Compose resources must select the exact service name. Upstand normalizes hostnames and paths and rejects IP addresses, localhost, wildcard hosts, malformed paths, traversal segments, and ports outside 1–65535.

The API validates the complete candidate resource set before committing a change. Duplicate hostname/path ownership and conflicting HTTP/HTTPS modes are rejected, and the last known-good Caddy configuration is restored if persistence fails.

Certificates and renewal

The Web Server → HTTPS & Certificates section configures the ACME email used by Caddy. Caddy obtains and renews certificates automatically for HTTPS routes. DNS for each hostname must resolve to the server and TCP ports 80 and 443 must reach the Caddy service.

Each route can select one of two certificate strategies:

• Let's Encrypt: the production default. Caddy completes ACME HTTP/TLS challenges and persists the certificate and renewal state in its managed data volume.
• Caddy internal CA: useful for private networks and development. Browsers and clients must trust the Caddy root certificate; it is not a public certificate authority.

Upstand does not store private certificate material in resource metadata. Certificate issuance and renewal are delegated to Caddy, while Upstand validates the complete generated configuration before reloading it. If issuance fails, check DNS, ports 80/443, the ACME email, and the Caddy logs from Web Server → Logs.

Changing a route or certificate strategy validates and reloads the complete candidate configuration. If validation or reload fails, the last known-good Caddy configuration remains active and the resource update is rejected.

Caddy configuration

The Web Server page provides one reusable CodeMirror surface for:

• global Caddy options;
• named route snippets;
• the compiled read-only Caddyfile preview.

Snippets can be referenced by name from a resource domain mapping. Caddy configuration is syntax-checked and health-checked before it replaces the active configuration.