Skip to main content

DNS & TLS

The web container's nginx terminates TLS for three hostnames out of the box: the apex, www., and api.. All three must resolve to the host IP and all three must have valid certificates before traffic flows.

DNS records​

Assuming your host's public IP is <HOST_IP>:

RecordTypeHostValue
ApexA@<HOST_IP>
SubdomainAwww<HOST_IP>
SubdomainAapi<HOST_IP>

CNAMEs from www / api to the apex also work, but A records are the simplest and avoid CNAME-flattening edge cases.

After updating DNS, verify from outside your network:

dig @8.8.8.8 clone.is A +short
dig @8.8.8.8 www.clone.is A +short
dig @8.8.8.8 api.clone.is A +short

All three should print <HOST_IP>.

TLS certificates​

The web container mounts /etc/letsencrypt from the host read-only. The simplest way to issue certificates is on the host with certbot against the running nginx:

sudo apt install certbot
sudo certbot certonly --webroot -w /var/www/letsencrypt \
  -d clone.is -d www.clone.is -d api.clone.is

Or run certbot's standalone mode while web is briefly down. After issuance, the cert lives at /etc/letsencrypt/live/<domain>/{fullchain,privkey}.pem, and apps/web/nginx.conf references the path directly:

ssl_certificate     /etc/letsencrypt/live/clone.is/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/clone.is/privkey.pem;

Renewal is automatic via certbot's systemd timer; nginx reloads on the next request after the cert rotates (or you can docker compose exec web nginx -s reload).

The api.clone.is NXDOMAIN gotcha​

A subdomain can be live in the registrar's nameservers and on Google/Cloudflare resolvers (8.8.8.8, 1.1.1.1) while a specific ISP's resolver still serves a cached NXDOMAIN from the previous unconfigured state. The negative TTL is whatever the SOA records — for Namecheap-hosted DNS the default is roughly an hour.

Symptoms:

  • The MCP server fails with network error talking to https://api.clone.is/...: fetch failed.
  • dig @8.8.8.8 api.clone.is returns the right IP.
  • dig api.clone.is (your default resolver) returns only an SOA / NXDOMAIN.

Fixes, in increasing order of reach:

  1. Wait the negative TTL out (typically ≤ 1 hour).
  2. Switch the affected client to a public resolver (8.8.8.8 / 1.1.1.1) — fastest unblock without touching DNS.
  3. Pin the host with /etc/hosts on the affected machine — a one-line <HOST_IP> api.<your-domain> is a clean local override and harmless to remove later. Do not ship this in a Dockerfile.

Updating server names​

If you fork the repo and rename, edit:

  • apps/web/nginx.conf — server_name, ssl_certificate* paths, and the 301 redirect server.
  • docker-compose.yml — ALLOWED_HOSTS for the api service.
  • apps/docs/docusaurus.config.ts — url, editUrl, footer hrefs.
  • apps/mcp/src/index.ts — DEFAULT_BASE_URL (only if running stdio mode against the public API by default).