Emergence Documentation

Securing a site with SSL

Generate a CSR

Use the openssl tool from your terminal to generate a private key If you’re using Mac OS X or Linux this tool should already be installed.

user@hostname ~ $ cd /emergence/sites/example-live
user@hostname ~ $ sudo mkdir ssl
user@hostname ~ $ cd ssl
user@hostname ~ $ sudo openssl genrsa -out www.example.org.key 2048

Then, use the private key to generate a CSR (certificate signing request). You will be prompted to fill out several fields identifying the organization that owns the certificate, example responses are provided below. It is best to leave the email address field blank, and to use the www.* form of your hostname if you intend for the site to behave the same with or without it. If prompted for a challenge password, leave it blank.

user@hostname ~ $ sudo openssl req -new -key www.example.org.key -out www.example.org.csr 
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:Pennsylvania
Locality Name (eg, city) []:Philadelphia
Organization Name (eg, company) [Internet Widgits Pty Ltd]:MyOrganization LLC
Organizational Unit Name (eg, section) []:DevOps
Common Name (e.g. server FQDN or YOUR name) []:www.example.org
Email Address []:

Submit the CSR to a certificate authority

Submit the contents of your .csr file to a trusted certificate authority for signing. You can use the following command to read the contents of the file through your SSH terminal:

user@hostname ~ $ sudo cat www.example.org.csr 

Install certificate

Eventually you will receive a signed certificate from your signing vendor. If your vendor provides you with an intermediate certificate, you should append it to the end of the same file as your certificate before writing to the server.

user@hostname ~ $ sudo vim www.example.org.crt 

Then, edit the site’s site.config file and append a new key "ssl" to the top-level object:

{
    ...,
    "ssl": {
        "certificate": "/emergence/sites/example-live/ssl/www.example.org.crt",
        "certificate_key": "/emergence/sites/example-live/ssl/www.example.org.key"
    }
}

Update runtime

To load the new site.json file, restart the emergence-kernel service and then stop/start the web server from emergence’s node control panel.