Add a custom domain
Attach your own hostname to an app or site target, verify DNS, and get a certificate
Goal. api.acme.example serves api over HTTPS with a certificate Pier issues and
renews.
Declare the domain
pier add domain api.acme.example --app api
Changes:
~ update app "api" in prod
domain: api.acme.example (policy — applied immediately)
→ Updated pier.yaml
→ Waiting for infrastructure provisioning...
OK Infrastructure ready
OK Added domain api.acme.example to app "api"
The domain attaches to a target (--app api/canary for another target; --site www for
a site).
Create the DNS records
Two records at your DNS provider, as the output shows:
| Record | Name | Value | Proves |
|---|---|---|---|
CNAME | api.acme.example | the target's hostname (<id>.app.pier.run) | routing |
TXT | _pier.api.acme.example | pier-verify=<token> | ownership |
Pier re-checks until both resolve, then issues the certificate.
pier ls domains→ No custom domains.
pending becomes verified, and TLS active, once DNS has propagated. This usually
takes minutes and at most the record's TTL.
What changed
apps:
- name: api
targets:
- name: primary
plan: app-s
domains:
- host: api.acme.exampleVariations
- An apex domain (
acme.example): providers that cannot CNAME an apex offer ALIAS/ANAME records; use one with the same target. - A site:
pier add domain www.acme.example --site www; sites use a shared CNAME target, shown in the output. - Remove:
pier rm domain api.acme.example.