IC Custom Domain Setup Runbook

Overview

This runbook documents how to configure custom domains for Internet Computer canisters. IC uses DNS TXT records to map custom domains to canister IDs.

Prerequisites

• Access to DNS management (GoDaddy for helloworlddao.com)
• Canister deployed to IC mainnet
• Canister ID (get via dfx canister --network ic id <canister-name>)

How IC Custom Domains Work

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  User Browser   │────▶│  IC Boundary     │────▶│   Canister      │
│                 │     │  Nodes           │     │                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │                       │
        │  1. Request to        │  2. Lookup TXT record
        │     custom domain     │     _canister-id.domain
        │                       │
        │                       │  3. Route to canister
        │                       │     + generate SSL cert

IC boundary nodes:

1. Receive requests for custom domains
2. Query DNS for _canister-id.<domain> TXT record
3. Route traffic to the specified canister
4. Automatically provision Let's Encrypt SSL certificates

Current Domain Configuration

Domain	Canister	Canister ID	Status
staging.helloworlddao.com	www (frontend)	vlmti-wqaaa-aaaad-acoiq-cai	✅ Working
staging-admin.helloworlddao.com	admin	ehbll-kiaaa-aaaac-qc2aa-cai	✅ Working
www.helloworlddao.com	www (frontend)	vlmti-wqaaa-aaaad-acoiq-cai	⚠️ Not configured

Step 1: Get Canister ID

# Set environment to suppress warnings
export DFX_WARNING=-mainnet_plaintext_identity

# Get canister ID
cd /home/coby/git/frontend
dfx canister --network ic id admin
# Output: ehbll-kiaaa-aaaac-qc2aa-cai

dfx canister --network ic id www
# Output: vlmti-wqaaa-aaaad-acoiq-cai

Step 2: Configure DNS Records

Required Records

For each custom domain, add these DNS records in GoDaddy:

A Record (Points domain to IC)

Type: A
Name: <subdomain> (e.g., "staging-admin" or "staging")
Value: 23.142.184.129
TTL: 600

Note: IC boundary nodes are at multiple IPs. Using icp0.io as CNAME is preferred:

Type: CNAME
Name: <subdomain>
Value: icp0.io
TTL: 600

TXT Record (Links domain to canister)

Type: TXT
Name: _canister-id.<subdomain>
Value: <canister-id>
TTL: 600

Example: staging-admin.helloworlddao.com

# Option 1: CNAME (preferred)
Type: CNAME
Name: staging-admin
Value: icp0.io
TTL: 600

# Required: Canister ID TXT record
Type: TXT
Name: _canister-id.staging-admin
Value: ehbll-kiaaa-aaaac-qc2aa-cai
TTL: 600

Example: www.helloworlddao.com (Production)

# Option 1: CNAME
Type: CNAME
Name: www
Value: icp0.io
TTL: 600

# Required: Canister ID TXT record
Type: TXT
Name: _canister-id.www
Value: vlmti-wqaaa-aaaad-acoiq-cai
TTL: 600

Step 3: Verify DNS Propagation

Wait 5-15 minutes for DNS propagation, then verify:

# Check A/CNAME record
dig staging-admin.helloworlddao.com +short
# Should return: icp0.io or 23.142.184.129

# Check TXT record (critical!)
dig _canister-id.staging-admin.helloworlddao.com TXT +short
# Should return: "ehbll-kiaaa-aaaac-qc2aa-cai"

Step 4: Register Domain with IC API

CRITICAL: DNS records alone are not enough. You must explicitly register the domain with IC's custom domain API:

# Validate configuration first
curl -s "https://icp0.io/custom-domains/v1/staging-admin.helloworlddao.com/validate" | jq .

# Register the domain (required!)
curl -s -X POST "https://icp0.io/custom-domains/v1/staging-admin.helloworlddao.com" | jq .

# Check registration status
curl -s "https://icp0.io/custom-domains/v1/staging-admin.helloworlddao.com" | jq .

