Open edX installation and configuration
Introduction
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.”
See also:
Installation of the Bitnami stack
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.
We got it from here:
We also suggest to read the official documentation of the Bitnami stack
Installation of a test system under Ubuntu 16
Overview
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 software pack in a separate directory including web servers, database servers, several programming languages, etc. The version we tried included:
- Open edX eucalyptus.3 - Apache 2.4.25 - Elasticsearch 0.90.11 - Erlang 17.4 - Java 1.8.0_121 - Memcached 1.4.35 - MongoDB 2.6.12 - Mysql 5.6.35 - Node.js 6.10.0 - Python 2.7.13 - RabbitMQ 3.6.8 - Rails 4.2.8 - Ruby 2.1.10 - RubyGems 1.8.12
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)
| 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 summary for a simple user
Firstly, have a look at this bitnami doc which was not really advertised in the download link at the time of writing ....
Here are the steps:
- Get the
LOCAL INSTALLOpenEx installer from https://bitnami.com/stack/edx - Make the file executable:
chmod a+x bitnami-edx-eucalyptus.3-0-linux-x64-installer.run
- Create an empty directory somewhere
mkdir /path_yours/edx
- Run the installer (and wait for a very long time)
./bitnami-edx-eucalyptus.3-0-linux-x64-installer.run
- In the beginning it will ask your for an admin login, mail and password. It also requires SMTP information (anonymous is not allowed, so need an account). Alternatively you can use a gmail address.
- Important. You won't have to wait for a few minutes, but for a very long time, e.g. about 30 minutes on an older but idle Ubuntu 16 box.
- Launch it once the installer is done. You will get a little console (see picture to the right). This console is fairly useless if you are connected through an terminal. Instead you could run the following:
cd your_installation_directory ./ctlscript.sh status
- This will not mean that you actually can use the server, since you very likely may have a firewall that blocks outside access to your server.
- To test in the terminal if the server is actually working your could just type
wget localhost:8000(adapt the port number).
- Adapt the firewall (of course you also can restrict to a local network)
# show open ports sudo ufw status # add port 8000 (adapt to yours) sudo ufw allow 8000/tcp # Open for the Studio (else you cannot create courses) sudo ufw allow 18010/tcp # add port 8000 to a restricted area sudo ufw allow 8000/tcp from ip_number_here # Reload the firewall sudo ufw reload
Now if you plan to use this as a little production environment
- Open the firewall (see above)
- you should tell your system to launch this script at boot time. E.g. read this.
Bugs (April 27 2017)
- The installation script will run and install under your login. It can not figure out your group name and some configuration files will be wrong. Fix group names in:
properties.ini apps/edx/conf/httpd-cms.conf apps/edx/conf/httpd-lms.conf apps/xqueue/conf/httpd-xqueue.conf
- The start up page will display an empty URL (see above). Somehow, Apache will start despite wrong group names, but then something goes wrong. Fix the group name problem, shut down everything and restart.
- See this for a "Studio's having trouble saving your work" problem that was easy to fix with an Apache configuration detail. Also, see older versions of this wiki page.
- In Eucalyptos versions prior to March 21 2017, Studio will not allow saving an edited block Problem not solved so far. The problem is fixed. Else in an older install eidt /opt/bitnami/apps/edx/conf/httpd-vhosts.conf:
Replace
<VirtualHost *:18010>
Include "/opt/bitnami/apps/edx/conf/httpd-cms.conf"
</VirtualHost>
by:
<VirtualHost *:18010>
AllowEncodedSlashes On
Include "/opt/bitnami/apps/edx/conf/httpd-cms.conf"
</VirtualHost>
installation under root
Since saving a studio edit did not work, I tried reinstalling the whole thing under root. The problem was fixed in a new release, but I keep the root install anyhow. It does seem to be more reliable (processes will run under daemon by default).
sudo su ufw allow 81/tcp ufw allow 443/tcp ufw reload ./bitnami-edx-eucalyptus.3-0-linux-x64-installer.run
// kill temp file from user installation rm -r /tmp/mako_lms
Below is a slightly censored transcript of the installation dialog. I basically used default values.
./bitnami-edx-eucalyptus.3-0-linux-x64-installer.run
X11 connection rejected because of wrong authentication.
----------------------------------------------------------------------------
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-eucalyptus.3-0]:
----------------------------------------------------------------------------
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]: XXXX.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 []: XXXX-tecfa
Password :
Re-enter :
SMTP Host []: XXXX.unige.ch
SMTP Port [587]:
Secure connection
[1] None
[2] SSL
[3] TLS
Please choose an option [3] : 1
----------------------------------------------------------------------------
Setup is now ready to begin installing Open edX powered by Bitnami on your
computer.
Do you want to continue? [Y/n]: y
----------------------------------------------------------------------------
Please wait while Setup installs Open edX powered by Bitnami on your computer.
Installing
0% ______________ 50% ______________ 100%
########################################
Create a shortcut
We suggest creating the following symbolic link:
sudo ln -s /opt/edx-eucalyptus.3-0 /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
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)
Initial Configuration - get the admin console working
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
-XYoption !!
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:8000/admin and enjoy the difficult editing over a remote X connection.
Alternatively, you can access the admin console through the same port as edx studio.
(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
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
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
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
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.
User management
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
The web interface for administrators (http://localhost:81/admin) allows to add users and to make the active.
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.
Alternatively, the following command line script creates a new superuser according some source on the web (verify !!!)
sudo /opt/edx-eucalyptus.3-0/apps/edx/bin/python.edxapp ./manage.edxapp lms manage_user staff staff@example.com --staff --superuser --settings=aws
Administration console for approving course creation
E.g. to find it, go to edx-studio, edit the URL to add admin</admin>. Then either find the course create section or add course_creators/coursecreator/ to the URL.
Restrict emails to certain domains
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_PATTENRS_ALLOWED" : ["^.*@(.*\\.)?unige\\.ch$"]
Course creation rights
By default, any registered user has access to edx-studio and will be allowed to create a course. You should change this, read Controlling Course Creation Rights
There are two options, pick either one, but not both.
Option one: Disable non-staff users from creating courses
- Edit file apps/edx/edx-platform/cms/envs/common.py and add the following
DISABLE_COURSE_CREATION : True to features
FEATURES {
.............
'DISABLE_COURSE_CREATION' : True,
...........................
}
Option two: Create a course creation group. Only members of that group will be allowed to create courses
- Edit file apps/edx/edx-platform/cms/envs/common.py and change
False to True
FEATURES {
'ENABLE_CREATOR_GROUP' : True,
}
In both cases you will have to update the database (we believe, needs to be verified !)
#go to edx installation directory
cd edx
#go to plaform directory
cd apps/edx/edx-platform
# update, (/edx is a symlink to /opt/edx-eucalyptus.3-0)
sudo -u www-data /edx/apps/edx/bin/python.edxapp ./manage.py cms syncdb --migrate --settings aws --migrate –noinput
# Reboot
sudo /edx/ctlscript.sh restart
SSO from other services overview
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
SAML is popular with Universities, read
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
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
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
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.
Creating a course
See: Open edX
Links
Official documentation
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.
- FAQ on github
- Slack archive (even if you do not believe that knowledge should be conversational ...)
Bitnami documentation
- Bitnami documentation for Open edX. See the menus to the left.