SSL CERTIFICATE RENEWAL

Each webserver in your system requires a valid SSL cerificate. Currenly an SSL certificate can be generated by letsencrypt or it can be manually supplied.

When the build is being initiated on the build machine part of what happens is as follows:

  1. The build machine checks for VALID ssl certificates in the datastore. If valid certificates are found (from previous builds for the same domain that we are deploying to those certificates are used for this deployment.
  2. The build machine checks if there is an SSL certificate available for the current domain, cloudhost and build identifier on the file system of the build machine. If there is (and it is valid) then that certificate is used
  3. If there is no pre-existing SSL certificate (either in the datastore or on the filesystem) of the build-machine that meets our needs then a new certificate is generated or supplied by the person making the deployment if manual certificate provision is set
  4. One way or another we have to have an acceptable SSL certificate and the certificate we have is copied to the config S3 datastore that is shared with the webservers. A check is made to ensure that the SSL certificate has been successfully copied to the S3 Datastore
  5. When each webserver builds then it copies the certificate from the S3 configuration Datastore to its own filesystem and sets up the webserver to use this certificate for its SSL needs. We can then forget about the SSL certificate for a while.
  6. When you run a build a cronjob will be configured on the build machine that will action the renewal of the SSL certificates on the webservers when they expire. The way this will work is that you will have to uncomment the appropriate cronjob on your build machine when you are intending to run your webservers over the long term (months or years in other words). This cronjob will run every night and examine the certificates on your build machine (which were replicated to the webservers during the build process) to see if they are still valid or need to be renewed. When eventually the build machine figures that the certificates on your webservers are out of date, the build machine actions the process of reissuing the SSL certificates and those certificates are then copied to the datastore. On a nightly basis the webservers that are active check for newly issued certificates from the datastore and if they find newly issued certificates, those certificates are installed on the current webserver and the webserver on that machine reloaded so that that webserver is using the newly issued certificate. If a brand new webserver is provisioned due to a scaling event the new webserver will pick up the newly issued certificate from the datastore and install that. That is the operational mechnaism for how the SSL certificates are issued. The way things are set up by default a certificate is considered in need of renewal if there is 7 days or less left until it expires, you can change that value to your taste by looking for "604800" which is "7 days in seconds". This whole process is basically a hands off process and should only need manual intervention if something is off with the process for some reason so unless you are manually deploying an SSL certificate. As a deployer you shouldn't need to to anything to have your web property SSL secured and the certificates renewed.

In a bit more detail, this process can be described as:

As part of the pre-build process on the build-machine a test is made to see if these files already exist in the datastore for our current domain from a previous build

${BUILD_HOME}/providerscripts/datastore/GetFromDatastore.sh ${ssl_bucket}/fullchain.pem ${BUILD_HOME}/runtimedata/${CLOUDHOST}/${BUILD_IDENTIFIER}/ssl/${WEBSITE_URL}
${BUILD_HOME}/providerscripts/datastore/GetFromDatastore.sh ${ssl_bucket}/privkey.pem ${BUILD_HOME}/runtimedata/${CLOUDHOST}/${BUILD_IDENTIFIER}/ssl/${WEBSITE_URL}

If we now have certificates from a previous build they are now available at: 

${BUILD_HOME}/runtimedata/${CLOUDHOST}/${BUILD_IDENTIFIER}/ssl/${WEBSITE_URL}/fullchain.pem 
${BUILD_HOME}/runtimedata/${CLOUDHOST}/${BUILD_IDENTIFIER}/ssl/${WEBSITE_URL}/privkey.pem

If they exist then a check is made to see if they are valid certificates. If the certificates are valid they are copied to the config datastore. If they are not valid then new certificates are generated and stored in these same files and then copied to the S3 config datastore. A check is made to see that the certificates have copied successfully to the config datastore.

We must have valid certificates on the build machine now and they are copied to the webserver and placed in the following location: 

${HOME}/ssl/live/${WEBSITE_URL}/*.pem

There is a daily cron job which runs once a day to check certificate validation. If there are n webservers running then the webserver that "gets there first" checks the validity of its SSL certificate (which will be either valid or invalid for all n webservers) and then if the existing certificate is found to be invalid, a new certificate is generated on the elected machine and is written to the S3 datastore. All the other webservers then copy the new certificate from the datastore to their own

${HOME}/ssl/live/${WEBSITE_URL}/*.pem

If this system works correctly it should be a "hands off process" meaning that in normal operation you don't need to do anything to do with certificates because all of this manages it behind the scenes.

if SSL_GENERATION_METHOD is set to MANUAL then the pre-build process will ask you for a certificate to use for the current build which you will have to obtain from your prefered third party certificate provider. If you use the manual SSL certificate approach you will have to manually update the certificates on your servers. The manual option is only really meant for an emergency if you can't get your certificate in the usual way.