Your website on your own domain

Every Subcontext site has an address of its own, <your site>.sites.subcontext.com. To show the same site at an address on your domain, such as quote.example.com, you put a CDN (content delivery network) or reverse proxy in front of it. Your CDN holds the certificate for your hostname and passes visitors' requests to Subcontext.

Subcontext doesn't issue certificates for your domain. A plain CNAME pointing at Subcontext isn't enough on its own, because visitors would get a certificate warning.

How it fits together#

visitor -> quote.example.com -> your CDN                -> sites-origin.subcontext.com
           (your DNS record)    (your certificate;         (Subcontext picks the site
                                 Host passed unchanged)      from the Host header)

Adding the domain#

In the dashboard, open Sites, then the site, then Manage on its Custom domains card. Enter the hostname under Add a domain. Add each hostname separately. www.example.com and example.com are two domains.

The domain's page shows the setup steps, the Origin, and the verification address for that hostname.

Setting up your CDN#

Whatever CDN or proxy you use, it needs these five things:

It also needs a certificate for your hostname. Most CDNs issue one for free once the hostname is added.

Amazon CloudFront#

• Certificate: request one in AWS Certificate Manager in us-east-1 (CloudFront only uses certificates from that region), and attach it.
• Alternate domain name: your hostname.
• Origin domain: sites-origin.subcontext.com, protocol HTTPS only.
• Allowed HTTP methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE. The default (GET and HEAD only) breaks the quote form.
• Cache policy: Managed-CachingDisabled.
• Origin request policy: Managed-AllViewer (passes the Host header, cookies and query strings).
• DNS: CNAME your hostname to the distribution's d....cloudfront.net name.

Cloudflare#

• Add your hostname as a proxied (orange cloud) record.
• Rules, Origin Rules: send it to sites-origin.subcontext.com. The visitor's Host is kept by default.
• Caching, Cache Rules: set the hostname to Bypass cache.
• Certificate: Cloudflare issues one for your hostname (Universal SSL).
• If you use bot protection (Bot Fight Mode, challenges), let the verification check through (see Verifying).

Fastly#

• Add your hostname to the service and a TLS subscription for it.
• Hosts: add sites-origin.subcontext.com with TLS.
• Override host: leave blank, so the visitor's Host passes through.
• Cache settings: pass (TTL 0) for pages.
• DNS: point your hostname at the name Fastly gives you.

Your own reverse proxy#

Any proxy works if it does the same five things. With nginx:

server {
  listen 443 ssl;
  server_name quote.example.com;
  # Your certificate for quote.example.com (Let's Encrypt is fine)
  ssl_certificate     /etc/ssl/quote.example.com/fullchain.pem;
  ssl_certificate_key /etc/ssl/quote.example.com/privkey.pem;

  location / {
    proxy_pass https://sites-origin.subcontext.com;
    proxy_ssl_server_name on;
    proxy_ssl_name sites-origin.subcontext.com;
    proxy_set_header Host $host;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_cache off;
  }
}

Your DNS record#

Point your hostname at your CDN, not at Subcontext:

• A subdomain (quote.example.com, www.example.com): a CNAME to the name your CDN gave you.
• The bare domain (example.com): a domain's apex can't have a CNAME. Use your DNS provider's ALIAS or ANAME record, or CNAME flattening on Cloudflare, or the A and AAAA records your CDN gives you. Amazon Route 53 calls this an alias record.

www and the bare domain#

Pick one address for the site and send the other to it. The simplest is to add www.example.com as the domain in Subcontext, and have your CDN or DNS provider redirect example.com to it. If you'd rather serve both, add both in Subcontext and set each one up in the same way.

Verifying#

Press Verify now on the domain's page. Subcontext's servers then fetch

https://quote.example.com/__verify/<the domain's token>

through your hostname, and expect the token back. The exact address is on the domain's page. It passes when your DNS points at your CDN, your certificate is trusted, your CDN passes the Host header to Subcontext, and Subcontext answers with the token. The check runs in the background, so refresh after a moment.

• Verified: visitors to the hostname see the site. Subcontext re-checks verified domains once a day, so keep the verification address reachable for as long as you use the domain.
• Verified, checks failing: a recent check failed. Visitors still see the site, and Subcontext checks again every 30 minutes. If checks keep failing for 3 days, the domain becomes Failed. A check that passes clears it.
• Pending: not verified yet. The page shows what the last check found. Subcontext retries pending domains automatically every 30 minutes, so it goes live soon after you fix it, even if you don't press Verify again. After a week of failed checks it becomes Failed.
• Failed: visitors to the hostname don't see the site, and Subcontext has stopped checking it automatically. Fix the problem the page shows, then press Verify. The domain goes back to pending and the checks start again.

Owners and managers can be told when a domain starts failing its checks, stops working, or recovers, with the Domain status changes notification.

DNS changes can take from a few minutes to several hours to reach everyone, depending on the records' TTL.

What the last check means#

Removing a domain#

Remove on the domain's page takes it off the site straight away. Visitors to that hostname stop seeing the site, so change your DNS or CDN at the same time.