Skip to content
Hyperion

Preview a website before its DNS moves

A preview address is a second name for a site, built from a template, on a wildcard certificate the node holds. It works before the site’s own DNS points at the server, for example during a migration. The address also serves as the domain of test websites.

Before you start

Section titled “Before you start”
  • You are an Owner. An Administrator can open the page and sees the forms disabled.
  • You can create DNS records for a parent domain you own, for example preview.example.com.
  • A real Let’s Encrypt contact is set under Settings, HTTPS & previews. See Issue an HTTPS certificate.

Steps

Section titled “Steps”

  1. Open Settings in the sidebar, then HTTPS & previews, and find Preview address. The pill reads off, on or no usable base.

  2. In Template, enter the pattern and click Save:

    • {name} is the site’s first label.
    • {node} is the node’s hostname.
    • {node_id} is the node’s long ID.

    With {name}.{node}.preview.example.com, the site blog.com on node lab-01 is previewed at blog.lab-01.preview.example.com. Keep at least two labels after {name}, because the certificate needs a parent domain to cover. With more than one node, keep {node}, because a wildcard DNS record points at one server only. An empty template turns previews off.

  3. For each node, create a wildcard DNS record at your provider: *.lab-01.preview.example.com pointing at that node’s IP address.

  4. Under Preview certificates, each node has a row with its Wildcard, DNS and Status. Click Issue on that node’s row. The page Preview wildcard certificate — DNS-01 then lists the records. It uses TXT records as described in Issue a wildcard certificate, or one CNAME if you set up the delegated zone there.

Every site on the node, production included, now also answers on its preview address, without a Let’s Encrypt request per site.

Check that it worked

Section titled “Check that it worked”

Open a site’s Overview tab. A Preview site button appears and opens the preview address with a trusted certificate.

Terminal window
curl -sI https://blog.lab-01.preview.example.com/ | head -n 1

Expected: a status line from the site, with no certificate error.

If it fails

Section titled “If it fails”
  • The pill reads no usable base: the template leaves no parent domain. Put at least two labels after {name}.
  • “Several nodes share” a base: only one of them can serve its previews. Add {node} to the template.
  • No Preview site button: the node’s preview certificate is not issued yet, so check its row under Preview certificates. A site whose domain is already under the preview base, such as a test website, needs no second address and has no button.