Oscar ecommerce

Osvar er egen Django-lødning som integrerer med Open edX.


 Open edX Ecommerce

Get the Ecommerce module working on your Open edX native build. This post covers installation and configuration of the module, Django configuration, Nginx considerations, and PayPal integration.


This article is a supplement to the official documentation, “How to Install and Start the E-Commerce Service in Native Installations“, which has not been updated in a couple of years and meanwhile, things have changed.

The Open edX Ecommerce module is actually a 3rd party Django project named Oscar that the Open edX team fully integrated into the platform. Like the LMS and CMS, Oscar Ecommerce is an independent application with its own database, user list, passwords and so on. The Open edX team relies on Oauth to provide seamless authentication between the LMS, CMS and Oscar. A lot of the instructions in the official documentation are related to getting Oauth setup and working.

While recently setting up the Ecommerce module on a Gingko.2 installation I stumbled through some the steps in the official documentation and disagreed with others.

Setup Procedure

To get the Ecommerce module (aka Oscar) working you’ll need to do the following:

  1. Verify that the Ecommerce module is running
  2. Configure edX
  3. Setup Oauth between the CMS and the Ecommerce module
  4. Configure Django to use Oscar Ecommerce
  5. Configure Oscar Ecommerce
  6. Navigate to Oscar Ecommerce Dashboard
1. Verify that the Ecommerce module is running

If you followed the documented instructions from “Native Open edX Ubuntu 16.04 64 bit Installation” for Gingko or later then the Ecommerce module is automatically installed and should be running on your instance. You can verify this by running the following command from a terminal window connected to your Ubuntu instance.

sudo /edx/bin/supervisorctl status

If you see the “Ecommerce” module in a running state then you can ignore the first two steps of the official documentation, or at least when running these you should notice that both steps are benign. If for any reason you decide to execute the first two steps of the official documentation then be forewarned that step #2 is tantamount to upgrading your entire platform and could thus bring unintended consequences beyond the scope of the Ecommerce module setup.

Moreover, if the Ecommerce module is not currently running then you should think carefully about your next steps. If your installation is not version Ginkgo or later then you should consider upgrading your entire platform before proceeding simply to ensure that your code base doesn’t venture too far into the unknown. You can read my blog post on Upgrading Open edX for more detail on what’s involved in upgrading and how to prepare.

2. Configure edX

There are a handful of things to configure in the LMS via the eponymous configuration file /edx/app/edxapp/lms.env.json. Refer to the screen shots below for guidance on the subject matter and approximate locations of each section. You’ll need to restart the LMS for these changes to take effect:

sudo /edx/bin/supervisorctl restart edxapp:

Briefly summarizing the purpose of each section:

  • ENABLE_OAUTH2_PROVIDER – This enables the LMS as a provider of Oauth2 authentication services. The Ecommerce module will leverage Oauth2 rather than host its own user list and passwords. For example, as en end user if you’ve elected to “Login with Facebook” then this flag makes your LMS the “Facebook” of that proposition.
  • JWT_AUTH – This is the URL of the JSON Web Token authorizer. In our case it’s exactly the same as the issuer.
  • JWT_ISSUER – This is the URL of the JSON Web Token issuer
  • OAUTH_OIDC_ISSUER – This is the URL of the Open ID issuer (eg your LMS platform)
  • PAID_COURSE_REGISTRATION_CURRENCY – The Ecommerce module reads this value to determine which currency symbol to display along side products. This value is also passed to the payment gateway.
  • PDF_RECEIPT_ – All of the salient text for customer receipts is stored in these fields.
3. Setup Oauth between the CMS and the Ecommerce module

It wasn’t initially apparent to me but, setting configuration parameters in lms.env.json only indicates to the LMS that you want to use it as part of an Oauth authentication; you still have to setup Oauth itself. We’ll use the Django admin console for this. For the Python/Django uninitiated, Django apps like LMS and CMS come with a “back end” admin console where additional configuration parameters are available beyond what you’ll find in the four JSON files in /edx/app/edxapp/. Refer to this screen shot for the URL path and guidelines for creating an Oauth client.

4. Configure Django to use Oscar Ecommerce

This is the definitive step in “activating” the Ecommerce module. Refer to the following screen shot for parameter values and the desired outcome.

5. Configure Oscar Ecommerce
sudo su ecommerce -s /bin/bash
cd ~/ecommerce
source ../ecommerce_env
python manage.py makemigrations
python manage.py migrate
python manage.py create_or_update_site \
	--site-id=1 \
	--site-domain=preescolar.atentamente.mx:8002 \
	--partner-code=edX \
	--partner-name='Open edX' \
	--lms-url-root=https://preescolar.atentamente.mx \
	--payment-processors=paypal \
	--client-id=ecommerce-key \
	--client-secret=ecommerce-secret \
	--from-email=edx.[email protected].com \

Following is how these command line arguments map to the two Django configuration screens from the previous step.

6. Navigate to Oscar Ecommerce Dashboard

If everything is working as it should then you’ll be able to navigate to the Ecommerce dashboard where you can begin setting up your products. You can refer to the Oscar Ecommerce Official Documentation for further instructions on setting up products, payment gateways, etcetera.

Trouble Shooting

  • Firewall. You should pay close attention to the unorthodox port assignments used by the Ecommerce module. By default the Otto Ecommerce module runs on port 8002 and the LMS “Course Discovery” API runs on port 18381. You might need to open these ports on your firewall.
  • Port Settings. Take note that ports have changed over time. The official documentation makes multiple references to ports 18020 and 18130; neither of which seem to be in use on Ginkgo.
  • Nginx. If you’re using SSL on your site then you might need to make adjustments to one or more of the Nginx virtual server configurations located in /edx/app/nginx/sites-available/.