Install and Start the E-Commerce Service#
Warning
This document is out of date regarding virtual environment configuration. E-Commerce should be properly provisioned for you as part of Dockerized devstack.
To install and start the edX E-Commerce service, you must complete the following steps.
Note
These steps assume that you are running Open edX devstack. If you prefer to run the E-Commerce service locally on your computer instead of on the virtual machine (VM) that devstack uses, see :Development Outside Devstack.
Set Up a Virtual Environment#
Create or activate a Python virtual environment. You execute all of the commands described in this section within the virtualenv (unless otherwise noted).
For more information, see Virtual Environments.
Run the following command to install dependencies.
$ make requirements
(Optional) Create settings overrides that you do not commit to the repository. To do this, create a file named
ecommerce/settings/private.py
. Theecommerce/settings/local.py
file reads the values in this file, but Git ignores the file.
Run Migrations#
To set up the ecommerce
database, you must run migrations.
Note
Local installations use SQLite by default. If you use another database backend, make sure you update your settings and create the database, if necessary, before you run migrations.
To run migrations, execute the following command.
$ make migrate
When you run migrations, the E-Commerce service adds a default site to your installation.
Configure OAuth#
The E-Commerce service relies on the LMS, which serves as the OAuth 2.0 authentication provider.
To configure the E-Commerce service to work with OAuth, complete the following procedures.
Create and Register a Client#
To create and register a new OAuth client, follow these steps.
Start the LMS.
In your browser, go to
http://127.0.0.1:8000/admin/oauth2_provider/application/
.Select Add client.
Leave the User field blank.
For Client Name, enter
E-Commerce Service
.For URL, enter
http://localhost:8002/
.For Redirect URL, enter
http://127.0.0.1:8002/complete/edx-oauth2/
. This is the OAuth client endpoint.The system automatically generates values in the Client ID and Client Secret fields.
For Client Type, select Authorization code.
Enable Skip authorization.
Select Save.
Configure a Site, Partner, and Site Configuration#
To finish creating and configuring your OAuth client, you must configure a
partner, site, and site configuration for the E-Commerce service to use. The
site that you configure is the default site that the E-Commerce service adds
when you run migrations. You must update this default site to match the domain
that you will use to access the E-Commerce service. You must also set up a site
configuration that contains an oauth_settings
JSON field that stores your
OAuth client’s settings, as follows.
Setting |
Description |
Value |
---|---|---|
|
OAuth 2.0 client key |
The Client ID field in the Create and Register a Client section for backend server-to-server calls. |
|
OAuth 2.0 client secret |
The Client Secret field in the Create and Register a Client ection for backend server-to-server calls. |
|
OAuth 2.0 client key |
The Client ID field in the Create and Register a Client section. |
|
OAuth 2.0 client secret |
The Client Secret field in the Create and Register a Client section. |
|
OAuth 2.0 authentication URL |
For example, |
|
OAuth token issuer |
For example, |
|
User logout URL |
For example, |
To configure your default site, partner, and site configuration, use the
appropriate settings module for your environment
(ecommerce.settings.devstack
for Devstack,
ecommerce.settings.production
for Fullstack) to run the following Django
management command. This command updates the default site and creates a new
partner and site configuration with the specified options.
$ sudo su ecommerce $ python manage.py create_or_update_site --site-id=1 --site-domain=localhost:8002 --partner-code=edX --partner-name='Open edX' --lms-url-root=localhost:8000 --theme-scss-path=sass/themes/edx.scss --payment-processors=cybersource,paypal --backend-service-client-id=[Change to OAuth Client ID for backend service calls] --backend-service-client-key=[Change to OAuth Client Secret for backend service calls] --sso-client-id=[Change to OAuth Client ID for SSO calls] --sso-client-key=[Change to OAuth Client Secret for SSO calls]
Add Another Site, Partner, and Site Configuration#
If you want to add more sites, partners, and site configurations, you can use
the create_or_update_site
command. The following options are available for
this command.
Option |
Required |
Description |
Example |
---|---|---|---|
|
No |
Database ID of a site you want to update. |
|
|
Yes |
Domain by which you will access the E-Commerce service. |
|
|
No |
Name of the E-Commerce site. |
|
|
Yes |
Short code of the partner. |
|
|
No |
Name of the partner. |
|
|
Yes |
URL root of the Open edX LMS instance. |
|
|
No |
|
|
|
No |
Comma-delimited list of payment processors used on the site. |
|
|
Yes |
OAuth client ID. |
|
|
Yes |
OAuth client secret. |
|
|
Yes |
Address from which email messages are sent. |
|
|
No |
Indication that specifies whether enrollment codes for seats can be created. |
|
|
No |
Email address displayed to user for payment support. |
|
|
No |
URL displayed to user for payment support. |
|
To add another site, use the appropriate settings module for your environment
(ecommerce.settings.devstack
for Devstack,
ecommerce.settings.production
for Fullstack) to run the following Django
management command. This command creates a new site, partner, and site
configuration with the options that you specify.
$ sudo su ecommerce $ python manage.py create_or_update_site --site-domain=[change me] --partner-code=[change me] --partner-name=[change me] --lms-url-root=[change me] --client-id=[OAuth client ID] --client-secret=[OAuth client secret] --from-email=[from email]
Start the Server#
To complete the installation and start the E-Commerce service, follow these steps.
Note
Local installations use SQLite by default. If you use another database backend, make sure you update your settings and create the database, if necessary, before you run migrations.
(Devstack only) If you are using devstack, switch to the
ecommerce
user and use theecommerce.settings.devstack
settings module to run the following commands.$ sudo su ecommerce $ make serve
To run the server, execute the following command.
$ python manage.py runserver 8002
Note
If you use a different port, make sure you update the OAuth client by using the Django administration panel in the LMS. For more information about configuring the OAuth client, see Configure OAuth.
Switch from ShoppingCart to E-Commerce#
By default, the ShoppingCart service is enabled when you install an Open edX instance. To use the E-Commerce service to handle ecommerce-related tasks instead of ShoppingCart, follow these steps.
Sign in to the Django administration console for your base URL. For example,
http://{your_URL}/admin
.In the Commerce section, next to Commerce configuration, select Add.
Select Enabled.
Select Checkout on ecommerce service.
(Optional) In the Single course checkout page field, override the default path value of
/basket/single-item/
with your own path value.Important
If you override the default path value, you must also change all of the code that relies on that path.
Set the Cache Time To Live value in seconds.
Select the site for which you want to enable the E-Commerce service.
Select Save.
Development Outside Devstack#
If you are running the LMS in devstack but would prefer to run the
E-Commerce service on your host, set up a reverse port-forward. This reverse
port-forward allows the LMS process inside your devstack to use
127.0.0.1:8002
to make calls to the E-Commerce service running on your
host. This simplifies LMS URL configuration.
To set up a reverse port-forward, execute the following command when you SSH into your devstack. Make sure that you run this command on the VM host, not the guest.
$ vagrant ssh -- -R 8002:127.0.0.1:8002