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.
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.
- Install OpenSSL
- Generate a private key and certificate
- Fill out the certificate details
- Get the certificate signed
- Create the PEM file
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:
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:
Generate a private key and certificate
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:
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:email@example.com
Here are some more details for what to enter for each step:
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.
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:
- If you intend to secure the URL https://example.com, then your certificate’s common name must be:
- If you plan on getting a wildcard certificate, make sure to prefix your domain with an asterisk:
The company name. This should not be abbriviated.
Section of the organization. You may choose to leave this blank if it’s not applicable.
Get the certificate signed
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
cat surge.crt surge.key > surge.pem
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
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
If you’ve been working within your project directory, you’ll want to move your
.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.