Document: initial run @hostname error on Mac with stale DNS cache (#138) · Issues · Site.js / app

Document: initial run @hostname error on Mac with stale DNS cache

This is not a bug but a situation you can run into that should be documented (for the time being, documenting it here):

Scenario

You hit (e.g.) mac.my.domain with the DNS not set up for it.
You set up a CNAME for mac.my.domain.
You start a server @hostname (with your hostname correctly set to the above).
Perhaps you expose your server via ngrok, etc.
You hit the hostname in the browser again.

What could happen

If Safari/the system caches the incorrect DNS lookup, your automatic Let's Encrypt TLS certificate provisioning can fail with the following error:

[acme-v2] handled(?) rejection as errback:
Error: getaddrinfo ENOTFOUND mac.my.domain mac.my.domain:80
    at GetAddrInfoReqWrap.onlookup [as oncomplete] (dns.js:56:26)
Error loading/registering certificate for 'mac.my.domain':
{ Error: getaddrinfo ENOTFOUND mac.my.domain mac.my.domain:80
    at GetAddrInfoReqWrap.onlookup [as oncomplete] (dns.js:56:26)
  errno: 'ENOTFOUND',
  code: 'ENOTFOUND',
  syscall: 'getaddrinfo',
  hostname: 'mac.my.domain',
  host: 'mac.my.domain',
  port: 80 }

The fix

You must clear your DNS cache:

sudo killall -HUP mDNSResponder;sudo killall mDNSResponderHelper;sudo dscacheutil -flushcache

This is not a bug but a situation you can run into that should be documented (for the time being, documenting it here):

## Scenario

1. You hit (e.g.) `mac.my.domain` with the DNS not set up for it.
2. You set up a CNAME for `mac.my.domain`.
3. You start a server @hostname (with your hostname correctly set to the above).
4. Perhaps you expose your server via ngrok, etc.
5. You hit the hostname in the browser again.

## What could happen

If Safari/the system caches the incorrect DNS lookup, your automatic Let's Encrypt TLS certificate provisioning can fail with the following error:

```sh
[acme-v2] handled(?) rejection as errback:
Error: getaddrinfo ENOTFOUND mac.my.domain mac.my.domain:80
    at GetAddrInfoReqWrap.onlookup [as oncomplete] (dns.js:56:26)
Error loading/registering certificate for 'mac.my.domain':
{ Error: getaddrinfo ENOTFOUND mac.my.domain mac.my.domain:80
    at GetAddrInfoReqWrap.onlookup [as oncomplete] (dns.js:56:26)
  errno: 'ENOTFOUND',
  code: 'ENOTFOUND',
  syscall: 'getaddrinfo',
  hostname: 'mac.my.domain',
  host: 'mac.my.domain',
  port: 80 }
```

## The fix

You must clear your DNS cache:

```sh
sudo killall -HUP mDNSResponder;sudo killall mDNSResponderHelper;sudo dscacheutil -flushcache
```