Add a domain

On Runway, each application gets a domain with SSL/TLS.

When you create an application, we automatically assign app-name.pqapp.dev and you have your own URL! For example, if your application’s name is incredible-runway, then your the application’s URL will be https://incredible-runway.pqapp.dev.

Follow along to learn how to assign a custom domain to your application and what it entails.

Add a domain

You can see your application’s domain names on the Runway CLI or on the Runway UI:

$ runway app domain ls
INFO    showing domains for app "incredible-runway"
 Domain       incredible-runway.pqapp.dev
 Root Domain  (none needed)
 Status       active (standard app domain)
All app domains need one of the following DNS records:
either your-domain IN CNAME paas-prod-ip.runway.horse.
or your-domain IN A 5.57.43.177

Proceed by adding your custom domain name - e.g. runway.berlin:

$ runway app domain add runway.berlin
INFO    adding domain for app "incredible-runway"    
         All app domains need one of the following DNS records:          
  ╭──╮   either runway.berlin IN CNAME paas-prod-ip.runway.horse.
 ◜│  │◝  or runway.berlin IN A 5.57.43.177
  ◕  ◕
  │  │╭  Is that set up for runway.berlin?
  │◟_◞│
  ╰───╯
app domain addition: done
 Domain       runway.berlin
 Root Domain  (none)
 Status       INACTIVE (no root domain configured) 
 -----------  -------------------

To start using this domain, please add a root domain and verify it:

* runway domain add runway.berlin
* (do the DNS setup as given by the previous command)
* runway domain verify runway.berlin

DNS records

After you assigned the domain name, add one of the suggested records on your DNS interface (only one of them is required):

• runway.berlin. IN CNAME paas-prod-ip.runway.horse.
• runway.berlin. IN ALIAS paas-prod-ip.runway.horse.
• runway.berlin. IN ANAME paas-prod-ip.runway.horse.
• runway.berlin. IN A 5.57.43.177

Domain names can be a bit weird in how they work, e.g. for runway.berlin you need to use an ALIAS, ANAME or A DNS record because they are the root of the domain.

If you setup a sub-domain (e.g. www.runway.berlin) then a CNAME works as well. The CNAME has the advantage that if we change the IP address, you don’t have to do anything.

ALIAS and ANAME are new DNS record types. They are specifically designed for root domains, consult with your DNS provider if they support those.

Verify ownership

Domain verification is a one-time process and once you confirmed the ownership of a domain name and the DNS records are created, then any sub domain name will automatically be assignable on Runway.

For example, confirm runway.berlin, and then add www.runway.berlin, hello-world.runway.berlin and so on to applications.

Proceed to verify the domain name on Runway:

$ runway domain add runway.berlin
domain runway.berlin: done
 Domain      runway.berlin
 Status      UNVERIFIED
 Message
 Last Check  (none yet)
 TXT Record  runway=random-hash-123-abcdefg
 ----------  -------------------                                                     
To start using this domain, you need to verify your ownership of it:
* add this as a TXT record:
  runway=random-hash-123-abcdefg
* wait for the record to propagate in DNS (depending on the TTL)
* run runway domain verify runway.berlin

As a next step, head to your provider’s DNS settings to create a new record of type TXT to verify you can manage this domain. After you created this record, you can verify that we confirmed your ownership by running runway domain ls.

As an example, the record may look like this (using a TTL of 86400 seconds or 24 hours):

runway.berlin.		86400	IN	TXT	"runway=random-hash-123-abcdefg"

In general, domain verification can take a while (usually up to 24 hours) due to how DNS works.

You can influence this by setting a shorter TTL (time to live) on the record when you create it. To kick-off the verification process on Runway, you can always run:

runway domain verify runway.berlin

Once the domain is verified, your application will be available on the domain name and SSL/TLS will be automatically provisioned for you. Rest assured, you can always get in touch with us if you need help.

Next steps

Please don’t remove the TXT record, as Runway will periodically verify that you (still) own the domain name.

Once the domain is verified, the (sub-)domain on the app will start to work.

Redirects

You may want to add a redirect in your code now (or e.g. through a web server configuration) to ensure the canonical name of your website is always used:

http {
# snip ...
  server {
    listen {{port}};
    server_name incredible-runway.pqapp.dev;
    return 301 https://runway.berlin$request_uri;
  }

  server {
    listen {{port}} default_server;
    server_name _;

    # snip ...
  }
}

<If "%{HTTP_HOST} == 'incredible-runway.pqapp.dev'">
    Redirect "/" "https://runway.berlin"
</If>

www (or sub-domains)

Each DNS record is unique — while runway.berlin and www.runway.berlin may look the same, the first is a root domain and the second is a sub-domain.

If you setup a root domain on your application (e.g. runway.berlin), then you want to also setup a CNAME for www.runway.berlin and assign it with:

runway app domain add www.runway.berlin

Since you already confirmed ownership, no extra steps are required.

Wildcard

If you plan to use a lot of sub-domains on Runway, you can use a wildcard CNAME to direct all sub-domains to Runway:

*.runway.berlin.		86400	IN	CNAME	paas-prod-ip.runway.horse.