Documentation Edit this page

NamecheapProxy

A hosted DNS proxy: call url://namecheap/ to create, update, and delete subdomains (DNS records) on the operator's Namecheap domains without holding the Namecheap credential. It is a third-party service proxy (sibling to GitHub Proxy and CockroachDb) whose defining property is being a stable-IP whitelisted egress: Namecheap authenticates each API call against a whitelist of client IPs, and because this service runs on the ContainerNursery host's single stable IP (already whitelisted with Namecheap), any consumer — however dynamic or unknowable its own IP — can manage DNS through it. See the project overview.

Architecture

Consumer (CLI / agent / service)
   │  url:// protocol via UrlResolver (sandboxed client library)
   ▼
NamecheapProxyServerService (url://namecheap/)
   │  delegates to
   ▼
NamecheapApi (Namecheap registrar client)
   │  HTTPS (source IP = the whitelisted ContainerNursery host IP)
   ▼
Namecheap DNS API (api.namecheap.com)

Namecheap's write API (setHosts) replaces a domain's entire record set at once, so each upsertRecord/deleteRecord is a read-modify-write serialized behind a per-domain lock (no lost updates), preserving the domain's EmailType. The apex (@) record and NS records are refused by default. This first release is a single ambient-account deployment (one Namecheap credential from the environment, vended to all callers).

Deployment

Deployed on the ContainerNursery host (198.199.106.165) as a url:// facade route. The CN CLI cannot express the url facade, so the route is created via the admin API:

# 1. Upload the fat jar to the host
scp namecheap-proxy-server-service.jar \
  root@198.199.106.165:/root/ContainerNursery/apps/namecheap-proxy-server-service.jar

# 2. Create the url:// route (admin API at api.nursery.wasmserver.com)
curl -X POST https://api.nursery.wasmserver.com/routes -H "Content-Type: application/json" -d '{
  "facade":   { "provider": "url", "configuration": { "domain": "namecheap", "transport": "RPC" } },
  "container": {
    "provider": "danger_jarfile",
    "configuration": { "image": "/root/ContainerNursery/apps/namecheap-proxy-server-service.jar" },
    "memoryLimitMb": 256, "keepWarmSeconds": 300, "allowConflictingJvmFlags": true,
    "envvars": {
      "JAVA_TOOL_OPTIONS": "-XX:+UseSerialGC -XX:MinHeapFreeRatio=10 -XX:MaxHeapFreeRatio=20 -Xss512k -XX:MaxDirectMemorySize=128m",
      "NAMECHEAP_API_USER": "<api-user>",
      "NAMECHEAP_API_KEY":  "<api-key>",
      "NAMECHEAP_CLIENT_IP": "198.199.106.165"
    }
  }
}'

ContainerNursery supplies URL_BIND_DOMAIN/PORT for lazy-start; absent URL_BIND_DOMAIN the server runs in standalone P2P mode. Set NAMECHEAP_SANDBOX=true to target Namecheap's sandbox endpoint. See the ServiceServer README for the full environment-variable table.

Configuration notes

• NAMECHEAP_CLIENT_IP must be the ContainerNursery host's public IP (198.199.106.165) and that IP must be whitelisted in the Namecheap account's API settings — this is the whole basis of the stable-IP egress. The host IP is already whitelisted for the operator's account.
• Env vars, memoryLimitMb, and keepWarmSeconds must sit at the container block level (not inside container.configuration), or ContainerNursery silently drops them.

Health Checks

• Production Health: namecheapproxy.healthcheck:namecheap-proxy-health-check registered with productionhealth.wasmserver.com — connects over url://, checks isConnected, lists domains, and runs a self-cleaning create/read/delete TXT round-trip on a _nchealthcheck record, restoring the zone.
• The check can also be run standalone: java -jar namecheap-proxy-health-check.jar.

Notes

• DNS for the operator's domains is managed via Namecheap (see infrastructure/domains.md); this service makes that management available programmatically over url:// to the whole fleet.