From e11486a9669a7a379654be6ddb45a84e5aaa1aed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B8ren=20Bramer=20Schmidt?= Date: Fri, 23 Oct 2026 17:07:42 +0700 Subject: [PATCH 1/3] docs(compute): explain workspace TXT verification --- apps/docs/content/docs/compute/domains.mdx | 30 ++++++++++++---------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/apps/docs/content/docs/compute/domains.mdx b/apps/docs/content/docs/compute/domains.mdx index bfbef1e33d5..2738c5f8ac0 100644 --- a/apps/docs/content/docs/compute/domains.mdx +++ b/apps/docs/content/docs/compute/domains.mdx @@ -3,7 +3,7 @@ title: Domains description: Point a custom domain at an app on any branch and the platform verifies DNS and provisions TLS for you. url: /compute/domains metaTitle: Custom domains | Prisma Compute -metaDescription: Add a custom domain to a Prisma Compute app, configure the CNAME record, watch provisioning, and troubleshoot failures. +metaDescription: Connect a custom domain to a Prisma Compute app, verify workspace ownership with TXT, configure routing, and provision TLS. --- Configure custom domains for apps on [production, preview, or staging branches](/compute/branching). Each domain routes to the live deployment of the app on the selected branch. @@ -33,20 +33,22 @@ npx prisma service domain add staging.acme.com --service web --branch staging npx prisma service domain wait staging.acme.com --service web --branch staging ``` -In Console, select the branch and open the app's **Domains** page to add or remove a custom domain. +In Console, select the branch and open the app's **Domains** page. Choose **Add domain**, enter the hostname, and continue to see the CNAME and workspace TXT records. -Registration verifies DNS up front. If the **CNAME** record isn't visible yet, the command fails with a `DOMAIN_DNS_NOT_CONFIGURED` error and prints the record name and value for you to create. Re-running `add` for a hostname that's already attached is safe: it shows the existing domain instead of failing. +Registration verifies ownership before creating a domain or requesting a certificate. If the TXT record is missing, the CLI returns `SERVICE.DOMAIN_OWNERSHIP_REQUIRED` and prints the exact record name and value. Create it, then rerun the suggested command. Re-running `add` for a hostname that's already attached is safe: it shows the existing domain without requiring a new verification step. -### 2. Create CNAME Record +### 2. Add the TXT and CNAME records -Add the printed DNS record, which points at `switchboard.{region}.prisma.build`. +Add the TXT record shown by Console or the CLI. Its value belongs to your workspace. Use the exact value provided; the example below is a placeholder. -Example: -| Type | Name | Value | TTL | -| ----- | --------------- | ------------------------------ | --- | +Also add the routing CNAME, which points at `switchboard.{region}.prisma.build`. If it is not configured yet, `add` returns a DNS error with the CNAME instructions after ownership verification succeeds. + +| Type | Name | Value | TTL | +| --- | --- | --- | --- | +| TXT | `_prisma-verification.shop.acme.com` | `prisma-verification=` | 300 | | CNAME | `shop.acme.com` | `switchboard.cdg.prisma.build` | 300 | -The CLI prints the record name as the full hostname. If your DNS provider expects a relative name, enter just the label (`shop`). +If your provider expects names relative to the `acme.com` zone, use `_prisma-verification.shop` for TXT and `shop` for CNAME. Keep the TXT record: it lets this workspace reconnect the hostname after an app or branch is recreated. Another workspace needs a different value. :::note[What is switchboard?] @@ -56,7 +58,7 @@ Switchboard is the routing layer that sits in front of your Compute app. Switchb ### 3. Re-run `add`, then wait for provisioning -Once the CNAME record has propagated, re-run `service domain add`. This time registration succeeds and TLS provisioning starts. Track it with: +Once both DNS records have propagated, choose **Verify and connect** in Console or rerun the same `service domain add` command, including its branch selector. Registration then starts TLS provisioning. Track it with: ```npm npx prisma service domain wait shop.acme.com --service web @@ -73,10 +75,12 @@ A single check exits non-zero with `DOMAIN_VERIFICATION_TIMEOUT` while the domai ## Remove a domain ```npm -npx prisma service domain remove shop.acme.com --service web +npx prisma service domain delete shop.acme.com --service web ``` -Removing detaches the domain from the app. Pass `--yes` to skip the confirmation prompt. Prisma can't touch your DNS, so the CNAME record stays behind. Delete it at your provider once you no longer need it. +Removing detaches the domain from the app. For a non-interactive run, pass `--confirm shop.acme.com`. Prisma cannot change your DNS. Keep the TXT record if you plan to reconnect the hostname in this workspace; remove both DNS records once you no longer need them. + +Existing connected domains keep serving without adding TXT immediately. A new attachment after removal or branch deletion requires the workspace proof, even when the old CNAME still points at Prisma. ## States @@ -91,7 +95,7 @@ A domain moves through these states: ## Limits -- DNS uses CNAME records only. Apex domains need a DNS provider that supports CNAME-like records (ALIAS, ANAME, or CNAME flattening) at the apex. +- Routing uses a CNAME, and new attachments require a workspace TXT proof. Apex domains need a DNS provider that supports CNAME-like records (ALIAS, ANAME, or CNAME flattening) at the apex. - Wildcard hostnames such as `*.acme.com` are rejected. - Up to 3 custom domains per app. Adding more returns `DOMAIN_QUOTA_EXCEEDED`. - There's no workspace-wide domain list in the CLI. From a0f2b0d09932c152f17793173360391c48e7ef70 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B8ren=20Bramer=20Schmidt?= Date: Fri, 23 Oct 2026 21:16:55 +0700 Subject: [PATCH 2/3] docs(compute): explain Cloudflare proxy setup and renewal --- apps/docs/content/docs/compute/domains.mdx | 23 ++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/apps/docs/content/docs/compute/domains.mdx b/apps/docs/content/docs/compute/domains.mdx index 2738c5f8ac0..8db38d6a02f 100644 --- a/apps/docs/content/docs/compute/domains.mdx +++ b/apps/docs/content/docs/compute/domains.mdx @@ -50,6 +50,29 @@ Also add the routing CNAME, which points at `switchboard.{region}.prisma.build`. If your provider expects names relative to the `acme.com` zone, use `_prisma-verification.shop` for TXT and `shop` for CNAME. Keep the TXT record: it lets this workspace reconnect the hostname after an app or branch is recreated. Another workspace needs a different value. +:::note[Cloudflare DNS] + +Set the hostname's **Proxy status** to **DNS only** (gray cloud) while connecting +the domain. A proxied record returns Cloudflare's IP addresses, which prevents +Prisma from verifying the routing target. If Prisma detects this, Console and the +CLI show instructions to turn the proxy off and retry. + +After Prisma shows the domain as **Active**, you can turn **Proxied** (orange +cloud) back on to use Cloudflare's CDN. Keep the CNAME target and TXT proof in +place, and use **Full (strict)** SSL/TLS mode. + +Prisma renews certificates through HTTP validation. Ensure requests to +`/.well-known/acme-challenge/*` reach Prisma without caching, security challenges, +or rules that rewrite the response. If you reconnect the domain after removing +it or recreating a branch, switch back to **DNS only** for verification. Manual +provisioning retries also check DNS again. + +See Cloudflare's [proxy status](https://developers.cloudflare.com/dns/proxy-status/) +and [Full (strict) TLS](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/full-strict/) +documentation for these settings. + +::: + :::note[What is switchboard?] Switchboard is the routing layer that sits in front of your Compute app. Switchboard verifies the domain, provisions and terminates TLS, then forwards traffic to your app. From 6d60c9542c3af43a3bb08d274f62c5c54742274a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B8ren=20Bramer=20Schmidt?= Date: Sat, 24 Oct 2026 15:54:41 +0700 Subject: [PATCH 3/3] docs(docs): clarify Cloudflare certificate validation --- apps/docs/content/docs/compute/domains.mdx | 23 +++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/apps/docs/content/docs/compute/domains.mdx b/apps/docs/content/docs/compute/domains.mdx index 8db38d6a02f..818d3da6838 100644 --- a/apps/docs/content/docs/compute/domains.mdx +++ b/apps/docs/content/docs/compute/domains.mdx @@ -54,18 +54,27 @@ If your provider expects names relative to the `acme.com` zone, use `_prisma-ver Set the hostname's **Proxy status** to **DNS only** (gray cloud) while connecting the domain. A proxied record returns Cloudflare's IP addresses, which prevents -Prisma from verifying the routing target. If Prisma detects this, Console and the +Prisma from verifying your CNAME target. If Prisma detects this, Console and the CLI show instructions to turn the proxy off and retry. After Prisma shows the domain as **Active**, you can turn **Proxied** (orange -cloud) back on to use Cloudflare's CDN. Keep the CNAME target and TXT proof in +cloud) back on to use Cloudflare's CDN. Keep the CNAME target and TXT record in place, and use **Full (strict)** SSL/TLS mode. -Prisma renews certificates through HTTP validation. Ensure requests to -`/.well-known/acme-challenge/*` reach Prisma without caching, security challenges, -or rules that rewrite the response. If you reconnect the domain after removing -it or recreating a branch, switch back to **DNS only** for verification. Manual -provisioning retries also check DNS again. +Prisma issues and renews certificates automatically. Your app does not need a +route or validation file for `/.well-known/acme-challenge/*` because Prisma +responds to these validation requests. + +If you manage the Cloudflare zone, ensure your Cloudflare rules let these requests +reach Prisma. Custom security challenges, caching, redirects, or Workers can +intercept them before they reach Prisma. Add exceptions only for rules that +interfere with this path. Match requests whose URL path starts with +`/.well-known/acme-challenge/`. See [Cloudflare's validation troubleshooting](https://developers.cloudflare.com/ssl/edge-certificates/changing-dcv-method/troubleshooting/) +for rule checks and examples. + +If you remove a domain from Prisma and add it again, switch back to **DNS only** +for verification. The [`service domain retry` command](#troubleshooting) also +requires **DNS only** because it checks DNS again. See Cloudflare's [proxy status](https://developers.cloudflare.com/dns/proxy-status/) and [Full (strict) TLS](https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/full-strict/)