Open edX Ecommerce

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

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

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

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

By |2018-07-04T06:21:58+00:00April 25th, 2018|Categories: Dev Ops, Open edX|17 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.

17 Comments

  1. gang wang August 22, 2018 at 10:55 am - Reply

    great work!

    i definitely follow the instruction, but I cannot get commerce running, and btw, for hawthorn.1, the ssl configuration should be work after run certbot, and it is not necessary to modify the config file

  2. robin July 5, 2018 at 1:56 am - Reply

    This page really helps. thanks. And, there’re still some problems. in the step 4. when enable the commerce site, the 2 urls ( /basket/add/, /checkout/receipt/ ) are not found in the project : github.com/edx/ecommerce ?

    • admin July 5, 2018 at 6:08 am - Reply

      hi robin, if you haven’t already done so i’d suggest joining the Open edX Slack channel, https://openedx.slack.com/. there’s a dedicated Ecommerce channel there where you’ll find more help.

  3. Mark July 4, 2018 at 2:26 am - Reply

    Hi Lawrence, I was able to get ecommerce up and running but whenever I try to add a course in the ECAT, i get this

    Error! Failed to publish commerce data for course-v1:Business+BLDEN360LD+2018_Q3 to LMS. Authentication credentials were not provided.

    • admin July 4, 2018 at 5:44 am - Reply

      hi mark, i also got that error on my first couple of attempts. in my case it was related to settings in Step 5, which are easy to confuse.

      • Mark July 6, 2018 at 1:17 am - Reply

        Hmm, checked step 5 and doesnt seem like I made a mistake. I do know though that I don’t have discovery installed so I’m not sure what should be the value in discovery-api-url, is that necessary?

        • admin July 6, 2018 at 5:21 am - Reply

          the Ecommerce module uses the discovery service, so therein lies your current problem. more broadly, these instructions assume that you followed the community documentation to install the Native build, which would have installed discovery. if you’ve taken a different installation approach then you might be in for a bumpy road.

          • Mark August 1, 2018 at 1:01 am

            Hi lawrence, I was able to make workarounds to get past the discovery service and use api calls instead.
            Now I’ve been able to purchase courses in my tests and I do end up being enrolled afterwards but I dont seem to get the receipts. Does the ecommerce send receipts/bills?

          • admin August 1, 2018 at 5:50 am

            hi mark. yes, it does. have you setup an SMTP mail provider for your instance? if not then the messages are probably being sent but going directly to a spam folder on the receiving end.

          • Mark August 1, 2018 at 9:15 pm

            Hi lawrence, I think we do have an SMTP mail provider setup since we do get activation emails when we register but so far when I purchase a course I don’t get a receipt mailed to me.

          • Mark August 14, 2018 at 1:27 am

            Hi Lawrence,

            Could you check out my question in the google grps?
            https://groups.google.com/forum/#!topic/openedx-ops/Et_tDKZkgfc

            It’s regarding switching from paypal sandbox to live in the ecommerce.
            Thanks a lot,
            Mark

          • admin August 14, 2018 at 7:36 am

            hi mark, typically, yml files need to be executed by ansible in order for parameter value modifications to take effect. having said that, i’m not 100% certain that this would be the case in your google forum question given that the yml file is located in /edx/etc/ whereas playbooks are usually located in a different folder within /edx/. i don’t have access to a non-production machine in which i’d be able to experiment, so i’d encourage you to review your ecommerce install notes and look for any opportunity to re-run any of the playbooks that were part of the installation procedure.

  4. Bobby Caste June 12, 2018 at 12:07 pm - Reply

    Same problem for me. I cannot get commerce running.

    Thanks in advance, great work.

  5. Eric Mensah May 28, 2018 at 8:42 pm - Reply

    For some unknown reason, the ecommerce configuration is not working for me. I’m spent about 2 weeks trying to get it to work but nothing seems to work even though, I followed the intructions.

    Could you elaborate a bit more on the nginx and port configuration for the ecommerce?

    Thanks!

  6. luis April 29, 2018 at 12:28 pm - Reply

    do you have any official information about configuring ssl on opedx?

  7. Luis April 29, 2018 at 11:47 am - Reply

    Very well explained, thanks!!

Leave A Comment

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