Add SSL Encryption to Open edX

Summary

Let’s Encrypt is a free, automated, and open Certificate Authority that is sponsored by Internet Security Research Group (ISRG) which itself is a venerable who’s who of silicon valley Internet companies. Let’s Encrypt has made it much easier to request, install and maintain SSL/TLS certificates on your web servers. For Ubuntu/Nginx web apps like Open edX, Let’s Encrypt uses a platform named Certbot that provides a simple installation process that MOSTLY works, barring a couple of minor hiccups. By following these instructions you should be able to get HTTPS working on your server in less than an hour.

If you’re already familiar with Nginx then you can probably jump over to Certbot’s installation guide for Ubuntu 16.04 / Nginx, and if so then god speed. Otherwise by all means, please read on.

Now, about those hiccups. First, as of the date of publication of this post at least, Certbot’s instructions required a minor modification. Second, some of the Open edX virtual server configurations are too complex for certbot to understand, causing it to make minor though correctable mistakes when configuring HTTP redirections to HTTPS. Fortunately, both of these are minor problems which we’ll easily avert in the procedure that follows.

Setup Procedure

1. Prepare Your Nginx Virtual Server Configuration Files

Open edx runs on Nginx, a fast, bare-bones web server alternative to Apache, and like Apache, Nginx can host multiple virtual web servers on the same Ubuntu server instance. In the case of the Open edX software suite there are nearly a dozen such web servers — two of them being your LMS and Course Management Studio — which you can view from either of the following two paths:

/etc/nginx/sites-enabled/
or
/edx/app/nginx/sites-available/

Explicitly name each server. Open edx native build configuration, by design, automagically infers the fully-qualified domain name of your LMS, elminating any need on your part to explicitly name the virtual server. Unfortunately, this convenience strategy undermines Certbot’s ability to read your virtual server configuration files to determine the names of the SSL certificates you need to request. You’ll therefore need to edit the LMS and CMS files, adding a line near the top of each file to explicitly name each server.

sudo vim /etc/nginx/sites-enabled/lms

This post only covers setting up SSL/TLS for the LMS and CMS, however, if you analyze the other virtual server configuration files in this folder you’ll probably be able to apply these same procedures to other sites in your Open edX software suite like for example, the Ecommerce module.

2. Install Certbot

The published installation procedure on the official Certbot site changed in late 2020. The good news is that the new installation procedure is very simple to follow assuming that you are running Ubuntu 20.04 LTS or later:

sudo apt-get update
sudo snap install core; sudo snap refresh core
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx

After re-running the install procedure with these modified instructions you should see screen output substantially resembling the following.

Choose “2: Redirect” and hit enter.

If you got similar results then CONGRATULATIONS, you are now the proud owner of your very own SSL/TLS certificates! Certbot only does two things during its installation procedure. First, it saves sets of files in /etc/letsencrypt/live/. And second, it modifies your Nginx virtual server configurations located in /etc/nginx/sites-enabled/. Using sudo you can inspect both of these to learn more about the specifics of what it did.

3. Edit Nginx Virtual Server Config Files

The Open edX virtual server configuration files for the LMS and CMS are a little too complex for Certbot to analyze, causing it make a couple of minor mistakes. First, it correctly adds a new listener on port 443 but incorrectly neglects to un-assign the existing listener on port 80. Second, it incorrectly places the SSL certificate files paths and listener directive at the bottom of the virtual server config file. Fortunately, these are easy to remedy.

First, open the lms config file and look for the new configuration code snippets that Certbot added near the bottom of the file.

Cut and re-paste this configuration code snippet towards the top of the same file as per the screen shot below. Summarizing what we’re doing:

1. Add a new virtual server that listens on port 80, and redirects all traffic to https
2. In the original virtual server declaration, remove the directive to listen on port 80
3. Paste the Certbot code snippet immediately below the server_name directive

Certbot additionally pastes a commented-out snippet for handling redirection from http to https, however, we’ll ignore this snippet entirely since we’ve already taken care of this in the previous step.

After you finish all edits you’ll need to restart Nginx:

sudo systemctl restart nginx

To verify that your configuration edits are correct you should check the server status after restarting:

sudo systemctl status nginx

4. Test Your Platform

If everything works then your Open edX LMS and CMS should automatically redirect to https.

5. Setup A Cron Job To Auto-Renew Your Certificate(s)

The Certbot packages on your system come with a cron job that will renew your certificates automatically before they expire. Since Let’s Encrypt certificates expire after only 90 days, it’s highly advisable to take advantage of this feature. You can test automatic renewal for your certificates by running this command:

sudo certbot renew --dry-run

If that appears to be working correctly, you can arrange for automatic renewal by adding a cron job which runs the following command on a recurring basis:

certbot renew

The screen shot below shows a cron job that runs once a day to check for and renew any expiring certificates.

I hope you found this helpful. Please help me improve this article by leaving a comment below. Thank you!