Scalingo provides a subdomain which looks like osc-fr1.scalingo.io for all applications to access your application. Of course, you may want to use your own domain name. This operation requires different configuration operations:

Buy a Domain Name

We do not sell domain names. You can buy one from a company which sells them (called registrar) such as:

• DNS Simple - https://dnsimple.com/
• OVH - https://www.ovh.com
• Gandi - https://www.gandi.net

You can find an exhaustive list of registrars on the ICANN website. The process is pretty similar with any of these services. You search for the availability of the domain and if it is available, you can buy it per year.

Configure Your Application

Let’s say you bought the domain name example.com. You first need to configure your Scalingo application to accept requests to this domain. You can achieve this with our CLI, or through our dashboard.

Using Our CLI

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

Using the Web Dashboard

Go to the ‘Domains’ tab of your app dashboard, fill the ‘Domain Name’ text field and validate by clicking on ‘Link domain name to the app’.

Configure Your Domain Name

After having bought a domain name you need to configure it. Most of the registrars provide a web dashboard to do so. To target your application hosted on Scalingo, you need to create a CNAME field targeting the fully qualified domain name (FQDN). This FQDN depends on the region your application is deployed on:

• osc-fr1: my-app.osc-fr1.scalingo.io.
• osc-secnum-fr1: my-app.osc-secnum-fr1.scalingo.io.

Example

The raw configuration line to create an alias between www.example.com and my-app.osc-fr1.scalingo.io is:

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

After this configuration is completed, a Let’s Encrypt certificate is automatically generated for your application. If the propagation took time, it’s possible the next check to generate a certificate is scheduled in a couple of hours, (it’s following an exponential backoff algorithm to retry the generation). In this case, you might want to accelerate the process: you can detach and re-attach the domain to the application, our system will then try to generate a certificate immediately.

Root Domain

Most of the registrars only allow A field for root domains. However A should target an IP. As Scalingo don’t ensure that our front IP addresses won’t change over time, we advise you to use a subdomain for your application or to migrate your domain name to another DNS provider.

Some providers allow to create ALIAS, ANAME or CNAME field for root domains:

• DNSimple (ALIAS)
• DNS Made Easy (ANAME)
• easyDNS (ANAME)
• Cloudflare (CNAME)
• PointDNS (ALIAS)

If you want to keep your registrar which is not compatible with root domain aliases, you can create A fields targeting our web entrypoints. These IP depend on the region your application is deployed on:

• osc-fr1: 4 A fields
  • 5.104.101.30
  • 109.232.236.90
  • 109.232.233.130
  • 148.253.75.120
• osc-secnum-fr1: 4 A fields
  • 148.253.96.193
  • 185.21.194.105
  • 80.247.12.255
  • 80.247.13.145

Wildcard Domain

App Configuration

You may want to redirect all subdomains of your domain to a specific Scalingo application. To achieve this you’ve to add a domain name with the form:

• *.example.com
• *.subdomain.example.com

And also add a CNAME field targeting your application FQDN, just like with any regular domain name.

Then all requests targeting for instance www.example.com or admin.example.com will be redirected to this specific application.

Once you have added your wildcard domain, we automatically generate a Let’s Encrypt certificate. But to complete the generation, you need to create a TXT record in your zone. This allows Let’s Encrypt certificate to know that you are the owner of the wildcard domain. This is highlighted by the “Action Required” status on the web dashboard. Clicking on the question mark gives you the instruction to update your TXT record.

Here is an example of the DNS configuration for the domain *.example.com:

NAME                         TTL   TYPE    VALUE
_acme-challenge.example.com  120   TXT     5TWm4V7xoUpGax-58FrPO49

This TXT record must be updated every three months to renew the certificate. In case you fear to forget to do this modification, we support automatic update of this value for some DNS providers (see the list below). All you have to do is to give us some credentials for the DNS providers APIs. You can do this by setting up some environment variables (see the Environment variables section).

Azure DNS

If your domain is managed by Azure DNS, you can add the following variables:

DNS_PROVIDER=azure
DNS_AZURE_CLIENT_ID=<your_azure_client_id>
DNS_AZURE_CLIENT_SECRET=<your_azure_client_secret>
DNS_AZURE_SUBSCRIPTION_ID=<your_azure_subscription_id>
DNS_AZURE_TENANT_ID=<your_azure_tenant_id>
DNS_AZURE_RESOURCE_GROUP=<your_azure_resource_group>

To obtain your keys, first login on the Azure Portal. Then follow these steps:

• Create an Application: go on Azure Active Directory > App Registrations > New application registration. Fill the form (the Sign-on URL is completely arbitrary).
• Get your Client ID: After created your app, stay on the page. Copy the Application ID. This is your Client ID.
• Get your Client Secret: On the same page, go on Settings > Keys. Enter a description and a duration, then Save. Make sure to copy the key before leaving the page, you won’t be able to retrieve after you leave. This is your Client Secret
• Get your Subscription ID: Go on Subscriptions. Copy your Subscription ID.
• Get your Tenant ID: Go on Azure Active Directory > Properties. Copy the Directory ID. This is your Tenant ID.
• Get your Resource Group: Go on DNS Zone > Select your zone > Overview > Copy the Resource Group.

Now you have to create a Role for your application. Go on Subscriptions > Select your subscription > Access Control (IAM) > Add > Select DNS Zone Contributor and assign it to your application. Just type the name of your application and select it. Save.

That’s all! You can use the Azure DNS with Scalingo.

