---
name: shipholm-custom-domain
description: "Serve a Shipholm app on the user's own domain (a subdomain, the apex or both with www) with HTTPS, or move a domain from another host such as Lovable. Use when the user wants their own address instead of, or as well as, <app>.shipholm.dev."
---

# Your own domain
Serve an app on shop.example.com, or on example.com and www.example.com, as well as its .shipholm.dev address.

## Steps
1. `add_domain(app="shop", domain="shop.example.com")` returns the records to create:
   - TXT `_shipholm.shop.example.com` = `shipholm-verify=<token>` proves you control the domain,
   - CNAME `shop.example.com` → `shop.shipholm.dev` routes the traffic. For an apex domain like
     `example.com` you get A records instead, one per address returned. Create all of them, so
     the site stays up if a node is down.
2. Create them at the DNS provider. On Cloudflare set the records to **DNS only** (grey cloud):
   the platform gets its own certificate, and a proxy in front breaks that.
3. `verify_domain(app="shop", domain="shop.example.com")` checks the TXT record. Once it is
   verified and the domain points here, the certificate follows within a minute or two
   (`app_status` shows it). Renewal is automatic.
4. Check it: `curl -sI https://shop.example.com/` and the certificate's issuer and dates:
   `openssl s_client -connect shop.example.com:443 -servername shop.example.com </dev/null | openssl x509 -noout -issuer -dates`.

## Apex and www
Add both as domains of the same app (`example.com` and `www.example.com`). Each gets its own
TXT record and certificate. Choose one as the canonical address and let the app redirect the
other with a 301 that keeps the path and query. Otherwise search engines see two copies of
every page. The app does that: compare the `Host` header with its `SITE_URL`, and leave
`/healthz` and `<app>.shipholm.dev` alone.

## Many apps under one domain
One `add_domain` per app (`glosboken.example.com`, `korsord.example.com` …), each with its own
TXT and CNAME. A specific record wins over a wildcard (`*.example.com`), so you can move one
subdomain at a time while the wildcard still points at the old host.

## Moving a site from another host
Verification needs only the TXT record, so the old host keeps serving while you get ready.
1. Lower the TTL of the records you will change (300 s) a while before.
2. `add_domain`, create the TXT records, `verify_domain`. Nothing changes for visitors yet.
3. Make sure the app on Shipholm is complete first: deployed, data imported, pages checked on
   `<app>.shipholm.dev`.
4. Switch the routing records last. A name cannot have both a CNAME and A records, so delete
   the old host's records and create the new ones right after. The old host's records are
   often proxied A records (Lovable's was 185.158.133.1, proxied); the new ones are DNS only.
   Expect a minute or two without a valid certificate.
5. Check from outside: `dig +short @1.1.1.1 example.com` shows the new addresses, then the
   curl and openssl checks above for every name.
6. Remove the domain from the old host's settings, so it stops renewing a certificate for it.

## Pitfalls
- Leave mail records (MX, SPF, DKIM, DMARC) alone. They are independent of the web records;
  on an apex, the SPF TXT record sits next to the A records.
- A proxied (orange) Cloudflare record, or a CAA record that excludes Let's Encrypt, stops the
  certificate.
- A domain that points here but was never added with `add_domain` gets a 404 from the platform,
  not the app.
- Verification records from before the rename (`_agentbuild.<domain>`) still verify.
