Open edX installation and configuration

This article or chapter is incomplete and its contents need further attention. Some information may be missing or may be wrong, spelling and grammar may have to be improved, use your judgment!

## Contents

* 1 Introduction
* 2 Installation of the Bitnami stack
* 2.1 Installation of a test system under Ubuntu 16
* 2.1.1 Overview
* 2.2 installation with root privileges
* 2.2.1 Create a shortcut
* 2.2.2 To start/stop the server
* 2.2.3 Initial Configuration - get the admin console working
* 2.2.4 Email configuation
* 2.2.5 The environment
* 2.3 Security
* 3 Configuration
* 3.1 Add a site
* 3.2 User management
* 3.2.1 Creating a user with admin tools
* 3.2.2 Restrict emails to certain domains
* 3.2.3 Course creation rights
* 3.2.4 SSO from other services overview
* 3.2.5 SAML configuration
* 3.3 LTI
* 3.4 Bulk email from courses
* 3.5 Course Talk
* 4 Using and installing plugins
* 4.1 XBlocks directory
* 4.2 Listing installed XBlocks
* 4.3 Using an installed XBlock
* 4.4 Installation of XBlocks with the Bitname stack
* 5 Creating a course
* 6 Links
* 6.1 Official documentation
* 6.2 Bitnami documentation

## Introduction[edit | edit source]

According to the [homepage], "The Open edX platform is a free--and open source--course management system (CMS) that was originally developed by edX. The Open edX platform is used all over the world to host Massive Open Online Courses (MOOCs) as well as smaller classes and training modules."

The following content will apply to a May 2018 Ginko 2-4 installation on Ubuntu 16LTS. The Eucalyptus (2017) was described here.

See also:

* Open edX

## Installation of the Bitnami stack[edit | edit source]

There are many different ways to install and run an edX server.

As of March 31 2017, we managed to install a Bitnami stack as described below. As of May 2018 some contents below are outdated. Use with care.

We got it from here:

* https://bitnami.com/stack/edx

Log onto your server machine and use something like:

wget https://bitnami.com/redirect/to/193216/bitnami-edx-ginkgo.2-4-linux-x64-installer.run

We also suggest to read the official documentation of the Bitnami stack

### Installation of a test system under Ubuntu 16[edit | edit source]

Like for Eucalyptus, there are small glitches fro ginkgo, e.g. in terminal mode, the installation script seem to be stuck after reaching 100%. In reality (I found out after abortin), the installation takes ages without telling so, about an hour.

There are display problems with the X version (I wonder when programmers will learn that people actually do use high resolution screens and have been doing that for the last bloody 6 years). The dialogue is a bit different from the X version and the terminal version.

You also could provide the installation script with parameters. This could help doing a re-installation. Use "--help" to find out.

#### Overview[edit | edit source]

