@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
mdx 162 lines 6.21 KB
Raw
1 ---
2 title: Custom domains
3 description: Register a Function hostname, configure DNS and CAA, verify HTTPS, and retire the domain safely.
4 ---
5
6 A Neon custom domain maps one hostname to one Function on one branch. Alchemy
7 registers that mapping and returns the DNS target; your DNS provider and Neon
8 certificate provisioning complete the setup. Start with [Setup](/neon/setup) and
9 a Function whose native URL already works.
10
11 ## Prepare a hostname
12
13 Use a domain you control and arrange permission to edit its DNS. Prefer a
14 subdomain such as `api.example.com`: a standard CNAME cannot be placed at a zone
15 apex without provider-specific flattening. Reserve a different hostname for each
16 preview; custom domains are not inherited by child branches.
17
18 Confirm whether another application already uses the hostname before changing
19 its records. A hostname can belong to only one Function target at a time.
20
21 ## Register the Function domain
22
23 Inside your stack, using an existing `api` Function:
24
25 ```typescript
26 import * as Neon from "@alchemy.run/neon";
27
28 const domain = yield* Neon.CustomDomain("ApiDomain", {
29 function: api,
30 hostname: "api.example.com",
31 });
32 ```
33
34 Return `domain.cnameTarget` in the stack outputs so the DNS operator can copy the
35 exact target after deployment. Registration intentionally does not wait for DNS,
36 which lets you create the DNS record afterward.
37
38 ## Use the Website alternative
39
40 For a Website, use its `domain` prop instead of declaring a second registration
41 for the same hostname:
42
43 ```typescript
44 const site = yield* Neon.Website.Vite("Web", {
45 branch,
46 rootDir: "./web",
47 domain: "app.example.com",
48 });
49 ```
50
51 The live Website exposes the registration as `site.domain` and its target as
52 `site.domain.cnameTarget`. During native local development there is no domain
53 registration; use the local dev URL. A returned custom URL is not proof that DNS
54 or HTTPS is ready.
55
56 ## Publish a DNS-only CNAME
57
58 At your DNS provider, configure:
59
60 | Field | Value |
61 | --- | --- |
62 | Type | `CNAME` |
63 | Name | `api` or `api.example.com`, according to the provider's UI |
64 | Target | The exact `cnameTarget` output, without `https://` or a path |
65 | Proxy | Disabled / DNS-only; on Cloudflare this is the grey cloud |
66 | TTL | Your DNS provider's normal value |
67
68 After reviewing their ownership, remove conflicting A, AAAA, or CNAME records for
69 that hostname. A proxy can prevent Neon validation even when the browser appears
70 to reach an edge server. Wait for the applicable DNS TTL before judging propagation.
71
72 If the domain's DNS is in Cloudflare, Route 53, or Hetzner DNS, the Website can
73 publish the CNAME for you. Pass the DNS host as `dns`, and keep Cloudflare records
74 DNS-only (the default):
75
76 ```typescript
77 const site = yield* Neon.Website.Vite("Web", {
78 branch,
79 rootDir: "./web",
80 domain: { name: "app.example.com", dns: Cloudflare.DNS.Adapter() },
81 });
82 ```
83
84 See [DNS Adapters](/infrastructure-as-code/dns-adapters).
85
86 ## Check certificate-authority restrictions
87
88 If your domain or an applicable parent has CAA records, the policy must allow
89 Let's Encrypt, the certificate authority Neon uses. Have the DNS/security owner
90 approve the change, then authorize it as described in
91 [Neon's domain guide](https://neon.com/docs/compute/functions/custom-domains#configure-dns):
92
93 ```text
94 CAA 0 issue "letsencrypt.org"
95 ```
96
97 A domain without a restrictive CAA policy does not need this extra record merely
98 to satisfy Alchemy.
99
100 ## Check registration status
101
102 In the Neon Console, select the project and branch, then open **Settings →
103 Functions → Custom Domains**. Check the target Function, DNS status, and any
104 reported reason. The resource also exposes `status`, `dnsStatus`, `bindingStatus`,
105 and `statusReason` when returned by Neon.
106
107 | Reported problem | Action |
108 | --- | --- |
109 | `cname-not-pointing-at-edge` | Correct the target, disable DNS proxying, remove conflicts, and allow propagation |
110 | `caa-blocks-lets-encrypt` | Review CAA on the hostname and its parent domains; authorize Let's Encrypt |
111 | `binding-missing` | Verify the intended Function still exists; contact Neon Support if internal routing remains missing |
112 | Hostname already registered elsewhere | Resolve ownership of the existing mapping; do not bypass it with blanket adoption |
113
114 ## Verify HTTPS and application behavior
115
116 Resolve the public CNAME:
117
118 ```sh
119 dig +short CNAME api.example.com
120 ```
121
122 Then request a known route that your Function implements:
123
124 ```sh
125 curl --fail-with-body --max-time 30 https://api.example.com/health
126 ```
127
128 Check the expected response, not only a successful status. Keep TLS verification
129 enabled; `curl -k` would hide a certificate failure. Neon may issue the certificate
130 on the first request. If the registration is active but HTTPS initially fails,
131 allow a short issuance delay and retry once; persistent failures need diagnostics,
132 not an unbounded retry loop.
133
134 Open the application through the custom hostname and exercise sign-in, navigation,
135 redirects, and any streaming/WebSocket features it uses. Registration status
136 `active` establishes DNS/CAA/routing, not completed application acceptance.
137
138 ## Secure both URLs
139
140 The native Neon Function URL remains public when a custom domain is added.
141 Authenticate and authorize protected work on both entry points. Browser clients
142 may also require application CORS configuration. For Auth redirects, register the
143 custom application's origin separately using
144 [Production Auth](/neon/guides/production-auth).
145
146 ## Retire the hostname
147
148 Remove the DNS record first, then wait for public DNS to stop returning the Neon
149 target. Only then remove the CustomDomain declaration and deploy, or destroy its
150 owning stack. This avoids leaving a dangling CNAME after releasing the hostname.
151 If DNS is managed in a separate stack or by another team, coordinate the ordering
152 rather than assuming Function destruction also removes DNS.
153
154 Confirm the custom URL no longer serves the retired application before reusing
155 the hostname. Keep the original stack/stage state until cleanup finishes; see
156 [State and recovery](/neon/guides/state-recovery).
157
158 ## Related guides
159
160 - [CustomDomain reference](/providers/neon/customdomain) — inputs, outputs, and lifecycle.
161 - [Neon custom domains](https://neon.com/docs/compute/functions/custom-domains) — current DNS, CAA, and status behavior.
162 - [Setup](/neon/setup) — deployment prerequisites.