installation.rst

Installation

To install the NAU Open edX extensions plugin in an Open edX instance you need to do the following steps:

• Use pip to install the plugin into the same virtualenv that has all the dependencies for edxapp (edx-platform).
• Run the database migrations if required.
• Configure the plugin as required.

We will go into detail on how to achieve this for the two more common ways of running Open edX.

Docker Devstack

The devstack install based on docker is a very popular way of launching a development environment of the Open edX services. If you are running this environment then follow this steps.

1. First step is to get the code and install it.

   In the directory where you created your devstack you also have now a src directory. You can download the code there.

   cd src
   sudo mkdir edxapp
   sudo chown $USER edxapp/
   cd edxapp
   git clone https://github.com/fccn/nau-openedx-extensions.git
   git checkout nau/lilac.master

   Now we need to install it in the virtualenv.

   cd ../../devstack
   docker exec edx.devstack-nau-lilac.master.lms bash -c 'source /edx/app/edxapp/edxapp_env && cd /edx/src/edxapp/nau-openedx-extensions && pip install -e .'
   make lms-restart

   Or more interactively if you prefer

   Note

   If you already ran the previous instructions you can skip ahead to the next step.

   cd ../../devstack
   make lms-shell
   cd /edx/src/edxapp/nau-openedx-extensions/
   pip install -e .
   exit
   make lms-restart

   Note

   We are running the installation in editable mode (-e). When developing or testing, if you make any changes to the code, the server should restart automatically. This will happen if you checkout different tags or branches of the code as well. To see the server restart in action you can see the logs using

   docker logs edx.devstack.lms -f

   You can also restart the server manually with

   make lms-restart

2. Run the database migrations

   To run the database migration in the devstack environment

   make lms-update-db

   You should see this on your console.

   Running migrations:
     Applying nau_openedx_extensions.0001_initial... OK

   Note

   The database is shared between lms and studio so you only need to migrate once for both applications.

3. Configure the plugin to work with edxapp(edx-platform) at lms.yml

   Let edx-platform work with a custom form.

   Open a shell on the lms.

   Edit the lms.yml file.

   Add this line. .. code-block:: yaml

   ... REGISTRATION_EXTENSION_FORM: nau_openedx_extensions.custom_registration_form.forms.NauUserExtendedForm ...

4. For every course requiring extra certificate context, use the advanced studio settings Certificate Web/HTML View Overrides as follows:

   {
       "nau_certs_settings": {
           "calculate_grades_context": true,
           "interpolated_strings": {
               "completion_statement": "This acknowledges that {cc_first_name} {cc_last_name} has succesfully completed the course"
           }
       }
   }

   

   Note

   Since grades calculation could take a while, you could configure the plugin to avoid such process using "calculate_grades_context": false.

5. Or replace the default variable accomplishment_copy_course_description with a new interpolated that formats the grade has percentage without any decimal cases.

Native Installation

The native environment is regarded as a base ubuntu 16.04 server where the ansible playbooks from the configuration repository where run.

Using ansible

If you use ansible to create or update your instance of the Open edX project, then most likely you have a serve-vars.yml directory or you have some form of secure data repository.

To install the SEB Open edX plugin in there you need to change some ansible variables and re-run your installation playbooks.

EDXAPP_PRIVATE_REQUIREMENTS:
  # NAU plugin
  - name: 'git+ssh://[email protected]/fccn/[email protected]#egg=nau_openedx_extensions==1.0.3'

EDXAPP_ENV_EXTRA:
  REGISTRATION_EXTENSION_FORM: "nau_openedx_extensions.custom_registration_form.forms.NauUserExtendedForm"

Some site operators prefer not to run database migration during the playbook runs. If this is you, then please run the migrations manually.

/edx/bin/edxapp-migrate-lms

Installing manually

To run the installation without the help of any script you still need to run the same basic steps.

1. Install the code

   sudo su edxapp -s /bin/bash
   /edx/bin/pip.edxapp install git+ssh://[email protected]/fccn/[email protected]#egg=nau_openedx_extensions==1.0.3

2. Restart the services

   /edx/bin/supervisorctl restart all

3. Run the database migrations

   /edx/bin/edxapp-migrate-lms