While Scalingo provides a default public domain name for all applications, it’s generally a good idea to attach a custom domain name to an application, especially when in production.

Ideally, this custom domain name should allow users reach the application via a meaningful, easy-to-remember name (at least, compared to the default one provided by Scalingo).

By default, a maximum of 20 domain names can be attached to an application. Please get in touch with our Support team if you need more.

Buying a Domain Name

Domain names can be bought from registrars such as dnsimple, Gandi, or OVH Cloud. We do not sell domain names.

An exhaustive list of registrars can be found on the ICANN website.

The process is very similar from one registrar to the other: you have to first check the availability of the domain name you are interested in. If it is available, you can buy it for a limited amount of time, after which you will have to renew your subscription.

Setting Up the Domain Name

Once you own a domain name, the first step consists in making it point to your application. This step involves editing your domain name zone file. Steps may vary depending on your registrar, and differ depending on whether you want to setup a subdomain, an apex domain, or a wildcard domain.

Setting Up a Subdomain

The preferred way to make a subdomain point to your application consists in creating a CNAME record in your zone file. This CNAME record must point to the default domain name provided by Scalingo.

In the following example, the RR makes the www subdomain point to an application named my-app, hosted in the osc-fr1 region (notice the dot at the end of my-app.osc-fr1.scalingo.io.).

NAME   TTL      TYPE  FIELD    TARGET
www    10800    IN    CNAME    my-app.osc-fr1.scalingo.io.

Setting Up an Apex Domain

Apex domains are a bit specific, mostly because most registrars don’t support creating CNAME DNS records for them.

• If your registrar supports creating CNAME DNS records for apex domains, then you can follow the previous instructions to make it point to your application.
  Cloudflare is known to support CNAME record for apex domains.

  In such a case, the RR should look like this:

  NAME   TTL      TYPE  FIELD    TARGET
  @      10800    IN    CNAME    my-app.osc-fr1.scalingo.io.
  

• Some registrars support fields such as ALIAS or ANAME to provide the same functionality as CNAME records. If your registrar supports one of these, it’s the way to go. Follow the previous instructions, and make sure to replace CNAME by either ALIAS or ANAME.
  dnsimple, DNS Made Easy or PointDNS are known to support either ALIAS or ANAME records for apex domains.

  In such a case, the RR should look like this:

  NAME   TTL      TYPE  FIELD    TARGET
  @      10800    IN    ANAME    my-app.osc-fr1.scalingo.io.
  

• If your registrar doesn’t support any of these, you have 3 options left:

  1. Fallback on using a subdomain and a CNAME record for your application.
  2. Migrate to another registrar.

  3. Use A records:

     A DNS A record must point to an IPv4 address. At Scalingo, we don’t ensure that our ingress IP addresses won’t change over time.

     Creating A records pointing to our ingress IP addresses is de facto a risk, so we don’t recommend doing so.

     If you still want to go that path, create an A DNS record for each ingress IP address, depending on the region where your app is hosted.

Setting Up a Wildcard Domain

To setup a wildcard domain, please create a CNAME record in your zone file, as you’d do for a classic subdomain.

In the following example, the RR makes any subdomain of the [apex domain] point to an application named my-app, hosted in the osc-fr1 region:

NAME   TTL      TYPE  FIELD    TARGET
*      10800    IN    CNAME    my-app.osc-fr1.scalingo.io.

If you want Scalingo to manage the TLS certificate for the wildcard domain, make sure to follow these additional instructions.

Attaching the Domain Name

Once your domain name setup, it has to be added to the app hosted on Scalingo. This step is mandatory: it allows the platform to route requests targeting the domain name to the corresponding containers.

Using the Dashboard

1. From your web browser, open your dashboard
2. Click on the application for which you want to add a custom domain name
3. Click on the Settings tab
4. From the Setting sub-menu, select Public Routing
5. Locate the Custom Domains block
6. Click the Add a domain button
7. In the popup window, fill the Name input
8. Validate by clicking the Add button

Using the Command Line

1. Make sure you have correctly setup the Scalingo command line tool
2. Attach the domain name:

   scalingo --app my-app domains-add <domain name>
   

Using the Terraform Provider

1. Create a scalingo_domain resource block in your Terraform file:

   resource "scalingo_domain" my-domain {
     common_name = "www.example.com"
     app = "${scalingo_app.my-app.id}"
   }
   

   In this example, we attach the domain name www.example.com to the application.

Defining a Canonical Domain

If you have attached one or more custom domains to an application, you may want to redirect all requests to one of these, which becomes the canonical domain.

The redirection to the canonical domain is made using an HTTP 301 Moved Permanently redirection.

Using the Dashboard

1. From your web browser, open your dashboard
2. Click on the application for which you want to add a custom domain name
3. Click on the Settings tab
4. From the Setting sub-menu, select Public Routing
5. Locate the Custom Domains block
6. Locate the domain name you want to set as canonical
7. Click the star icon next to it to make it the canonical domain name
8. In the popup window that appears, click the Apply button

Using the Command Line

1. Make sure you have correctly setup the Scalingo command line tool
2. Set the domain name you want as canonical:

   scalingo --app my-app set-canonical-domain <domain_name>
   

Using the Terraform Provider

1. Make sure the canonical attribute of the corresponding scalingo_domain resource block is set to true:

   resource "scalingo_domain" "my-canonical-domain" {
     common_name = "www.example.com"
     app = "${scalingo_app.my-app.id}"
     canonical = true
   }
   

   In this example, we attach the domain name www.example.com to the application and set it as canonical.