If you have free access to a server machine, the easiest method is probably installing the "bitnami" stack (README.txt file. It will install a complete independent software pack in a separate directory including web servers, database servers, several programming languages, etc.

If your machine already runs web servers, data base servers, etc. it will use other ports. From the README file: "The default listening port for Apache is 8080, for Elasticsearch 9300, for Memcached 11211, for MongoDB 27017, for MySQL is 3306, for RabbitMQ 5672, for Open edX XQueue 18040 and 18010 for Open edX CMS. If those ports are already in use by other applications, you will be prompted for alternate ports to use." This does of course require that you allow that...

Summary of ports that must be openend or can remain local (user installation for a system with an existing LAMP/Java stack, changed apache default from 8080 to 8000)

PORTS used by edX standard and custom installations (reused from the old Eucalyptus installation)  Service  | system default ports | default user install

ports

| our user install | our root install

(machine already had a LAMP stack)

| requires open firewall

|
|
|
|
|

mysql_port  | 3306 | 3307 | 3307 | 3307 |
smtp_port  | 587 | 587 | 587 | 587  |
apache_server_port  | 80 | 8080 | 8000 | 81  | x
apache_server_ssl_port  | 443 | 8443 | 8443 | 443  | x
mongodb_port  |  | 27017 | 27017 | 27017
elasticsearch_port  |  | 9200 | 9200 | 9200
elasticsearch_node_port  |  | 9300 | 9300 | 9300
rabbitmq_server_port  |  | 5672 | 5672 | 5672
rabbitmq_management_port  |  | 15672 | 15672 | 15672
Open edX XQueue  |  | 18040 | 18040 | 18040  | x
Open edX CMS  |  | 18010 | 18010 | 18010  | x

### installation with root privileges[edit | edit source]

sudo su
ufw allow 81/tcp
ufw allow 443/tcp
ufw reload

./bitnami-edx-ginkgo.2-4-linux-x64-installer.run

Now exit and exit, log into the server with X enabled if you prefer the installation popup window, e.g.

ssh your.machine -XY

Below is a slightly censored transcript of the installation dialog. I basically used default values.

sudo bitnami-edx-ginkgo.2-4-linux-x64-installer.run

-
Welcome to the Open edX powered by Bitnami Setup Wizard.

-
Select the components you want to install; clear the components you do not want
to install. Click Next when you are ready to continue.

Open edX : Y (Cannot be edited)

Demo course for Open edX [Y/n] :y
Is the selection above correct? [Y/n]: y

-
Installation folder

Please, choose a folder to install Open edX powered by Bitnami
Select a folder [/opt/edx-ginkgo.2-4]:

-
Create Admin account

Open edX powered by Bitnami admin user creation

Your real name [User Name]: Daniel K. Schneider

Email Address [user@example.com]:

Login [user]: admin

Password :
Please confirm your password :

-
Web Server Port

Choose a port that is not currently in use, such as port 81.
Apache Web Server Port [81]:

-
MySQL Information

Please enter your MySQL database information:

Choose a port that is not currently in use, such as port 3307.
MySQL Server port [3307]:

-
The hostname that will be used to create internal URLs. If this value is
incorrect, you may be unable to access your Open edX installation from other
computers.

Hostname [127.0.1.1]: xxxxxxx.unige.ch

Do you want to configure mail support? [y/N]: y

-
Configure SMTP Settings

This is required so your application can send notifications via email.
Default email provider:

[1] GMail
[2] Custom
Please choose an option [1] : 2

-
Configure SMTP Settings

This data is stored in the application configuration files and may be visible to
others. For this reason, it is recommended that you do not use your personal
account credentials.

Username []:

Password :
Re-enter :
SMTP Host [xxxxxxxx.unige.ch]:

SMTP Port [587]:

Secure connection

[1] None
[2] SSL
[3] TLS
Please choose an option [1] :

-
Setup is now ready to begin installing Open edX powered by Bitnami on your
computer.
outlook
Do you want to continue? [Y/n]:

-
Please wait while Setup installs Open edX powered by Bitnami on your computer.

Installing
0% ______________ 50% ______________ 100%
########################################

After the script shows claims it is done (see the 100% above), it is not and you should wait for a long time before you abort. In the terminal version, there is no feedback that the system is installing. The "installing progress" bar above only shows the first "unpacking" part if I understood right.

So I repeat, wait for a very long time (about one hour), after the script claims 100% installing.

If you want to redo the installation with the X popup (I did that since I hit ctrl-c too early, see above).

* Hit CTRL-C
* Make sure that X can display on your screen (else redo the "terminal" installation, and this time: WAIT !)
* sudo rm -r /opt/edx-ginkgo.2-4/

Be patient ... wait until you see this.

#### Create a shortcut[edit | edit source]

We suggest creating the following symbolic link:

sudo ln -s /opt/edx-ginkgo.2-4/ /edx

That way it's a bit easier to type script names, e.g. the frequently used

sudo /edx/ctlscript.sh restart

#### To start/stop the server[edit | edit source]

You can use the included ctlscript.sh utility that sits in the top-level directory, e.g. /opt/edx-eucalyptus.3-0

sudo ./ctlscript.sh start|stop|restart

EdX will be available on the selected port, e.g.

http://yourserver_ip_or_name:81
- or -
http://yourserver_ip_or_name:8080

Again, if this does not work from your client machine, adapt the firewall settings (see above)

edX administration panel

#### Initial Configuration - get the admin console working[edit | edit source]

(from the Eucalyptus installation - not yet updated since one also can use the web console)

By default, anyone now can require an account and will get it. This may attract spammers.

After login into the system you cannot do anything, except signing up for the demo class and configuring the admin profile. You can configure edX through the http://youredx:port/admin URL.

* Read 4\. Configuring the Open edX Platform & enjoy.

There are three ways to use the admin console:

(1) Log into the admin console on localhost or via edx-studio

http://localhost:81/admin

The admin console is available on the localhost, which is really bad news if you cannot run an Xserver on your client machine. If you do happen to have a client linux machine (I do) then you can run firefox on the server machine. Connect to the server with the `-XY` option !!

ssh your_server -XY
sudo apt-get install firefox

Now your freaky Ubuntu will not run the firefox you just installed, but a copy of the one you already may have running on your local machine. Type:

firefox --new-instance

Open http://localhost:81/admin and enjoy the difficult editing over a remote X connection.

Alternatively, if you change a setting, you can access the admin console through the same port as edx studio.

* http://_yoursite_:18010/admin/

(2) Using a terminal web client

Instead of running a web browser over an X connection, you also can use a terminal browser, E.g.

sudo apt-get install lynx
lynx http://localhost:81/admin

You will see many configuration items grouped into categories. Each item can be edited in three ways:

* Clicking on the item
* Add
* Change (same as clicking on item)

(3) Create an ssh tunnel

* Read the FAQ section How to access a server using an SSH tunnel?

You may have to give the full server name. Example:

* Source port: 81
* Destination: your_full_server_name:81

#### Email configuation[edit | edit source]

It is quite important that your MOOC can send emails, at least for account confirmation.

There are two methods:

* Use the google SMTP using a Google Account as sender
* Configure a local smtp server.

Sometimes local STMP servers use restrictions, talk to your system administrator. Typically, you should edit the 4 configuration files in `apps/edx/conf` and use settings like this:

"EMAIL_BACKEND": "django.core.mail.backends.smtp.EmailBackend",
"EMAIL_HOST_USER": "USER@YOUR_MAILDOMAIN.domain",
"EMAIL_HOST_PASSWORD": "XXXXXXX",
"EMAIL_HOST": "your_outgoing_mail_server.YOUR_DOMAIN.domain",
"EMAIL_PORT": 587,
"EMAIL_USE_TLS": true,

Make sure that (a) your user exists, that (b) settings are correct and (c) that you are allowed to send mail from a portal.

If the email is not working, you can still explorer edX for testing, i.e. you can manually create accounts and then send the passwords to your student population. For people who signed up but did not get any email, you could explore the Students section in the admin console. E.g. by clicking on Registration objects in Registration you could retrieve an activation key.

#### The environment[edit | edit source]

Since you installed a complete stack that includes everthing edX needs, you will have to be careful when executing python scripts, do updates and so forth. Command line scripts should be called via

/opt/edx-eucalyptus.3-0/apps/edx/bin/python.edxapp

and not you standard python !

Otherwise consider something like this (not tested):

sudo /opt/edx-eucalyptus.3-0/use_edx
sudo source /opt/edx-eucalyptus.3-0/apps/edx/scripts/edxapp_env

### Security[edit | edit source]

The manuals and the admin console strongly suggest to do the following. We quote:

Security warning for Open edX

Running Open edX in production without enabling code jail is extremely dangerous, puts your student's data at risk, and is not recommended. You can set it up following the steps of this page.

Install AppArmor CodeJail

(1) Read How to install CodeJail Sandbox? (Bitnami). For a root install, the instructions in the Bitname page (just above) seem to be correct, but some appear to be already done.

(2) Already there (?):

sudo apt-get install apparmor
sudo addgroup sandbox
sudo adduser --disabled-login sandbox --ingroup sandbox

(3) After checking the above, continue and create a /etc/sudoers.d/01-sandbox file with the following contents. Make bloody damn sure that the path are ok, before you save the file. A single mistake in a single line will block your system. If that happens type `su`, enter the root password (not yours), then edit and uncomment all lines with #. Then restart with sudo.

sudo visudo -f /etc/sudoers.d/01-sandbox

File contents:

daemon ALL=(sandbox) SETENV:NOPASSWD:/opt/edx-eucalyptus.3-0/apps/edx/venvs/edxapp-sandbox/bin/python
daemon ALL=(sandbox) SETENV:NOPASSWD:/usr/bin/find
daemon ALL=(ALL) NOPASSWD:/usr/bin/pkill

(4) Create/Edit /etc/apparmor.d/opt.bitnami.apps.edx.venvs.edxapp-sandbox.bin.python

sudo touch /etc/apparmor.d/opt.bitnami.apps.edx.venvs.edxapp-sandbox.bin.python

with the following contents:

#include <tunables/global>
#include <tunables/global>

/opt/edx-eucalyptus.3-0/apps/edx/venvs/edxapp-sandbox/bin/python {
#include <abstractions/base>
#include <abstractions/python>

/opt/edx-eucalyptus.3-0/apps/edx/venvs/edxapp-sandbox/** mr,
# If you have code that the sandbox must be able to access, add lines
# pointing to those directories:
/opt/edx-eucalyptus.3-0/apps/edx/edx-platform/common/lib/sandbox-packages/** r,
/opt/edx-eucalyptus.3-0/python/lib/python2.7/** r,

/tmp/codejail-*/ rix,
/tmp/codejail-*/** wrix,

(5) Add this to apparmor_parser

sudo apparmor_parser /etc/apparmor.d/opt.bitnami.apps.edx.venvs.edxapp-sandbox.bin.python
sudo installdir/ctlscript.sh restart apache

## Configuration[edit | edit source]

Configuring edX can be fairly confusing to a novice. So far I identified three different interfaces

(1) EdX can be configured from the administration console which by default only runs on the server machine (localhost). E.g. if the edX server runs on port 81 (yours may run under 8080), then:

http://localhost:81/admin

(2) You also can and must edit configuration files that sit in the ./apps/edx/conf directory (see below for an example)

(3) You can enter command line instructions that sit in the /opt/edx-eucalyptus.3-0/apps/edx/edx-platform directory, e.g.

cd /opt/edx-eucalyptus.3-0/apps/edx/edx-platform

Let us recall that you must launch the scripts with the python stack distributed. To do so, instead of just typing something like python manage.py, you will have to type ` /opt/edx-eucalyptus.3-0/apps/edx/bin/python.edxapp manage.py` or if you got your symbolic link `/edx/apps/edx/bin/python.edxapp manage.py `

List available commands:

sudo /opt/edx-eucalyptus.3-0/apps/edx/bin/python.edxapp ./manage.py lms --settings aws help

Once you understood that principle, it still will be difficult to get anything done.

### Add a site[edit | edit source]

In Django:

* Select Sites->Site

* Enter the Internet name including the port, e.g. yoursite.site:81

### User management[edit | edit source]

By default, anyone can sign up as a simple user. This can be a source for spamming and should be further analyzed....

#### Creating a user with admin tools[edit | edit source]

The web interface for administrators (http://localhost:81/admin) allows make users active and to give them rights. Creating a user does not seem to work.

Under site administration:

* Authentication and Authorization -> Users
* The same admin interface section also allows to change various permissions, i.e. allow someone to become staff (being able to use this interface) or become superuser. Staff and superuser is not the same as being an instructor for a class.

When last tried this did not work, e.g. there is no field to enter a user name:

Django "administration" tool woes, cannot enter a user id

Workarounds:

* Create a user in the LMS, then make changes in the console. That is what I used (for now)

* Alternatively, the following command line script creates a new superuser according some source on the web (verify !!!)

sudo /edx/apps/edx/bin/python.edxapp ./manage.edxapp lms manage_user staff staff@example.com --staff --superuser --settings=aws

Create staff users: In the administration console:

* Goto Authentication and Authorization
* Users
* Tick `Staff status`

Administration console for approving course creation

* http://__yoursite_:18010/admin/course_creators/coursecreator/

E.g. to find it, go to edx-studio, edit the URL to add `admin`. Then either find the course create section or add `course_creators/coursecreator/` to the URL.

#### Restrict emails to certain domains[edit | edit source]

cd ./apps/edx/conf/
# backup the files
sudo cp lms.env.json lms.env.json.OLD
sudo cp cms.env.json cms.env.json.OLD

In each of the files you could a line at the end that restricts registration to certain domains. Read this.

Example restring registration to University of Geneva emails (the regexp actually also would allow for subdomains like tecfa.unige.ch, which we don't have anymore). "REGISTRATION_EMAIL_PATTERNS_ALLOWED": ["^.*@(.*\\\\.)?unige\\\\.ch$"],

The following will allow registration from anywhere: "REGISTRATION_EMAIL_PATTERNS_ALLOWED": null,

#### Course creation rights[edit | edit source]

You can give course creation rights in the django administration tool (that be default only runs on the server machine or via a SSH tunnel)

Have the user create him/herself before through the normal sign up mechanism.

Then open the django console or directly the user management tool.

* http://localhost:81/admin/auth/user/

* Click on the user
* Then, under permissions, tick `staff status`

#### SSO from other services overview[edit | edit source]

edX provides a number of possibilities for single sign-on, e.g.

* Oauth (Google, Facebook, LinkedIn)
* SAML (also known as Shiboleth) - used by many universities, e.g. the Swiss higher education network.
* LTI (see the LTI section) - An e-learning standard allowing one platform to send users to another platform

#### SAML configuration[edit | edit source]

SAML is popular with Universities, read

* 4.17.3. Integrating Third Party Authentication in Open edX
* Integrating with a SAML Identity Provider
* 4.17. Enabling Third Party Authentication

To make this work you first need to enable third party auth support.

Edit

/opt/edx-eucalyptus.3-0/apps/edx/conf/lms.env.json

Change from false to true:

"FEATURES": {
.....
"ENABLE_COMBINED_LOGIN_REGISTRATION": true,
"ENABLE_THIRD_PARTY_AUTH": true,

Restart the server. If you did this right, then you will see backend name: tpa-saml in the Add Provider Configuration:

To add a provider:

Third_Party_Auth › Provider Configuration (SAML IdPs) › Add Provider Configuration (SAML IdP)

* Fill in the name of your provider institution
* Tick skip registration form and skip email verification (if you trust the provider)
* Fill in Idp slug (short name), Entity ID and Metadata source.

Save.

The provider now should appear in http://localhost:81/admin/third_party_auth/samlproviderconfig/. However it may not be enabled. In order to make this work, you may have to get in touch with your SAML provider.

### LTI[edit | edit source]

edX is both an LTI provider and consumer, read Open edX as an LTI Tool Provider.

(1) Edit edx/app/edxapp/lms.env.json

"FEATURES" : {
...
"ENABLE_LTI_PROVIDER": true

(2) Run database migrations as root

cd /opt/edx-eucalyptus.3-0/apps/edx/edx-platform
../bin/python.edxapp ./manage.py lms syncdb --settings aws

You should see at the end something like:

Running migrations:
Rendering model states... DONE
Applying lti_provider.0001_initial... OK
Applying lti_provider.0002_auto_20160325_0407... O

(3) Restart the LMS server

/opt/edx-eucalyptus.3-0/ctlscript.sh

A connector with Moodle does not seem to be working yet (March 2017).

To add an LTI consumer, e.g. Moodle:

* In the LTI Provider section, next to LTI Consumers select Add.
* Add a consumer name, e.g. My_Moodle
* Keep the automatically generated keys.
* Save

To allow students from your Moodle to log into edX:

* Third_Party_Auth section -> Provider Configuration (LTI), select Add (or click on Provider configuration, then add ...)
* Then what ? Moodle does not seem to provide LTI consuming at the systems level...

### Bulk email from courses[edit | edit source]

By default, sending email from courses to its participants is not allowed.

To change this, you can use the administration console: Bulk_Email

* The tool `Bulk_Email › Bulk email flags > Add `: Tick both "enabled" to allow bulk email and "require course email auth" to allow only for specific courses.
* Then allow for specific classes, and set the parameters in `Bulk_Email › Course authorizations `

### Course Talk[edit | edit source]

Course talk is the name of an online service for rating courses.

You can configure a widget that allow users to rater your courses. Read 4.6. Adding the CourseTalk Widget

* In the navigation pane of the admin interface, locate Coursetalk, and then select Course talk widget configurations.

EdX Studio Home page just after installing (Bitnami Eucalyptus 3.0 version, April 2017)

## Using and installing plugins[edit | edit source]

A system administrator can install so-called XBlocks. Each course manager then must enable these for his/her course. This is a difficult operation since (a) the system does not tell what blocks are available and (b) it is difficult to figure out the name of a block.

### XBlocks directory[edit | edit source]

* XBlocks directory

Some of this are already installed in some distributions, e.g. some Bitnami installations claim to have XBlocks pre-installed.

There exist other lists and I have no idea which one could be trusted, e.g.

* List-of-XBlocks
* Appsembler xblock directory

### Listing installed XBlocks[edit | edit source]

In the Gingko version (and prior) we didn't find a way to list installed XBlocks

The easiest way may be to look at the directories, e.g.

ls -la /edx/apps/edx/venvs/edxapp/lib/python2.7/site-packages | grep xblock

However, this only will be of moderate help. EdX documentation is so broken that it cannot even tell the simple name of block that is required to make it work.

Name to use in Studio  | Name  | Repository  | Comments

|
|
|

done  | DoneXBlock  | https://github.com/Stanford-Online/DoneXBlock | OK. The block appears as "Completion"
|  |  |
flow-control  | XBlock flow-control  | https://github.com/eduNEXT/flow-control-xblock | OK installed (not tested)
ratingvideo ?  | Xblock for video rating  | https://github.com/UC3Mx/ratingXBlock | not tested
rate  | RateXBlock  | ?  | OK
poll  | XBlock-Poll  | https://github.com/open-craft/xblock-poll | OK

... good luck.

### Using an installed XBlock[edit | edit source]

Depending on your installation, some XBlocks already may be installed. E.g. the bitname stack already include some blocks. Otherwise, the system administrator has to do this. So far, normal procedure. However, by definition, installed XBlocks cannot be just used, i.e. the course creator has to enable them. This is bloody tedious and also quite difficult for non-technical persons. E.g. there is no way to list installed XBlocks.

To enable the XBlock for the course, do as follows:

* Navigate to the course in Studio.
* Click the "Settings -> Advanced settings" menu.
* Specify the XBlock to use in the "Advanced Module List" area using a comma-separated list. Note that you can find the name of the module in the provider documentation, something that is difficult since most block authors do not seem to do this. So look at the source code (file setup.py towards the end, do not take the name of the XBlock, rather look for something like:

packages=[
'done',

"rate",
"poll",
"done",
"drag-and-drop"

Once some XBlocks are enabled for course you can use these in any unit.

* On the unit page, under Add New Component, select Advanced.
* Your XBlock is listed as one of the types you can add.
* Select the name of your XBlock to add an instance to the unit.
* You can then edit the properties of the instance as needed by selecting the Edit button.

Read also:

* How to enable XBlocks

### Installation of XBlocks with the Bitname stack[edit | edit source]

* Log in to your server console.
* Load the Open edX virtual environment (if you do not, you will regret !)

source /opt/bitnamiXXXX/apps/edx/venvs/edxapp/bin/activate

e.g. if you created our recommended symbolic link, type

source /edx/apps/edx/venvs/edxapp/bin/activate

Then there are two ways to download and install

Old style - download and install

* Download the module.

sudo pip install /path/to/downloaded/xblock/

New style - alternatively, do it in one step

sudo -H pip install git+https://github.com/path_to_the_repository

If this does not work, try:

sudo su
source /edx/apps/edx/venvs/edxapp/bin/activate
pip install .....

Exemple:

pip install git+https://github.com/Stanford-Online/DoneXBlock.git
pip install git+https://github.com/eduNEXT/flow-control-xblock.git

After installing a new blocks, do restart the system

sudo /edx/ctlscript.sh restart

See above for enabling

## Creating a course[edit | edit source]

See: Open edX

## Links[edit | edit source]

### Official documentation[edit | edit source]

The documentation is spread over several places.

* Getting help. Provides a list of online resources.

* Installing, Configuring, and Running the Open edX Platform. As we described above, for testing purposes, it is much easier to start with the Bitnami stack. However, this document still includes important documentation on configuration that one should read.

* Documentation for edx.org and the Open edX Community
* Building and Running an edX Course Instructions for course teams that are creating courses to run on the edx.org website.
* EdX Learner's Guide Help for learners taking a course on edx.org.

* FAQ on github

* Managing OpenEdX Tips and Tricks

* Slack archive (even if you do not believe that knowledge should be conversational ...)

### Bitnami documentation[edit | edit source]

* Bitnami documentation for Open edX. See the menus to the left.