Web and custom domains

Open a canister’s Web and domains section to serve its website on a domain you own, such as app.example.com. It shows the domains it already serves and the state of each.

1. Add a domain and enter the hostname.

2. Prove ownership. Add the three DNS records; each shows Pending until icLens sees it with the right value, then Done. Add the domain to the canister’s /.well-known/ic-domains file; icLens can upload it for you, in a separate review, if you control the canister. Add the same line to your project, and include .well-known in .ic-assets.json, or your next deploy removes it. Continue unlocks when the gateway accepts DNS and ownership.

3. Register. Choose Register domain and confirm. The certificate and routing follow a few minutes later.

While you wait, the page checks every minute. Waiting is not an error: only a domain that points to a different canister is.

Update or remove a domain

Use the domain’s menu. To remove it, first delete its _canister-id TXT record at your DNS provider; icLens confirms the record is gone, then removes the registration.

Good to know

• Registration works on Mainnet only. You can plan on a local network.
• Domains don’t spend the canister’s cycles, change its controllers or edit your DNS.
• If your app uses Internet Identity, a new domain can give users different principals. Set up your app’s alternative origins before switching.
• A deploy replaces the ic-domains file with your project’s copy, and skips .well-known unless .ic-assets.json has { "match": ".well-known", "ignore": false }.