While Scalingo can automatically handle all the burden of generating and renewing the certificates linked to a domain name, you may not want to rely on these features, and instead provide your own certificate using another CA.

Setting Up a Custom Certificate

1. Generating a custom certificate
2. Importing the custom certificate chain

Generating a Certificate Signing Request

1. Generate a key pair, and the corresponding Certificate Signing Request (CSR):

   openssl req -new -newkey rsa:2048 -sha256 -nodes -keyout my-app.key -out my-app.csr
   

   The above command creates a 2048 bytes long key using the RSA algorithm. Chosing the algorithm and the key length is your responsibility.

   The tool asks for different information related to your certificate. Particular attention should be given to these ones:

   • Country Name: ISO 3166-1 two letters code for your country
   • Common Name: domain name you want to secure

The command creates two files:

• my-app.key: the private key, which must be kept secret
• my-app.csr: the CSR, which has to be signed by a CA

Signing the Certificate Signing Request

1. Submit your CSR to your CA to generate a valid certificate.
   This service is often charged by the CA!

2. Make sure your key and certificate files are in PEM format.

Creating the Certificate Chain

Most CA provide certificate chains or bundles alongside your signed certificate (most common is the Certification Authority, but they may supply intermediary certificates too).

1. Before uploading the custom certificate to Scalingo, you have to first create a single file containing all the certificates of the chain, including your custom certificate. This file must be in PEM format, and must look like this:

   -----BEGIN CERTIFICATE-----
   .... your certificate
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   .... intermediate certificate 1
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   .... intermediate certificate 2
   -----END CERTIFICATE-----
   

Importing the Custom Certificate

Once you have the certificate chain ready, upload it to Scalingo.

Using the Dashboard

1. From your web browser, open your dashboard
2. Click on the application for which you want to add a custom TLS certificate
3. Click on the Settings tab
4. From the Settings sub-menu, select Public Routing
5. Locate the Custom domains block
6. Locate the domain name for which you want to set the certificate
7. Click the corresponding pen icon
8. Select the certificate chain and key you want to use
9. Click the Upload button

Using the Command Line

• If the domain name is already attached to your app:

  scalingo --app my-app domains-ssl --cert my-app.crt --key my-app.key www.example.com
  

• If the domain name is not yet attached to your app:

  scalingo --app my-app domains-add --cert my-app.crt --key my-app.key www.example.com
  

In both cases, the modification is instantly applied.

Converting to PEM

Your certificate may have been supplied in a binary format by your CA: if you have a .cer, a .crt or a .der file, it should be binary. But those extensions are sometimes used for PEM files too.

You can check the file format by opening it with a text editor: if you see BEGIN CERTIFICATE, then it’s textual. If this is a binary file, your editor should tell you so.

In the latter case, you can convert it to text using openssl. The following command should help you achieve this task:

openssl x509 -inform DER -in my-certificate.crt -out my-certificate.pem

Forgetting to Renew a Certificate

If you forget to renew a custom certificate on time, or if you remove it from your domain name, and unless you have completely opted out of Let’s Encrypt features, Scalingo automatically and immediately generates a Let’s Encrypt certificate so your app remains reachable via HTTPS.