Add SSL Encryption to Open edX

Add a free Let’s Encrypt SSL/TLS certificate to your Open edX installation in just a few minutes using this step-by-step how-to guide.

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.

On an aside, you should note that many of the virtual server configurations in this folder make use of unorthodox http port assignments. For example, Studio is assigned to port 18010. For the avoidance of any doubts, the Open edX design team deliberately took this approach so that you’d only need one fully-qualified domain name (eg edx.org) to access the entire suite of software. However, you can easily set one  or more of the applications to it’s own fully-qualified domain name in order to make it more accessible and user friendly for your users. For example, for obsessive-compulsive dev ops types (like me) you could create an entire series of subdomains such as:

  • example.com

  • studio.example.com

  • forum.example.com

  • ecommerce.example.com

  • discovery.example.com

  • notes.example.com

For example, for the demo server that I built for this article I created a primary domain for the LMS (edx-ssl.lawrencemcdaniel.com) and a subdomain for Studio (edx-ssl-studio.lawrencemcdaniel.com).

In general, all that’s required is that the DNS record for each sub domain points to the same server IP address, and that you edit each virtual server configuration to explicitly name each virtual server and change the “Listen” port back to the default 80 (or 443 for SSL). Lastly, you’d also need to do a search & replace of the server name(s) in the two edX Platform configuration files /edx/app/edxapp/lms.env.json and  /edx/app/edxapp/cms.env.json.

2. Install Certbot

The published installation procedure on the Certbot web site didn’t work earlier today as I was preparing to write this post. Here’s the error message I received when I attempted to run the installation for Nginx running on an Ubuntu server:

Fortunately, I found the following thread dated 9-January-2018 explaining both the problem and a workaround. The short story is that the following modified installation instructions should work:

sudo apt-get update
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
sudo apt-get install python-certbot-nginx 

sudo certbot --authenticator standalone --installer nginx --pre-hook "service nginx stop" --post-hook "service nginx start"

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!

By |2018-06-20T06:14:06+00:00April 30th, 2018|Categories: Open edX|2 Comments

About the Author:

Lawrence is a full stack developer specializing in web and mobile development using AngularJS, Ionic, Wordpress and Amazon Web Services. He has worked as a freelance technology consultant since 1999. He earned a BS in computer science and mathematics with minors in physics and English from University of North Texas.

2 Comments

  1. Calie July 24, 2018 at 4:05 am - Reply

    Hi Lawrence!

    Thank you for you post. It helps a lot.

    But when I try to renewal the certificate it doesn’t work.

    I have the error :
    Jul 24 11:54:23 dev-openedx-ubu nginx[5389]: nginx: [emerg] bind() to 0.0.0.0:18130 failed (98: Address already in use)
    Jul 24 11:54:23 dev-openedx-ubu nginx[5389]: nginx: [emerg] bind() to 0.0.0.0:18080 failed (98: Address already in use)
    Jul 24 11:54:23 dev-openedx-ubu nginx[5389]: nginx: [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use)
    Jul 24 11:54:23 dev-openedx-ubu nginx[5389]: nginx: [emerg] bind() to 0.0.0.0:443 failed (98: Address already in use)
    Jul 24 11:54:23 dev-openedx-ubu nginx[5389]: nginx: [emerg] bind() to 0.0.0.0:18040 failed (98: Address already in use)
    Jul 24 11:54:24 dev-openedx-ubu nginx[5389]: nginx: [emerg] still could not bind()
    Jul 24 11:54:24 dev-openedx-ubu systemd[1]: nginx.service: Control process exited, code=exited status=1
    Jul 24 11:54:24 dev-openedx-ubu systemd[1]: Failed to start nginx – high performance web server.
    Jul 24 11:54:24 dev-openedx-ubu systemd[1]: nginx.service: Unit entered failed state.
    Jul 24 11:54:24 dev-openedx-ubu systemd[1]: nginx.service: Failed with result ‘exit-code’.

Leave A Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.