Expected registration flow:

1. validation_status: "valid" - DNS is correctly configured
2. registration_status: "registering" - Processing request
3. registration_status: "registered" - Complete, SSL will be provisioned

Step 5: Verify SSL Certificate

After registration completes, IC will provision SSL. Verify:

# Check SSL certificate
echo | openssl s_client -connect staging-admin.helloworlddao.com:443 \
  -servername staging-admin.helloworlddao.com 2>&1 | grep "subject="
# Should return: subject=CN = staging-admin.helloworlddao.com

If SSL shows wrong domain (e.g., ai.icpex.org):

• TXT record is missing or incorrect
• DNS hasn't propagated yet
• Wait 10-15 minutes and retry

Step 6: Test the Domain

# Test HTTPS
curl -s -o /dev/null -w "%{http_code}\n" https://staging-admin.helloworlddao.com

# Should return: 200

Troubleshooting

Problem: SSL Certificate Mismatch (Wrong Domain)

Symptom: Browser shows SSL error, certificate for wrong domain (e.g., ai.icpex.org)

Cause: Domain was never registered with IC's custom domain API

Solution:

1. Check registration status:

   curl -s "https://icp0.io/custom-domains/v1/YOUR_DOMAIN" | jq .

2. If not_found, register the domain:

   curl -s -X POST "https://icp0.io/custom-domains/v1/YOUR_DOMAIN" | jq .

3. Wait for registration_status: "registered"
4. Certificate will be provisioned automatically

Problem: _canister-id TXT Record Missing

Symptom: Validation fails, can't register domain

Cause: _canister-id TXT record missing or incorrect

Solution:

1. Verify TXT record: dig _canister-id.<domain> TXT +short
2. If missing, add the TXT record in DNS
3. Wait 10-15 minutes for propagation
4. Re-run validation and registration

Problem: DNS Not Resolving

Symptom: dig <domain> +short returns nothing

Cause: A/CNAME record missing

Solution:

1. Add A record pointing to 23.142.184.129 or CNAME to icp0.io
2. Wait 5-10 minutes for propagation

Problem: HTTP 308 Redirect Loop

Symptom: Constant redirects, never loads

Cause: Usually a caching issue

Solution:

1. Clear browser cache
2. Try incognito/private window
3. Try curl -L to follow redirects

Problem: Canister Returns 404

Symptom: Domain works but shows 404

Cause: Canister assets not deployed or wrong path

Solution:

1. Verify canister has assets: dfx canister --network ic info <name>
2. Redeploy if needed: dfx deploy --network ic <name>

Fallback: Raw IC URL

If custom domain isn't working, use the raw IC URL:

Canister	Raw URL
Frontend (www)	https://vlmti-wqaaa-aaaad-acoiq-cai.icp0.io/
Admin	https://ehbll-kiaaa-aaaac-qc2aa-cai.icp0.io/

DNS Records Checklist

Staging Environment

Record Type	Name	Value	Status
CNAME/A	staging	icp0.io	✅
TXT	_canister-id.staging	vlmti-wqaaa-aaaad-acoiq-cai	✅
CNAME/A	staging-admin	icp0.io	✅
TXT	_canister-id.staging-admin	ehbll-kiaaa-aaaac-qc2aa-cai	✅

Production Environment

Record Type	Name	Value	Status
CNAME/A	www	icp0.io	⚠️ Configure when ready
TXT	_canister-id.www	vlmti-wqaaa-aaaad-acoiq-cai	⚠️ Configure when ready
CNAME/A	admin	icp0.io	⚠️ Future
TXT	_canister-id.admin	TBD	⚠️ Future

Related Documentation

• IC Custom Domains Documentation
• Oracle Bridge DNS Setup
• GoDaddy DNS Management

Estimated Time

• DNS record addition: 5 minutes
• DNS propagation: 5-15 minutes
• SSL certificate provisioning: 5-10 minutes
• Total: ~15-30 minutes