Maybe you’re like me. On my first Open edX platform I thought, “how difficult could it be?”. Well, pretty difficult. the Open edX UI is complicated for several reasons, and until you understand a few basic principals any modification, no matter how minor, will be a challenge. But with this step-by-step tutorial you’ll have your new logo in production in as little as 10 minutes.

Theory

Changing the default Open edX platform logo, or for that matter, customizing the UI in any way, is more challenging than you might have thought. Rick-click on your Open edX platform’s default “double-circle” logo and choose “Open image in new tab” and you’ll see the first clue as to why things are a bit more complicated with the Open edX UI.

The logo file that appears in your browser is the result of run-time evaluations made by Python Django calls from within the Mako templates of the UI, which itself is capable of running a comprehensive theming system, meaning that any given static asset required by the platform is sourced from either of two distinct locations in the Ubuntu file system. But in addition to that, and as you can see from the manipulated filename in this screen shot, the eventual file that is served comes from a server-side cache that was generated by a “Static Asset Compilation” process.

The Fast Way to Change the Open edX Logo

The good news is that using this method you can change the Open edX platform logo in around 10 minutes. The bad news is that this method is bad practice from a systems management perspective.

  1. Upload your new logo to any publicly-accessible content delivery network (CDN) or cloud drive. If you’re unsure about how to proceed then AWS Cloudfront is a great, nearly-free content delivery network that is easy to setup. Confirm that you’ve correctly uploaded your logo to your CDN by opening the logo file in a browser from your computer.
  2. Connect to your Open edX instance using SSH and then use a text editor like VIM to modify row 19 of the Mako file /edx/app/edxapp/edx-platform/lms/templates/header/navbar-logo-header.html.

Your modification will take effect immediately after saving the template file. No asset compilation process is required because Mako templates are interpreted at run-time and the logo file is being served from a remote server.

Warning: this method is considered bad practice for the following reasons:

  • You are editing your production source code. You modifications will be overwritten any time that you upgrade your Open edX platform.
  • You should try to minimize the complexity of your installation by minimizing the number of external systems that are integrated to your Open edX platform. Since your Open edX server is entirely capable of serving your logo file, you really should take the proper steps to add this new file to Open edX’s static asset compilation process, along with the many other images that makeup the platform.

The Right Way to Change the Open edX Logo

  1. Enable Comprehensive Theming, then install your own custom theme using my example theme template as a base.
  2. Replace the default logo file, logo.png, with your own logo file saved in your theme folder that corresponds with /edx/app/edxapp/edx-platform/lms/static/images/
  3. If your new logo file is named logo.png then you can skip to step 4. Otherwise you need to copy the file /edx/app/edxapp/edx-platform/lms/templates/header/navbar-logo-header.html to the corresponding folder in your custom theme, and then edit row 19 using this screenshot as a guide.

    Note that the code snippet ${static.url("images/logo.svg")} directs Mako to leverage the comprehensive theming system, which will first check to see if your custom theme contains the file “logo.svg”, and if so, then this is the image file that will be sent to the browser. Otherwise the system default “double circle” logo will be returned.
  4. Recompile static assets. If you’re not familiar with what this is then you can just download and run my utility script to recompile assets.
  5. Restart the Open edX platform. If you don’t know how to restart the platform then can just reboot your server using the command line sudo reboot. Alternatively you can download my utility script to restart the Open edX platform.

Helpful Facts

  • The Open edX platform itself is a Python Django web app. Open edX follows Django norms and best practices, so the more you learn about Django the more you’ll understand how to customize and maintain your Open edX instance.
  • the entire UI is generated by Mako templates. Mako templates were designed by Python programmers for Django projects and so it’s not surprising that Mako has become a popular way to build UI’s in Django.
  • The base set of templates for the LMS are stored in /edx/app/edxapp/edx-platform/lms/templates.
  • The img tag for the platform logo is stored in the Mako template/edx/app/edxapp/edx-platform/lms/templates/header/navbar-logo-header.html, and the img tag itself is on row 19 of this template. Ultimately this line of code is just HTML5, and so anything that you can do in HTML5 can be done to this row. For example, you could asset your own custom class or id to this tag and then define this with some inline CSS that you save inside this same template.
  • The default logo is sourced from /edx/app/edxapp/edx-platform/lms/static/images/logo.png. But paver caches a copy of this file (see below.)
  • Replacement or modification of any static asset (image, CSS, javascript file, etcetera) requires that you recompile static assets.
  • Mako template modifications take effect immediately because the templates are interpreted at run-time.
  • All image files and other “static assets” are pre-processed using an open source utility named Paver that consolidates the files into a caching area located in /edx/var/edxapp/staticfiles whereupon each file is individually optimized.
  • The cached logo image that you see in your browser is being served from /edx/var/edxapp/staticfiles/images, assuming that you have not yet enabled comprehensive theming. Otherwise you’ll find a subdirectory in /edx/var/edxapp/staticfiles/ that corresponds with the name of your custom theme.

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