Installing and Updating SSL Certificates with Emergence


#1

1. Generate SSL Certificate

If you do not already have a ssl certificate, you’ll need to purchase. To do so you’ll need to generate a certificate signing request (csr) using openssl. The following video has a tutorial on how to do so.

https://knowledge.geotrust.com/support/knowledge-base/index?page=content&id=AR876

IMPORTANT: Do not use a passphrase when generating your private key

2. Add SSL Certificates to Server

Once you have the three ssl necessary files move them to:

/emergence/sites/SITENAME/ssl/
  • “www.example.com.crt”
  • “www.example.com.key”
  • “www.example.com.csr”

Ensure the permissions of these certs match the following:

-rw-r----- 1 root www-data 1679 Jul 20 20:34 www.example.com.crt
-rw-r----- 1 root www-data 1679 Jul 20 20:34 www.example.com.key
-rw-r----- 1 root www-data 1679 Jul 20 20:34 www.example.com.csr

3. Update config.json (optional)

NOTE: This step is only necessary if you’re operating a single site instance, ie mywebsite.com is the only public facing site in the kernel (excluding non public sites like staging sites). If there are multiple sites on the server skip to step 3.

The path to these certs needs to be added to config.json.

/emergence/config.json

{
     "user": "www-data",
     "group": "www-data",
     "server": {
         "host": "0.0.0.0",
         "sslKey": "/emergence/sites/SITENAME/ssl/www.example.com.key",
         "sslCert": "/emergence/sites/SITENAME/ssl/www.example.com.crt",
     }
     ...
}

4. Update site.json

Similar to config.json, you’ll need to add the ssl key and cert to site.json as well. Edit the following file to include the “ssl” parameter.

/emergence/sites/SITENAME/site.json

{
    "handle": "SITENAME",
    ...
    "ssl": {
         "certificate": "/emergence/sites/SITENAME/ssl/www.example.com.crt",
         "certificate_key": "/emergence/sites/SITENAME/ssl/www.example.com.key"
     }
 }

5. Append Intermediate Chain to .crt File

Next, you need to append the global chain to your .crt file. To do this:

  1. Find chain file for your providers
  1. Upload to server
  • Put file in ssl directory /emergence/sites/SITENAME/ssl/GeoTrust_Intermediate.txt
  1. Append file to .crt using the following command:

cat GeoTrust_Intermediate.txt >> www.example.com.crt

6. Restart Emergence and nginx

To restart emergence, ssl into the server and run:

restart emergence-kernel

To restart nginx, navigate to example.com:9083 (emergence hub) and stop then start “Web”

7. Verify Certificates are Installed

Hit your url and verify that your browser isn’t giving a warning and the lock is complete. Next, click the lock to get more information about the cert and verify it’s accurate. (The method of viewing this information may vary by browser)

8. Force SSL for Entire Site (optional)

If you’d like to force every page on your site to use https, add the follow snippet to your Site.config.php file

/php-config/Site.config.php or /php-config/Site.config.d/https.php

Site::$onInitialized = function() {
    if (!empty($_SERVER['HTTP_HOST']) && ($_SERVER['HTTP_HOST'] != 'example.com' || empty($_SERVER['HTTPS']))) {
        Site::redirectPermanent('https://example.com' . $_SERVER['REQUEST_URI']);
    }
};

Troubleshooting

  1. If you run into problems restarting your ngnix (Web) do a full reboot using this tutorial: Recovering from service- and host-level failures

  2. If the emergence-kernel and nginx look fine but your sites still aren’t loading, check these two places for possible errors:

    /var/log/upstart/emergence-kernel.log
    /emergence/log/nginx


Creating and using a free SSL certificate with Let's Encrypt
#2

Also, as of this commit, the kernel supports a more advanced syntax for site-level SSL that let’s you utilize SNI to map different hostnames to specific certificates:

{
    "handle": "SITENAME",
    ...
    "ssl": {
        "hostnames": {
            "api.example.com": {
                "certificate": "/emergence/sites/SITENAME/ssl/api.example.com.crt",
                "certificate_key": "/emergence/sites/SITENAME/ssl/api.example.com.key"
            },
            "example.com": {
                "certificate": "/emergence/sites/SITENAME/ssl/example.com.crt",
                "certificate_key": "/emergence/sites/SITENAME/ssl/example.com.key"
            },
            "admin.example.com": {
                "certificate": "/emergence/sites/SITENAME/ssl/admin.example.com.crt",
                "certificate_key": "/emergence/sites/SITENAME/ssl/admin.example.com.key"
            }
        }
    }
}

#4

@tyler I updated the top post to “wiki” mode, apply the correction there