Aliases and Custom Domains

This guide covers how to assign custom names to your now deployments
  • As custom subdomains under .now.sh (for example https://hello.now.sh)
  • As entirely custom domains (for example https://your-company.com)

Aliasing Basics

Whenever you deploy to now, the URL you get in return looks like something like:
https://get-started-basic-etjnigdrkz.now.sh
If we dissect that URL, we can see it's composed of a few parts:
  • https:// -Every single deployment is automatically served under HTTP/2 with SSL. Certificates are provisioned automatically.
  • get-started-basic - The application's name. You can customize it upon deployment (for example with the name field in package.json for Node.js deployments or LABEL in Dockerfile for Docker ones.
  • etjnigdrkz - A cryptographically-strong random string that makes your URL virtually impossible to guess, while retaining a reasonable length for sharing it with your co-workers or clients.
  • .now.sh - All your deployments end in .now.sh by default. Aliases allow you to point them to custom domains.
These URLs area ideal for development and staging, but not ideal to share with the public.
now aliases have two purposes:
  • Giving your deployment a friendly name that's more memorable.
  • Upgrading a certain deployment to production, by supplanting the previous alias with zero downtime.

Creating Aliases

Aliases are managed by invoking the command now alias, which has the following syntax:
now alias <SOURCE URL | ID> <TARGET SUBDOMAIN | DOMAIN>
For example, let's say I want https://get-started-basic-etjnigdrkz.now.sh
… to be accessible by the alias get-started-basic.now.sh. All I have to do is run:
now alias https://get-started-basic-etjnigdrkz.now.sh get-started-basic
> Success! Alias created (CIyk6IKL8MIHzAqrmcxbM8kf): https://get-started-basic.now.sh now points to https://get-started-basic-etjnigdrkz.now.sh (xpvB6GZWMR6Q9Oxe3c64Htgq) [copied to clipboard]
After this successful message, my deployment is instantly available via its original URL and the new alias I gave it:

The URL get-started-basic.now.sh now works!

Notice that I omitted .now.sh at the end of the target subdomain. When one is not given, we default to now.sh.
As seen in the output, each alias receives a unique identifier. In the example above, it's xpvB6GZWMR6Q9Oxe3c64Htgq. We'll cover this later in the Managing Aliases section.
The output also refers to the deployment ID, which is also accessible when you list your deployments with now ls. It can be used in substitution of the URL when running now alias:
now alias xpvB6GZWMR6Q9Oxe3c64Htgq get-started-basic
As a convenience, we parse the URLs you supply as parameters to now alias to extract the hostname, which means the following are all valid source URLs:
  • Just the hostname: get-started-basic-etjnigdrkz.now.sh
  • Including http(s): http://get-started-basic-etjnigdrkz.now.sh
  • Including /: https://get-started-basic-etjnigdrkz.now.sh/

Custom Domains

The same mechanism we explained above can be used to configure an external domain.
The command is almost exactly the same:
now alias https://get-started-basic-etjnigdrkz.now.sh zeithq.com
I already registered the domain zeithq.com, so I'll go ahead and run that command.
> zeithq.com is a custom domain.
> Verifying the DNS settings for zeithq.com (see https://zeit.world for help)
> Resolved IP: none
> Nameservers: ns-cloud-d1.googledomains.com, ns-cloud-d2.googledomains.com, ns-cloud-d3.googledomains.com, ns-cloud-d4.googledomains.com
> Error! Please make sure that your nameservers point to zeit.world.
> Examples: (full list at https://zeit.world)
> - california.zeit.world 173.255.215.107
> - newark.zeit.world 173.255.231.87
> - london.zeit.world 178.62.47.76
> - singapore.zeit.world 119.81.97.170
> Alternatively, ensure it resolves to alias.zeit.co via CNAME / ALIAS.
With now there's no manual configuration of DNS records and domain zones. The only requirement is that you point your domain's nameservers to any of our zeit.world hostnames.
In this case, my domain is registered with Google Domains, so I edit the nameservers there to look like this:

If you are using Google Domains, this is found under My domains > DNS

Upon re-running the command, we get:
> zeithq.com is a custom domain.
> Verifying the DNS settings for zeithq.com (see https://zeit.world for help)
> Detected https://zeit.world nameservers! Configuring records.
> DNS Configured! Verifying propagation…
> Verification OK!
> Provisioning certificate for zeithq.com
> Success! Alias created (04N40HL8XcvOe5cxcgNhomM0): https://zeithq.com now points to https://get-started-basic-etjnigdrkz.now.sh (VfsUPntrbhEzccjLU1zAI30Q) [copied to clipboard]

Using CNAME and ALIAS

If you want to use a domain that's configured with a third party DNS system, you can still use now alias.
To do so, just create a CNAME or ALIAS record that points to alias.zeit.co. For this example, I'll configure hello.zeit.run to point to the same deployment I used above, but using Google's nameservers. First, I head to the DNS settings and add a CNAME record for the hello subdomain as follows:

I added this record under DNS > Custom resource records

Next, I run now alias:
now alias get-started-basic-etjnigdrkz.now.sh hello.zeit.run
> hello.zeit.run is a custom domain.
> Verifying the DNS settings for hello.zeit.run (see https://zeit.world for help)
> Error! Verification required: Please add the following TXT record on the external DNS server: _now.zeit.run: ed24d6ddc87ee58332ac358ae
As you can see, as a security measure we require that you validate that you own this domain name. So I add an extra TXT record accordingly:

Important! Notice the subdomain is _now and the record type TXT!

> hello.zeit.run is a custom domain.
> Verifying the DNS settings for hello.zeit.run (see https://zeit.world for help)
> Verification OK!
> Provisioning certificate for hello.zeit.run
> Success! Alias created (BucgEPj9TI4Pae3HzDQT3LAB): https://hello.zeit.run now points to https://get-started-basic-etjnigdrkz.now.sh (VfsUPntybhEzccjLU1zAI30Q) [copied to clipboard]

Security Considerations

We ensure that your domains are fully protected and only you can add aliases to them.
When you add an alias to a certain domain name, we first verify its ownership. If it's not been claimed by anyone, we associate it with your account.
After I executed the alias above, I can run now domains ls to see my domains:
now domains ls
> 2 domains found [214ms] id dns url verified created zXBxQLQYidDddAb2l6db26Cb zeit.world https://zeithq.com true 11m ago WAZjIaxvaiieNUqJc22PJUKG external https://zeit.run true 20m ago
As you can see, there are two types of domains:
  • external: the domain is associated with a third-party nameserver provider like DNSimple.
  • zeit.world: the domain is hosted with zeit.world and now alias automatically sets up records.
Once a domain appears under now domains ls, it means that only you can point aliases to them. For external domains this requires verification. For zeit.world, make sure to add an alias to the domain or run now domain add as soon as possible.