TLS certificates

← Back to Index | Previous: Install Deslicer AI | Next: Install DAP →

6.1 Deslicer-managed Caddy

Both Deslicer AI and DAP terminate public HTTPS with Deslicer-supplied Caddy. Application containers stay on loopback; Caddy owns the public listeners and certificates.

Product	Public listeners (typical)	Upstream
Deslicer AI	`:443` for `<dai-host>`	`/` → `127.0.0.1:13000`, `/control` → `127.0.0.1:13001`
DAP	`:443` (Observer API), `:8443` (Observer UI)	Loopback Observer API / Observer UI

Replace <dai-host> with the DAI FQDN and (for DAP) use the DAP FQDN in Observer URLs — not interchangeable.

You do not need to place a separate corporate reverse proxy in front of ports 13000 / 13001 for the primary install path. If a corporate load balancer sits in front of Caddy, treat that as an advanced overlay; Deslicer still configures Caddy on the product host.

Caddyfile is Deslicer-managed. Installers and Control always regenerate /etc/caddy/Caddyfile from provision, Control overlays, and supported CLI flags. Do not hand-edit the file; the next proxy/TLS apply overwrites it. --force-caddyfile remains accepted for compatibility and is effectively the default.

Control → Updates still prints Nexus-only --update. That command regenerates Caddy routes from the primary hostname site blocks. Extra listeners are not in that printed command. The installer rehydrates them from the host sidecar /etc/deslicer/edge-proxy-extra-listeners.json (hostnames/IPs only, no PEMs). On the first --update after this recovery ships, if the sidecar is missing, Deslicer parses the live Caddyfile (site hosts minus the primary) and seeds the sidecar — unless the file is still a stock/package Caddyfile, in which case no extras are invented. Colocated DAI+DAP share one Caddyfile and one sidecar.

Extra listeners (PEM mode)

Extra Caddy listener hostnames or IPs (no ports) come only from:

Blueprint / provision — deployment.edgeProxy.extraListens (day-0 DAI)
Installer CLI — --extra-listens host,ip on deslicer-dai-install.sh / deslicer-dap-install.sh (authoritative; an empty list clears extras)
Control Web certificates — after Control first-access (DAI and DAP panels). Apply with the printed --proxy-only command, not Nexus --update

Ports inherit from the primary site (DAI :443; DAP from the public Observer URL plus :8443 UI when that block exists). The primary DAI public URL / DAP API URL hostname stays locked in Control.

6.2 Certificate modes

Mode	When to use
ACME (automatic HTTPS)	Default for internet-reachable hostnames. Host must answer HTTP-01 on port 80 (and serve HTTPS on 443 for DAI). Extra listeners are PEM-mode only.
Provided PEM	You supply a certificate and private key issued by your PKI or a third-party CA. Required for extra listeners.

Two-phase DAI

Chicken-and-egg: Control cannot configure DAI’s own Caddy until DAI is up and first-access is claimed (/control/bootstrap).

Phase	How you set listeners / PEMs
Day-0 (before Control first-access)	Provision `deployment.edgeProxy.extraListens` and/or `deslicer-dai-install.sh --extra-listens`. Place PEMs on disk for Manual Certs as below.
After first-access	Platform integrations → Deslicer AI → Web certificates (same pattern as DAP: SAN checklist, stored vs live expiry, extra listeners, update + re-apply). Private keys are write-only after save.

DAP Web certificates are available as soon as Control is usable (they do not wait on the DAI TLS panel).

Prefer Control → Web certificates (§6.4, §6.5) for certificate rotation after Control is reachable. PEMs are stored encrypted in DAI; installers fetch them via the Control-printed host command (DAI enroll for DAP — never Nexus-only --update for cert apply).

Day-0 Manual Certs (Blueprint)

When Blueprint Manual Certs selects provided_tls_pem without embedding PEMs:

