Get Ecommerce working on your Open edX native build. This post is a supplement to the official documentation, “How to Install and Start the E-Commerce Service in Native Installations“, covering installation and configuration, Django configuration, Nginx considerations, and PayPal integration.

Summary

The Open edX Ecommerce module is actually a 3rd party Django project named Oscar that the Open edX team fully integrated into the platform by fusing the user lists together with Oauth. While recently setting up the Ecommerce module on a Gingko.2 installation I found myself stumbling through some the steps in the official documentation while disagreeing entirely with others. What follows is a modified procedure that I followed to get Ecommerce running on a Ginkgo.2 installation. Hopefully this will save you some time.

Setup Procedure

  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
Need it now?
Professional Installation Service

Get Ecommerce setup same day.

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 an end user if you’ve ever 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 LMS 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.

Note: I’ve seen conflicting documentation regarding the proper port assignment for the Ecommerce module. Some suggest 8002 whereas others say it should be 18130. After some experimentation I’ve learned that either of these assignments will work, provided that you are consistent with your settings in /edx/app/edxapp/*.json and /edx/etc/ecommerce.yml and /etc/nginx/sites-enabled/ecommerce.

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

This step essentially binds together the Django configurations you created in the previous two steps 3 & 4 so that the Oscar Ecommerce module works seamlessly with our LMS.

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.atentamente@gmail.com \
	--discovery_api_url=https://preescolar.atentamente.mx:18381/

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

6. Modify /edx/etc/ecommerce.yml

I don’t understand the technicalities behind how and why the Ecommerce module reads this file at run-time, but I assure you that it does. In this file you’ll find a half-dozen occurrences of the URL, “http://127.0.0.1:8000” which you should update to your instance’s domain name or IP address. Also, make sure that the port assignment that you choose is consistent with the value you used in /edx/app/edxapp and /etc/nginx/sites-enabled/ecommerce. You need to restart the Ecommerce service afterward in order for the new settings to take effect.

sudo /edx/bin/supervisorctl restart ecommerce
7. 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 Oscar 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/.
  • Additional Work Notes. You can reference these additional work notes from my colleague Eric Mensah and myself as he was trouble-shooting a couple of details related to ports and ssl.

If you see the screen below when you try to navigate to the Ecommerce site then be aware that this, believe it or not, is correct. This is what you’ll initially see prior to logging in to the Ecommerce back end administration console.

If you see this screen after clicking the “Login” button (note the http://127.0.0.1:8000 domain name) then you need to update /edx/etc/ecommerce.yml from Step 6.

If you get a 404 error like the screen shot below then you need to modify the nginx configuration in /etc/nginx/sites-enabled/ecommerce. Most likely you need to modify the port assignment to match the port that you used in /edx/app/edxapp/*.json and /edx/etc/ecommerce.yml.

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