For more information about Azure DNS, see their documentation.

Cloudflare

If your domain is managed by Cloudflare, you can add the following variables:

DNS_PROVIDER=cloudflare
DNS_CLOUDFLARE_EMAIL=<your_cloudflare_email>
DNS_CLOUDFLARE_API_KEY=<your_cloudflare_global_api_key>

You can get your API key on https://dash.cloudflare.com/profile/api-tokens, section API Keys, then Global API Key.

For more information about Cloudflare, see their documentation.

DNSimple

If your domain is managed by DNSimple, you can add the following variables:

DNS_PROVIDER=dnsimple
DNS_DNSIMPLE_OAUTH_TOKEN=<your_dnsimple_oauth_token>

For more information about DNSimple, see their documentation.

Gandi

If your domain is managed by Gandi, you can add the following variables:

DNS_PROVIDER=gandi
DNS_GANDI_API_KEY=<your_gandi_api_key>

You can get your API key by going to https://www.gandi.net/admin/apixml/.

For more information about Gandi, see their documentation.

Gandiv5

If your domain is managed by Gandiv5, you can add the following variables:

DNS_PROVIDER=gandiv5
DNS_GANDIV5_API_KEY=<your_gandiv5_api_key>

You can get your API key by going to https://account.gandi.net, Security section, then Generate the API Key.

For more information about Gandiv5, see their documentation.

Google Cloud DNS

If your domain is managed by Google Cloud DNS, you can add the following variables:

DNS_PROVIDER=gcloud
DNS_GCLOUD_JSON_KEYS=<your_base64_encoded_service_account_file>

You can get your Service Account file by going to https://console.cloud.google.com/. Select your project, and then on the left menu go on APIs & Services > Credentials. Then click on Create Credentials and select Service account key. Then export keys in JSON. Once you have your JSON file, you must convert it to base64 format. You can do it with the following command :

 base64 --wrap=0 service_account_file.json

For more information about Google Cloud DNS, see their document

GoDaddy

If your domain is managed by GoDaddy, you can add the following variables:

DNS_PROVIDER=godaddy
DNS_GODADDY_API_KEY=<your_godaddy_api_key>
DNS_GODADDY_API_SECRET=<your_godaddy_api_secret>

You can get your API keys by going to https://developer.godaddy.com/keys.

For more information about GoDaddy, see their documentation.

OVH

If your domain is managed by OVH, you can add the following variables:

DNS_PROVIDER=ovh
DNS_OVH_ENDPOINT=<ovh_endpoint>
DNS_OVH_APPLICATION_KEY=<your_ovh_application_key>
DNS_OVH_APPLICATION_SECRET=<your_ovh_application_secret>
DNS_OVH_CONSUMER_KEY=<your_ovh_consumer_key>

The endpoint must be ovh-eu or ovh-ca. You can get your API keys by going on https://eu.api.ovh.com/createToken/ (for Europe) or https://ca.api.ovh.com/createToken/ (for Canada). Make sure the keys are valid for more than one day. The rights must be at least GET, POST and DELETE for /domain/zone/*.

For more information about OVH, see their documentation.

AWS Route53

If your domain is managed by Route53, you can add the following variables:

DNS_PROVIDER=route53
DNS_AWS_ACCESS_KEY_ID=<your_aws_access_key_id>
DNS_AWS_SECRET_ACCESS_KEY=<your_aws_secret_access_key>
DNS_AWS_HOSTED_ZONE_ID=<your_aws_hosted_id>

For more information about Route53, see their documentation.

Others providers will be add to the platform. If your provider is not in the list, you have to create the TXT record manually.

After this configuration is completed, a Let’s Encrypt certificate is automatically generated for your application.

Renewal wildcard domain

In order to renew a wildcard domain, you will need to create a new TXT record for your zone, to prove that you are the owner of the domain.

If you use the supported providers, everything is setup automagically. But if your DNS provider is not supported by our platform, you will receive an email to remember you that you have to create a new TXT record to renew your Let’s Encrypt certificate

Priorities

If an application has the wildcard domain *.example.com configured and that another application is using admin.example.com, the wildcard will not override the admin subdomain. Actually, any complete subdomain will have priority over the wildcard.

DNS Configuration

If you need to redirect all the subdomains to Scalingo servers, you need to setup your DNS accordingly, it’s really close to configuring a single domain name:

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

Note

When you add an alias, we don’t do any prior verification. If you cannot add your alias because it’s already taken on Scalingo and you think you’re legit to use it, send an email to support@scalingo.com describing the problem.

Security

The wildcard you add to your domain name is protected by a mechanism that ensures it can only be used by you. For instance, if you add a wildcard such as *.y.z and register an application called A with the subdomain x.y.z using your user account (my-user), no other user (e.g. evil-user) can register any other subdomain such as evil.y.z for their application B. The mechanism checks whether the owner of the application for the subdomain evil.y.z is the same as for any other subdomain registered with the wildcard. In this case, my-user for application A is different from evil-user for application B.

Canonical Domain

After defining multiple domains on an application, one can need to redirect all requests towards its application to a specific domain. This domain is called the canonical domain. The canonical domain can be defined in the Settings tab of the dashboard.

Note that when a wildcard domain is defined for an application, a second domain must be added to be set as canonical. For instance, let’s say that *.example.com is in the list of domains of an app. If www.example.com is the wanted canonical domain, it must be added to the list of domains to be selectable as a canonical domain.

The redirection to the canonical domain will be made with a HTTP 301 status code.