The packaged DAI installer completes the application stack (including interactive schema) without starting public Caddy TLS.
It creates /etc/caddy/certs/<dai-host>/, writes /etc/caddy/Caddyfile from provision (including any day-0 extra listeners), then exits non-zero with the exact PEM paths and a link to this chapter (https://docs.deslicer.io/tls-certificates).
Place fullchain.pem and privkey.pem as in §6.3.
Re-run deslicer-dai-install.sh --proxy-only (same provision / age identity / overlay / --extra-listens if used) to activate PEMs and enable Caddy. The Caddyfile is regenerated from provision.

Until step 4 succeeds, public HTTPS is down; Control on loopback 13001 remains reachable via SSH tunnel if needed. After HTTPS works and first-access is claimed, prefer §6.4 for later certificate rotation and extra listeners.

6.3 Provided PEM files on disk

Use this when day-0 Manual Certs needs PEMs on the host before Control can store them, or when you stage files that the installer / Control apply will point at.

Replace <dai-host> with the public FQDN that browsers use (for example dai-101-ubuntu-aws.deslicer.show). The private key must match the leaf certificate. Include every extra listener name/IP in the certificate SAN when clients verify those names.

1. Create a host-specific cert directory

sudo mkdir -p /etc/caddy/certs/<dai-host>

2. Place the PEM files

/etc/caddy/certs/<dai-host>/fullchain.pem
/etc/caddy/certs/<dai-host>/privkey.pem

fullchain.pem must contain, in order:

The server/leaf certificate for <dai-host> (and SANs for extra listeners)
The issuing intermediate CA certificate(s)

privkey.pem is the private key for that leaf certificate.

3. Set ownership and permissions

The Caddy service account must be able to read the files:

sudo chown -R root:caddy /etc/caddy/certs
sudo find /etc/caddy/certs -type d -exec chmod 750 {} \;
sudo find /etc/caddy/certs -type f -exec chmod 640 {} \;

4. Apply via installer (do not hand-edit Caddyfile)

bash /opt/deslicer/bin/deslicer-dai-install.sh \
  --proxy-only \
  --extra-listens <host-ip>,alias.example

Omit --extra-listens when extras already come from provision. The installer regenerates /etc/caddy/Caddyfile and reloads Caddy. Do not publish 13000 / 13001 on the public interface.

Then open https://<dai-host>/ and https://<dai-host>/control and confirm the browser trusts the certificate.

If Control still shows ACME mode or a different hostname, align Web certificates and the public app URL with this FQDN so login and probes do not diverge (Chapter 10 §10.13).

6.4 Deslicer AI Web certificates

Available after Control first-access.

Sign in to Control at https://<dai-host>/control
Open Platform integrations → Deslicer AI → Web certificates
Choose PEM (required for extra listeners) or ACME, select SAN checklist / custom extra names, save
Run the host apply command Control displays on the DAI host (--overlay, --update --proxy-only, and --extra-listens when non-empty). That installer mode is not Control → Updates (Nexus-only --update).

Example shape (use Control’s exact output):

bash /opt/deslicer/bin/deslicer-dai-install.sh \
  --overlay ./edge-tls.yml \
  --update \
  --proxy-only \
  --extra-listens <host-ip>

Control stores PEMs encrypted in DAI and shows Stored in DAI vs Live on endpoint (issuer, serial, dates, SANs, extra listeners, leaf SHA-256, and private-key SHA-256). Private-key PEM is write-only after save. The apply path regenerates the Caddyfile and reloads Caddy. Do not run ad-hoc caddy validate / hand edits for this path. For full product image updates, use Control → Updates (Chapter 5); that Nexus --update keeps extra listeners via the sidecar.

6.5 DAP Web certificates

After DAP is enrolled (and the public Observer hostname resolves to the DAP host):

In Control, open Platform integrations → DAP
Select the backend and open Web certificates
Choose PEM or ACME, configure extra listeners (PEM), save, and run the host apply command Control shows on the DAP host

Control prints a DAI enroll fetch command that includes PEMs and extra listeners from DAI storage — not a Nexus-only --update. Example shape:

bash /opt/deslicer/bin/deslicer-dap-install.sh --proxy-only ...

Use the exact flags and enroll context Control prints. Proxy-only regenerates /etc/caddy/Caddyfile and reloads Caddy. If ACME failed while DNS was wrong, fix DNS first, then re-run the Control command so issuance can leave backoff.

For day-0 PEM files on the DAP host before Control apply, use the same directory and permission pattern as §6.3, with the Observer hostname under /etc/caddy/certs/<dap-host>/.

6.6 Routing checklist

Deslicer AI

https://<dai-host>/ serves the application
https://<dai-host>/control serves Control
Browser shows a trusted certificate for the DAI hostname
Extra listeners (if any) answer on the same ports with the same PEMs
13000 / 13001 are not published on 0.0.0.0
PEM mode: files under /etc/caddy/certs/<dai-host>/ are root:caddy and mode 640 / dirs 750

DAP

Observer health URL from Control returns success over HTTPS
Observer UI URL from Control loads over HTTPS
Certificate mode matches what you configured in Control

6.7 IP addresses instead of FQDNs

Short answer: Caddy can listen on a host that only has an IP, but a supported enterprise install expects public FQDNs for DAI and DAP. IP-only is possible only with caveats — not as a drop-in replacement for the default ACME + Control path.

Approach	Works?	Caveats
ACME / Let’s Encrypt on a bare IP	Generally no	Public ACME HTTP-01 expects a resolvable hostname; IP-only issuance is not the Deslicer default
Customer PEM with IP in SAN (or self-signed IP SAN)	With caveats	Browsers/trust stores must trust that cert; many corporate PKIs still prefer DNS names
HTTP only (no TLS)	Not recommended	Not the supported enterprise edge path; Control, cookies, and IdP redirects assume HTTPS URLs
`/etc/hosts` (or internal DNS) mapping a name → IP	Preferred workaround	Keep using FQDNs in provision / enroll / Control even if public DNS is unavailable

Also plan for:

Control and app URLs — local login and probes compare the browser URL to the configured public app URL (Chapter 10 §10.13). Changing between IP and name later needs a coordinated URL update.
OIDC / IdP callbacks — redirect URIs are usually registered as https://<dai-host>/… hostnames, not raw IPs.
DAP enroll — Control stores the public Observer URL operators enter; workers and DAI server-side calls must reach that same URL.

Recommendation: publish DNS (or internal DNS / hosts-file names) for <dai-host> and <dap-host> even on isolated networks. For lab access by IP in addition to FQDN, add the IP via deployment.edgeProxy.extraListens, installer --extra-listens, or Control Web certificates (PEM), and put the IP in the certificate SAN. Do not hand-edit the Caddyfile.

If you must use IP-only PEMs, engage Deslicer Support before install so certificate mode, URL fields, and IdP callbacks stay aligned. See also Chapter 3 §3.1.

6.8 Control DAP Backends — untrusted TLS (enterprise only)

On Control → Platform integrations → DAP → Backends, expand a backend row to reach its Untrusted TLS panel. The panel holds exactly two switches, and both exist only in enterprise deployments; SaaS refuses enabling them.

Switch (Untrusted TLS panel)	Effect
DAP unsecure (peer)	Deslicer AI skips TLS certificate verification for HTTPS calls to this backend’s Observer URLs (proxy, provisioning, status, compliance). Control also appends `--peer-tls-insecure` to this backend’s Fresh/repair run line.
Worker node unsecure	Install/provision stamps worker and bootstrap clients to skip Observer TLS verify on this backend.

Trusting the CA instead — not a switch

There is no third toggle for CA trust. The preferred alternative to skip-verify is the Web certificates panel in the same expanded backend row (§6.5):

Choose Upload certificate (PEM) and supply the edge chain. While Worker node unsecure is off, Deslicer AI derives the Observer trust material from that chain and stamps it into provisioning, so workers and bootstrap verify normally. Enabling Worker node unsecure clears it.
ACME mode leaves no chain on file for Deslicer AI to derive from, so this path requires PEM mode.
Installing your public, private, or edge CA into each host’s trust store is a host-side action. It is not configured in Control.

Operator rules

Prefer a public CA or installing your private / edge CA into the trust store over skip-verify.
Enabling either unsecure toggle requires typing the exact confirmation phrase shown in Control (ACCEPT PEER TLS RISK / ACCEPT WORKER TLS RISK). The action is audited.
Skip-verify leaves a MITM residual: an attacker on the network path can impersonate Observer and intercept enrollment or API traffic.
Any change to DAP unsecure (enable or disable) revokes unconsumed install enrollment tokens for that backend. Control re-issues a Fresh or repair host install command (token + --dai-url) so day-0 DAI bundle fetch includes --peer-tls-insecure on the bash argv when enabled (required for curl -k against an untrusted DAI edge). Always copy the new run line after toggling; do not reuse a command minted before the policy change. Nexus --update is not the remint after DAP unsecure.
Disabling Worker node unsecure also revokes unconsumed install tokens so hosts cannot keep installing under the old insecure worker policy.

For the enroll-time walkthrough — where the panels are, which switches a self-signed estate needs, and which host’s certificate to upload — see Chapter 7 §7.3.

6.9 Corporate load balancer (optional overlay)

If your security standard requires a corporate LB/WAF in front of Deslicer:

Terminate TLS on the LB or pass through to Caddy—pick one model and keep certificates consistent
Forward to the Deslicer Caddy listeners (DAI :443, DAP edge ports), not to raw Compose ports
Preserve Host headers so ACME and application routing continue to work when Caddy remains the origin TLS terminator
Add the product host IP (and any extra names or IPs the load balancer uses) to extra listeners and to the PEM certificate SAN. Caddy must listen on those names/IPs; clients that verify the hostname fail unless the SAN matches
Apply extra listeners with Control Web certificates / --proxy-only (or day-0 --extra-listens). Do not rely on hand-editing the Caddyfile; Nexus --update keeps extras only via the sidecar after they were applied that way

← Back to Index | Previous: Install Deslicer AI | Next: Install DAP →

6.1 Deslicer-managed Caddy​

Extra listeners (PEM mode)​

6.2 Certificate modes​

Two-phase DAI​

Day-0 Manual Certs (Blueprint)​

6.3 Provided PEM files on disk​

1. Create a host-specific cert directory​

2. Place the PEM files​

3. Set ownership and permissions​

4. Apply via installer (do not hand-edit Caddyfile)​

6.4 Deslicer AI Web certificates​

6.5 DAP Web certificates​

6.6 Routing checklist​

6.7 IP addresses instead of FQDNs​

6.8 Control DAP Backends — untrusted TLS (enterprise only)​

6.9 Corporate load balancer (optional overlay)​