Adding a custom SSL certificate

All projects published to surge.sh subdomains automatically include free, basic SSL support. If you are using your own, custom domain, you can upgrade your project to Surge Plus to add your own custom SSL certificate.

This means your domain http://example.com will also be available at https://example.com.

Adding custom SSL

This guide will walk you through generating a PEM file, which you can use to add custom SSL to your project on Surge.

These steps will be the same whether you are getting a regular SSL certificate from an authority, making a self-signed certificate, or getting a Wildcard certificate for subdomains.

  1. Install OpenSSL
  2. Generate a private key and certificate
  3. Fill out the certificate details
  4. Get the certificate signed
  5. Create the PEM file
  6. Run surge ssl

Install OpenSSL

To generate a private key, you’ll need to have OpenSSL installed. To check if it is already on your system, run the following command:

openssl version

If it returns the version number—something like OpenSSL 1.0.2c 12 Jun 2015—you are ready to continue.

If you get command not found, you’ll need to install OpenSSL.

To install OpenSSL on Ubuntu, run:

sudo apt-get install openssl

OS X should already have OpenSSL installed. To update to the latest version, you can install OpenSSL using Homebrew. Run the following commands to install the most recent version of OpenSSL and use it, instead of OS X’s default version:

brew install openssl
brew link --force openssl

To confirm you have the version you want, open a new terminal window and run:

openssl version

Generate a private key and certificate

Use openssl to generate a private key and a certificate, both at once:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout surge.key -out surge.crt

After this, you’ll be asked for some information to include in the certificate.

Fill out the certificate details

Fill out the following details with your own information, as you’re prompted:

Answer the questions as you’re prompted to generate the certificate.

The data you’ll enter will look something like this:

Country Name:US
State or Province Name:New York
Locality Name:New York City
Organization Name:Your Company
Organizational Unit Name:Gif Department
Common Name:example.com
Email Address:you@example.com

Here are some more details for what to enter for each step:

Country

The two-letter ISO abbreviation for your country.

State or Province

The state or province where your organization is legally located. This cannot be abbreviated.

City or locality

The city where your organization is legally located.

Common name

The fully qualified domain name for your web server. This must be an exact match.

  • If you intend to secure the URL https://www.example.com, then your certificate’s common name must be: www.example.com
  • If you intend to secure the URL https://example.com, then your certificate’s common name must be: example.com
  • If you plan on getting a wildcard certificate, make sure to prefix your domain with an asterisk: *.example.com

Organization

The company name. This should not be abbriviated.

Organization Unit

Section of the organization. You may choose to leave this blank if it’s not applicable.

Get the certificate signed

Now that you have a certificate, you can submit it to a certificate authority that will verify it. Options for this include RapidSSL, Verisign, Thawte, among others.

If the signing authority asks you for a specific web server, choose: HAProxy + OpenSSL or Apache + OpenSSL.

Create the PEM file from the private key and cert

The only file you’ll want to upload to Surge is the PEM file. You can generate this by combining the surge.crt and surge.key files:

cat surge.crt surge.key > surge.pem
Join the `.crt` and `.key` file together, with any intermediate certificates your certificate authority gave you inbetween.

Run `surge ssl`

Now that you’ve generated the .pem file, safely story the .key file and .crt file somewhere else just in case you need them again. You may also want to note down the password for your .key file.

surge ssl
Upload your SSL using the `surge ssl` command.

You’ll be prompted for the path to your .pem file, and the custom domain you are adding it to. You may also pass these in immediately:

surge ssl --pem ./surge.pem --domain example.com

Cleaning up

If you’ve been working within your project directory, you’ll want to move your .key, .crt, and .pem files elsewhere so you don’t accidentally deploy them or add them to your version control.

That’s it, congrats! You now have your custom domain set up securely with custom SSL.

Some of this documentation is based upon RapidSSL’s original help article, Rackspace’s additions, and Digital Ocean’s documentation for uploading SSL certificates to HAProxy, which Surge uses.