gcx/docs/migration-guide.md

DNS Migration Guide: Namecheap to External Providers

When managing 30+ records with frequent changes, Namecheap's overwrite-only API becomes a liability. This guide covers migrating DNS resolution to a better API provider while keeping domain registration at Namecheap.

Why Migrate DNS Away from Namecheap?

Issue	Impact
setHosts overwrites all records	Risk of accidental deletion
No single-record CRUD	Every change requires full read-write cycle
No SRV support via API	Manual work for some services
XML responses	More complex parsing than JSON
IPv4-only whitelist	Limits deployment environments

Recommended Alternatives

Option 1: Cloudflare DNS (Recommended for most cases)

• Free plan includes DNS management
• RESTful JSON API with per-record CRUD
• Official SDKs in Python, Go, Node.js, etc.
• Terraform provider available
• Built-in DDoS protection and CDN
• API Token authentication (scoped permissions)

Option 2: Alibaba Cloud DNS (Recommended for China-focused services)

• Better performance for China mainland users
• Full per-record CRUD API
• Multi-language SDK support
• RAM sub-user permission control
• Use the aliyun-dns skill for management

Migration Steps

Step 1: Export Current Records

python namecheap_manager.py export --domain gogenex.com --output current_records.json

Step 2: Set Up New DNS Provider

For Cloudflare:

1. Create a Cloudflare account and add your domain
2. Cloudflare will scan and import existing records
3. Verify all records were imported correctly against current_records.json
4. Note the assigned Cloudflare nameservers (e.g., adam.ns.cloudflare.com)

For Alibaba Cloud DNS:

1. Add domain in Alidns console
2. Import records using: python alidns_batch.py --domain gogenex.com --plan current_records.json
3. Note the assigned Alidns nameservers (e.g., dns1.hichina.com)

Step 3: Switch Nameservers at Namecheap

# For Cloudflare
python namecheap_manager.py set-ns --domain gogenex.com \
    --nameservers adam.ns.cloudflare.com betty.ns.cloudflare.com

# For Alibaba Cloud
python namecheap_manager.py set-ns --domain gogenex.com \
    --nameservers dns1.hichina.com dns2.hichina.com

Step 4: Verify Propagation

DNS propagation typically takes 24-48 hours. Monitor with:

# Check which nameservers are responding
dig NS gogenex.com

# Verify specific records
dig api.gogenex.com
dig mpc.gogenex.com

Step 5: Post-Migration Cleanup

• Update any DDNS scripts to use the new provider's API
• Update Let's Encrypt certbot plugins (e.g., switch from certbot-dns-namecheap to certbot-dns-cloudflare)
• Update CI/CD pipelines that manage DNS
• Keep Namecheap account active for domain renewal

Rollback Plan

If issues arise, switch back to Namecheap nameservers:

python namecheap_manager.py set-ns --domain gogenex.com \
    --nameservers dns1.registrar-servers.com dns2.registrar-servers.com

Note: Namecheap default nameservers may vary. Check your Namecheap dashboard for the correct values.