Using Custom Domains & Routes

Last Updated October 2014

While myapp.gopagoda.io is a handy domain for accessing your app when in development, it’s probably not the domain you want your users to visit. No worries. Pagoda Box makes it easy to use custom domains and even define custom routes. After reading this doc, you should be familiar with:

  • Create a DNS alias using your custom domain
  • Pointing your custom domain to your app on Pagoda Box
  • Configuring custom routes to point to specific web services

Creating a DNS Alias

When you’re ready to direct traffic to your real domain (myapp.com) instead of your Pagoda Box domain (myapp.gopagoda.io), you need to do two things:

  1. Create a DNS alias using your custom domain.

  2. Add an A-Record on your domain registrar's zone file pointing to one or more of the available inbound IPs.

Add a New Alias

To create a DNS Alias, go to the Network tab in your App Dashboard and click on the "Add New Alias" button. Enter your custom domain purchased from a DNS provider. It’s important that the alias perfectly matches your purchased domain name.

Implicit Naming & Subdomains

Pagoda Box uses implicit DNS routing. This means that if you want to use subdomains with your app, you simply need to add the root level domain (myapp.com) as a DNS alias. Requests to any subdomain of myapp.com will automatically be routed to your app unless that subdomain is explicitly pointed somewhere else.

Don't use an asterisk in place of a subdomain when adding a DNS Alias (*.myapp.com). Just use the root level domain (myapp.com).

You will still need to create a DNS A-record for each subdomain pointing to one of the available inbound IPs.

Now select which service to which your DNS Alias will point. This really comes in handy if you like to point a subdomain or a specific route to a particular web service.

Verify Domain Ownership

Whenever you add a new DNS alias, you must verify that your own/manage the root domain. This is done by creating a TXT record in your DNS Zone file that includes a key provided in your dashboard. Management of any files associated with your DNS is done through your DNS provider.

Once you've added the TXT record to your domain, click the "Verify Now" button. We will ping the domain and look for the TXT recored with the correct verification key. Note that if you're updating an existing TXT record, the propagation of the change is subject to your domains TTL, so we may not be able to verify ownership immediately.

Point Your Domain to an Inbound IP

Once you're DNS alias is added and you've verified domain ownership, you're ready to direct traffic to your app. Simply point your domain to either one of the Pagoda Box public IPs or a dedicated IP that you've added to your app. This is done by modifying your domain's A-record to point to one of the available IPs.

Multiple Domains

If you have multiple domains that you'd like directed to your app, just create an alias for each. An app can have as many DNS aliases as you need.

Custom Routes

Along with using custom domains, Pagoda Box also allows you to define custom routes that point to specific services within your application. For instance, you could have yourdomain.com point to web1 while yourdomain.com/blog points to web2.

This really comes in handy if you want or need a specific section or directory of your app to be independently scalable from the rest of your app.

Use Case

A perfect use case is Magento. Magento's admin panel is notoriously resource intensive. When running the admin panel on the same service/instance as the public facing site, actions in the admin will often affect the page response times. What custom routes allow you to do is point all of your public web requests (yourmagentostore.com) to one web service, while all requests to your admin panel (yourmagentostore.com/admin) go to a completely separate web service. The resource-heavy requests in the admin will only affect the admin. Not your front-facing site. All this with no change to your codebase.

Custom Routes Honor Your App's Directory Structure

Something important to know is that any custom routes still honor your app's directory structure relative to your document root.

For example: say you have a PHP web service and a custom route of domain.com/blog with your httpd_document_root set to your "public" directory. In order to correcly load the blog, the blog code would be inside of public/blog/ in your app's repo.

Editing Your Domain's Zone File

Change Your A-Record

In order for your Custom Domain to be able to point to your app on Pagoda Box, you'll need to edit your domain’s zone file. This is done by adding a A-Record to your zone file that points to one of the available IPs.

Using a Dedicated IP and Adding SSL

If you need SSL on your domain, don't point your A-Record to Pagoda Box quite yet. You first need to add a dedicated IP and an SSL certificate. Then bind your dedicated IP to your SSL certificate The dedicated IP you will point your A-Record to. The Adding SSL documentation explains the process in more detail.

Every domain registrar handles zone file management in a slightly different way. If you have questions about editing your zone file or adding an A-Record, contact your domain registrar.

Once your A-Record has been directed to an IP on Pagoda Box and the DNS change has propagated, your custom domain will be fully functional.

DNS Propagation

Once you have added this A-Record to your domain, it can take up to 48 hours to propagate across the web’s nameservers. We recommend turning your DNS Time to Live (TTL) down as low as it will go 48-72 hours before modifying your A-Record. This will minimize downtime caused by DNS propagation.

Verify Traffic is Actually Routing to Your App

The final step in adding a DNS alias is verifying that traffic is actually routing to your app on Pagoda Box. This can be done only after you've modified your domains A-record and the change has propagated. To check, click the "Test Now" button in your dashboard.

If we detect that requests to your domain is pointed to a Pagoda Box IP, the domain status will be set to active and your DNS alias will be fully configured.

A-Record Verification Will Not Work with DNS Proxies

A-record verfication checks to see if your domain is pointing to a Pagoda Box IP. Domains pointed to a non-Pagoda-Box IP then proxied to Pagoda Box will always fail the A-record verification. This doesn't mean traffic isn't hitting your app. It just means your domain isn't pointed to a Pagoda Box IP.

Users using CDNs like Cloudflare will see this behavior.

If you have any questions, suggestions, or corrections, let us know.