Custom Domains & DNS

Overview

Savannah Cloud manages DNS for custom domains via PowerDNS. The full flow:

1. Add a domain in the dashboard (/domains) or via API
2. Point your registrar's nameservers to Savannah's nameservers
3. Background verifier confirms your domain every 5 minutes
4. Once verified, use the domain for deployments and email

Savannah Nameservers:

ns1.savannahcloud.com
ns2.savannahcloud.com

VPS IP (what A records should resolve to): 178.105.152.34

Step 1 — Add Your Domain

Via dashboard (/domains) or API:

curl -X POST https://api.savannahcloud.com/domains \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"app.acme.com"}'

The API returns:

{
  "id": "dom_abc123",
  "hostname": "app.acme.com",
  "nameservers": ["ns1.savannahcloud.com", "ns2.savannahcloud.com"],
  "verified": false
}

Step 2 — Delegate Nameservers

At your domain registrar (Namecheap, GoDaddy, Cloudflare, etc.), update the nameservers for your domain to:

ns1.savannahcloud.com
ns2.savannahcloud.com

Step 3 — Wait for Verification

The background DNS verifier runs every 5 minutes. It:

1. Resolves your domain's A record via Google DNS (8.8.8.8)
2. Checks if it matches 178.105.152.34
3. Sets verified=true in the database when matched

To trigger verification manually without waiting:

curl -X POST https://api.savannahcloud.com/domains/dom_abc123/verify \
  -H "Authorization: Bearer YOUR_JWT"

Step 4 — Use Your Domain

Once verified, your custom domain can be used as:

• Deployment URL — map the domain to a specific deployment
• Email sender — the dashboard compose UI shows verified domains as From options

Troubleshooting

Domain not verifying?

# Check what the domain resolves to
nslookup app.acme.com 8.8.8.8

# Should return: 178.105.152.34

Nameservers not propagating?

Check propagation at whatsmydns.net using NS record type.

Need to remove a domain?

curl -X DELETE https://api.savannahcloud.com/domains/dom_abc123 \
  -H "Authorization: Bearer YOUR_JWT"