carlos / carloku Public

Download this file

1	# Custom domains
2
3	Your app already answers on a hostname the platform gave it, something
4	like `hello.bdf.oncarlos.com`. Attaching your own domain is two moves:
5	tell Carloku the hostname is yours, then point a DNS record at it. The
6	platform hostname keeps working afterwards, so you can do all of this
7	before you switch any traffic over.
8
9	```sh
10	carlos domains attach -app hello www.example.com
11	```
12
13	Leave `-route` off when the app has one instance — the command works out
14	what to point the hostname at. With several, name the one you mean.
15
16	## The DNS record
17
18	Attach finishes by printing the record to create and the hostname's
19	current DNS state, so you need neither a second command nor a trip to the
20	console to know what is left. Usually that is an A record at this
21	deployment's edge addresses, named for you rather than left to look up.
22	Where the deployment offers a steering hostname, a subdomain is offered a
23	CNAME at that instead: visitors then reach the nearest healthy edge, and
24	a failed edge drops out of the answer on its own. An apex domain —
25	`example.com` with nothing in front of it — always takes the A record,
26	because a CNAME cannot legally sit at the apex.
27
28	Create the record with whoever runs your DNS. Checks run every few
29	minutes, so there is nothing to trigger.
30
31	## Watching it come live
32
33	```sh
34	carlos domains list -app hello
35	```
36
37	Each row is one claim joined to what the fleet actually observes: which
38	route it points at, whether the hostname resolves to the edge, when its
39	certificate expires, and — while it isn't pointing yet — the same
40	instruction attach printed. Certificates are minted and renewed for you;
41	there is no step here you own.
42
43	The claim itself reaches the boxes within seconds of the attach, so a row
44	that still reads `pending` a minute later is unusual. The DNS column is
45	the slow half. It stays unhelpful until your record has propagated, and
46	nothing on this side can hurry that along.
47
48	## Taking one off
49
50	```sh
51	carlos domains detach -app hello www.example.com
52	```
53
54	The boxes serving the app notice within seconds and stop answering for
55	the hostname, the same way they picked it up when you attached it. Your
56	DNS record is yours to clean up afterwards.
57
58	## Wildcards
59
60	Two flags on
61	[attach](https://carlosframework.com/docs/cli/#carlos-domains) cover the
62	give-every-customer-a-subdomain case. `-wildcard` enables a delegated
63	wildcard certificate for the hostname; `-catchall` derives a `*.<host>`
64	alias onto the same route. Both need DNS delegation in place, and attach
65	refuses with the reason when it isn't. Attaching one marketing domain
66	needs neither.
67
68	Neither flag has a default position either. Naming one changes it and
69	leaving it off leaves it alone, so you can turn a wildcard on months
70	later without restating anything else about the claim.
71