Tutorials

Put a Resource on a custom domain

View as Markdown

This tutorial maps a custom domain onto a deployed Resource. You will add the domain from the CLI, create one TXT and one CNAME record at your DNS provider, watch the three-stage tracker move from DNS to Certificate to Live, and confirm the endpoint serves over HTTPS. It takes about ten minutes of work plus DNS propagation time.

Custom domains are CNAME-only: you point a hostname at Hyjal, never at a raw IP address. Certificates are issued and renewed automatically. See Custom domains for the reference.

Prerequisites

  • A deployed Resource. This tutorial uses acme with a web Resource served at https://web--acme.hyjal.cloud.
  • Access to your domain’s DNS records. This tutorial uses www.acme.com.
  • The hyjal CLI installed and logged in.

1. Add the domain

Attach the domain to the Resource with hyjal domains add. The CLI returns the two DNS records you need to create.

$$ hyjal domains add www.acme.com --resource web
$Added www.acme.com to acme/web.
$
$Create these DNS records to verify and route:
$
$  TXT    _hyjal-challenge.www.acme.com    hyjal-verify=Q7x2k9a…f1
$  CNAME  www.acme.com                     web--acme.hyjal.cloud
$
$Then run: hyjal domains verify www.acme.com

The TXT record proves you control the domain. The CNAME routes traffic to the Resource’s endpoint.

2. Create the DNS records

At your DNS provider, create both records exactly as shown.

TypeNameValue
TXT_hyjal-challenge.www.acme.comhyjal-verify=Q7x2k9a…f1
CNAMEwww.acme.comweb--acme.hyjal.cloud

The CNAME target is the Resource’s default endpoint hostname. Do not create an A record; custom domains route by CNAME only.

3. Verify and follow the tracker

Trigger verification. The Console shows a three-stage tracker for the domain: DNS, then Certificate, then Live. The CLI prints the same stages as they advance.

$$ hyjal domains verify www.acme.com
$www.acme.com
$  DNS ........... ✓ TXT and CNAME observed
$  Certificate ... ✓ issued (sha256:c4a1…)
$  Live .......... ✓ serving
$
$Domain is live: https://www.acme.com

The stages advance in order:

  • DNS: the TXT challenge and CNAME are observed at the resolver.
  • Certificate: a certificate is issued automatically, typically within seconds of DNS propagating.
  • Live: the endpoint serves your Resource over HTTPS on the custom domain.

If DNS has not propagated yet, the tracker holds at the DNS stage. Wait for propagation and run hyjal domains verify again, or watch the tracker flip on its own in the Console. A domain still pending verification reports HYJ-DNS001.

4. Confirm HTTPS

Request the domain and confirm a 200 over TLS.

$$ curl -sSI https://www.acme.com | head -n 1
$HTTP/2 200

List your domains to confirm the mapping and its status.

$$ hyjal domains list
$DOMAIN          RESOURCE    STATUS
$www.acme.com    web         live

What you built

  • A custom domain mapped to a Resource with one TXT and one CNAME record.
  • An automatically issued, auto-renewing certificate.
  • A live HTTPS endpoint on your own hostname, tracked from DNS to Live.

Next steps