Skip to content
Docs

Self-hosting

Tracking domains and TLS

Add a branded tracking domain, verify its DNS, get certificates, and monitor its health.

Links and postback URLs are served from a tracking domain you own, usually a subdomain such as go.yourbrand.com that is a CNAME to the edge. A tenant can have many domains, per region or per brand, and each domain can speak a legacy link style for migrations (link styles).

Add and verify a domain

  1. Create it under Traffic, Domains or POST /tracking-domains with the host. The API validates the hostname and works out the CNAME target.
  2. GET /tracking-domains/{id}/dns returns the DNS records to create: the CNAME to the edge target for the domain's region, and a TXT record _dtrackier-verify.<host> carrying the domain's verification_token. Targets come from DT_DOMAIN_CNAME_TARGETS (us=track-us.example.com,default=track.example.com).
  3. A worker checks verification every 30 seconds (DT_DOMAIN_VERIFY_SECONDS) using your configured resolvers (DT_DNS_RESOLVERS, default the system resolver); POST /tracking-domains/{id}/verify forces a check. The domain status moves to ssl_pending when DNS is correct and to active once its certificate exists.

Certificates

  • Production profile (on-demand at the proxy). The bundled TLS proxy obtains a certificate for a custom domain at its first TLS connection, after asking the API (GET /v1/internal/tls-ask, secret DT_TLS_ASK_TOKEN) whether the host is a DNS-verified domain of a live workspace. The domain worker connects to the proxy with the domain as SNI (DT_DOMAIN_TLS_PROBE_ADDR), which triggers issuance, and marks the domain active once a certificate naming it is served. Unknown or unverified hostnames get no certificate. Portal-type domains (partner_portal, advertiser_portal, admin_portal) are passed on to their portal (DT_EDGE_PORTAL_UPSTREAMS).
  • Built-in ACME. Run the edge with DT_EDGE_TLS_ADDR (for example :443) and DT_ACME_DIRECTORY (prod for Let's Encrypt, empty or staging for the staging CA, a URL for another CA, none to disable) and DT_ACME_EMAIL. Certificates are obtained on demand for verified domains using HTTP-01 on the plain listener, and stored in Postgres so every edge replica shares them. Issuance runs only for domains registered to a tenant.
  • Cloudflare for SaaS. Set ssl_mode=cloudflare_saas on the domain and configure DT_CF_ZONE_ID and DT_CF_API_TOKEN; custom hostnames are created and tracked through Cloudflare.
  • Your own TLS terminator. Put the edge behind a load balancer or CDN that terminates TLS, and set DT_EDGE_TRUST_PROXY=1 (and DT_INGEST_TRUST_PROXY=1) so the visitor IP is read from X-Forwarded-For. Geography is read from CDN headers (CF-IPCountry, CloudFront-Viewer-Country, X-Geo-*).

Wildcard certificates through DNS-01 and domain pools with rotation are not implemented.

Health

Every five minutes (DT_DOMAIN_HEALTH_SECONDS) a worker measures each active domain: HTTP reachability and latency, certificate expiry, DNS block lists, and Google Safe Browsing when DT_SAFE_BROWSING_KEY is set. GET /tracking-domains/{id}/health returns the latest samples (kept 7 days). A domain that flips between healthy and failing raises a domain_error notification and an event usable in automation rules. Certificates close to expiry also appear in the synthetic monitor and its alerts (observability).

Branded domains for other things

The same domains serve unilinks and the Apple and Android association files (deep links), the web SDK (/sdk.js) and conversion endpoints. A dedicated conversion domain can be set separately from the click domain on an offer (conversion_tracking_domain_id).