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.


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:


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 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:







For example, for the demo server that I built for this article I created a primary domain for the LMS ( and a subdomain for Studio (

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 universe
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
sudo apt-get install certbot 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 |2019-03-05T08:26:35-06:00April 30th, 2018|Categories: Open edX|23 Comments

About the Author:

Lawrence is a full stack developer specializing in the Open edX platform, Django, Angular, Ionic, Wordpress and Amazon Web Services. He lives in Puerto Escondido, Oaxaca, Mexico.


  1. Yonathan Mtz May 27, 2019 at 1:32 pm - Reply

    Hello, I’m trying to configure an open edx instance, but when I add SSL encryption with a domain, and subdomain for the studio, I get the same page in both domain names. What needs to add in ngixn config for fix this situation. Thanks, this documentation is useful…

    • admin May 28, 2019 at 6:30 am - Reply

      which version of open edx did you install?

  2. Hank Hill May 17, 2019 at 3:24 pm - Reply

    Hi Lawrence,

    Thanks for the tutorials on open edx, really helpful!

    I’m stuck on this open edx ssl encryption..

    My site is now on https but I can’t access studio (port 18010). In addition, my cms file is EMPTY! 🙁

    I see on some comments and online people have a cms file filled with code but mine for some reason is empty by default. What’s going on here?


    • Hank Hill May 17, 2019 at 6:01 pm - Reply

      Just got that resolved but I have a new problem – ‘the connection is not private’ – Chrome tells me the site this message sometimes. When I try to get to the site via hyperlink from, for example a word doc, it says ‘the name on the security certificate is invalid or does not match the name of the site’.

      • admin May 18, 2019 at 7:19 am - Reply

        clear cookies in your browser.

    • admin May 18, 2019 at 7:19 am - Reply

      step to resolve depend on the version of open edx you’ve installed. prior to Ironwood you should change the port from 18010 to 443, plus, you should create a sub-domain for CMS in your dns settings like for example, “” and then assign this name in your cms nginx config file using the directive “server_name”. On the other hand, if you’ve installed Ironwood then you’ll probably want to keep the original port setting and simply add the directive “ssl” to the port assignment.

  3. Alberto April 22, 2019 at 11:19 am - Reply

    Dear Laurence, I just did all the process and it works basically right, but I have a problem when setting the cron renewal.
    Can you give more details on WHERE to find the place to add the cron job, or if there is a command line?

    • admin April 22, 2019 at 7:01 pm - Reply

      it’s a command line: crontab -e
      this will open a text editor like vi or vim where you can add a new line with the autorenewal command.

  4. Edo February 12, 2019 at 3:46 am - Reply

    thanks for your tutorial!
    I have a problem (native Ironwood1.rc1): if I try to put cms on a different subdomain (eg from lms (eg, then I’m not able to sign-in in studio… I see studio uses lms for authentication, but it seems non able to keep the authentication across different domains.
    No problem if I use same domain on different ports, either on SSL (es lms on and cmd on
    Thank you

    • admin February 12, 2019 at 8:04 am - Reply

      hi enrico, i can confirm that it is possible to share both authentication and session across the LMS and CMS, on http as well as https. the particular problem you are having might be due to settings in lms.env.json and cms.env.json related to the names and/or cookies. i’d recommend systematically eliminating as much as possible from both files until you resolved your problem. keep in mind that you can delete entire sections of parameters and the platform will still run. you can use this example lms.env.json file as a quasi-example of the bare minimum settings you need.

  5. Giorgos January 7, 2019 at 5:17 am - Reply

    Lawrence Hi!

    Disregard my previous message.

    I deleted from CMS only the line “listen 443;” and that did resolve the problem.

    PS. Add to your blog that the lines:
    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

    do not exist in LMS and users need to add them manually.

    • admin January 7, 2019 at 6:50 am - Reply

      you should only change the port assignment in CMS if (and only if) you prefer to access studio from a custom subdomain which you would setup at your internet domain registrar (ie if on the other hand you prefer to continue to access studio via the custom port assignment 18010 then you should still add your TLS/SSL keys AND you should still redirect traffic from http to https.

      • Giorgos January 7, 2019 at 9:51 am - Reply

        Lawrence sorry but I didn’t understand what you propose here.

        I restarted the AWS instance (stop and then start again) and I cannot access either LMS and CMS.

        I am a little bit lost!

        I added to CMS:
        listen 18010 ssl;

        ssl_certificate /etc/letsencrypt/live/; # managed by Certbot
        ssl_certificate_key /etc/letsencrypt/live/; # managed by Certbot
        include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
        ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

        But I receive an error “duplicate upstream “cms-backend” in etc/nginx/sites-enabled/″

        On the lms side I added:
        server {
        listen 80;
        return 301 https://$host$request_uri;


        listen 443 ssl; # managed by Certbot
        ssl_certificate /etc/letsencrypt/live/; # managed by Certbot
        ssl_certificate_key /etc/letsencrypt/live/; # managed by Certbot
        include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
        ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

        • admin January 7, 2019 at 10:05 am - Reply

          in your CMS configuration you need to remove the line you added, “server_name;”. then it should work.

          • Giorgos January 7, 2019 at 11:00 am

            First of all I would like to thank you for your time to solve my problem.

            Unfortunately, I receive the error: “nginx: [emerg] duplicate upstream “cms-backend” in /etc/nginx/sites-enabled/″.

          • Giorgos January 8, 2019 at 1:24 am

            Lawrence Hi again.

            Disregard my previous message. I launched a brand new instance and followed all the steps again and all that did work.

            I haven’t made any changes to CMS. What changes do I need to make if I want to put it under SSL? I mean to access studio through ?

  6. Giorgos Psathas January 7, 2019 at 5:12 am - Reply

    Lawrence Hi.

    I tried to follow the steps you provided. I used the domain

    I ended up to show my the cms panel (studio).

    Following your steps, up until step 2 went perfect.

    When I opened lms to make the requested changes on step 3, I commented out line “listen 80” and inside server I put the “listen 80;” and “return 301 https://$host$request_uri;” commands.

    BUT, trying to find the “listen 443 ssl;” block of commands you referred that exist near the bottom, I couldn’t find such entry! The entry was inside the cms settings from which I cut the code and then paste it in LMS.

    That did resolve the problem meaning that redirects to LMS home page.

    But now I have the problem that I cannot access the cms

    It show the error:
    Secure Connection Failed

    The connection to was interrupted while the page was loading.

    The page you are trying to view cannot be shown because the authenticity of the received data could not be verified.
    Please contact the website owners to inform them of this problem.

    When I put the “listen 443 ssl;” block of commands inside LMS, I can access the lms through

    When I put the “listen 443 ssl;” block of commands inside CMS, I can access the cms through !!!

  7. Spurgeon October 14, 2018 at 11:53 pm - Reply

    Dear Lawrence,

    As of 15th October, 2018 – I think step 3 is not needed as certbot does the needful.

    Yesterday, I tried with step 3, but couldnt get it work.

    Today, I realised that certbot’s changes have changed indeed and works after step 2.

    You may kindly review and update the blog appropriately.


    • admin October 15, 2018 at 5:28 am - Reply

      thanks Spurgeon. this step is still necessary for Course Management Studio because Certbot incorrectly adds the line “listen 443;”, and, the line “Listen 18010;” needs to become “Listen 18010 ssl;”. But you are correct regarding the LMS — step 3 is just a vanity procedure for this configuration.

      • Spurgeon October 17, 2018 at 3:14 am - Reply

        Thanks a ton for the kind clarification!

        Yes! I forgot about CMS part…

  8. Spurgeon October 12, 2018 at 8:19 am - Reply

    Thank you! God bless you!!

  9. 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 failed (98: Address already in use)
    Jul 24 11:54:23 dev-openedx-ubu nginx[5389]: nginx: [emerg] bind() to failed (98: Address already in use)
    Jul 24 11:54:23 dev-openedx-ubu nginx[5389]: nginx: [emerg] bind() to failed (98: Address already in use)
    Jul 24 11:54:23 dev-openedx-ubu nginx[5389]: nginx: [emerg] bind() to failed (98: Address already in use)
    Jul 24 11:54:23 dev-openedx-ubu nginx[5389]: nginx: [emerg] bind() to 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.