.. _install:

==================
Installing Figures
==================

This document describes how to install and configure Figures to run in Open edX.

------------
Requirements
------------

* Python (2.7)
* Django (1.8)
* Open edX (Ginkgo)

Currently, Figures runs on Open edX Ginkgo. A backport to Ficus is in progress and we'll support Hawthorn soon.

--------
Devstack
--------

Please see the :ref:`devstack <devstack>` documentation for instructions on how to install and configure Figures for devstack.

-------------------------
Production (cloud server)
-------------------------

This section describes how to install Figures on Open edX "Ginkgo". This is the `open-release/ginkgo.master` branch of edX's `edx-platform <https://github.com/edx/edx-platform/tree/open-release/ginkgo.master>`_ LMS.

This can be a production server, staging, or close based development server. For purposes of the instructions here, we will assume the target is a production environment.

Overview
========

We're going to describe *what* needs to happen to get Figures installed, along with instructions on how to perform each step manually. 

These steps are required to install and configures Figures:

* Add Figures to the edxapp Python packages
* Add Figures to the installed apps in the LMS settings
* Add Figures to the LMS settings
* Add Figures to the LMS URL patterns
* Run migrations to include Figures models
* Restart the LMS 

**You will need shell access and ability to sudo as the edxapp user for the Open edX instance on which you are installing Figures.**

*At this time, the CMS settings do not need to be modified.*

The following goes into detail for each step.

Steps
=====


Add Figures to the edxapp Python packages
-----------------------------------------

Figures needs to be added to the edxapp Python virtualenv packages.

Step 1
~~~~~~

Shell to the server hosting Open edX

Step 2 
~~~~~~

Run ``sudo su edxapp -s /bin/bash`` to switch to the edxapp user

Step 3 
~~~~~~

Verify you are using the ``edxapp`` user's virtualenv. Run ``which pip`` to check if the Python virtualenv is enabled. you should see:

::

	/edx/app/edxapp/venvs/edxapp/bin/pip

If you don't, then run ``source ~./edxapp_env`` and check again to verify

Step 4 
~~~~~~

Run ``pip install figures`` to install Figures from PyPI.

Alternate Steps
^^^^^^^^^^^^^^^

Alternately you can install Figures from source by doing the following:

Step 1
~~~~~~

Follow steps 1-3 above first

Step 2
~~~~~~

Install from Github in edit mode:

::

	pip install -e git+https://github.com/appsembler/figures.git#egg=figures

You may want to do this if you want to run from master. This is not recommended for production environments.


Add Figures to the installed apps in the LMS settings
-----------------------------------------------------

Figures needs to be in the ``INSTALLED_APPS`` list in the LMS settings. For those familiar with Django, this is no different than any Django reusable app.

There are differnt ways to do this. Two ways are:

* Add Figures to the ``lms.env.json`` file
* Add to the LMS settings files (in the ``lms/envs/`` directory)

Open edX lets you add Django reusable apps via the ``lms.env.json`` file. This is the preferred approach as it reduces customization of ``edx-platform``

Add the following as a top level key to ``/edx/app/edxapp/lms.env.json``:

::

    "ADDL_INSTALLED_APPS": [
        "figures"
    ],

If ``ADDL_INSTALLED_APPS`` already exists, then just add ``"figures"`` to the list.

The other option is to add ``figuress`` directly to the ``INSTALLED_APPS`` list in the LMS settings file, ``lms/envs/common.py``


Add Figures to the LMS settings
-------------------------------

Figures needs to be found by Django Webpack Loader in order to serve its UI. It also needs to be registered with the Celerybeat scheduler in order to run the ETL pipeline on a schedule.

Figures can do this automatically if its settings are loaded when the LMS starts up by having ``figures.settings`` be imported in the LMS settings.

At the bottom of the ``lms/envs/aws.py`` file, add the following:

::

	if 'figures' in INSTALLED_APPS:
		import figures.settings

**IMPORTANT**: Make sure that you do the above import *AFTER* ``WEBPACK_LOADER`` and ``CELERYBEAT_SCHEDULE`` have been declared in the LMS envs.

If you have implemented your own wrapper around ``lms/envs/aws.py`` you can add the above to that file instead. For example, Appsembler has ``aws_appsembler.py`` and ``devstack_appsembler.py`` for cloud deployments and devstack environments respectively.


Add Figures to the LMS URLconf
------------------------------

To access the Figures UI, the LMS needs to have its `URLconf <https://docs.djangoproject.com/en/1.8/topics/http/urls/>`_ updated to include Figures.

At the bottom of the ``lms/urls.py`` file, add the following:

::

	if 'figures' in settings.INSTALLED_APPS:
		urlpatterns += (
			url(r'^figures/',
			    include('figures.urls', namespace='figures')),
		)	


Run migrations to include Figures models
----------------------------------------

Figures contains its own models which are used for storing metrics data. Because of this, you need to create database tables for Figures models.

As the ``edxapp`` user, run the following:

::

	./manage.py lms migrate figures


Restart the LMS 
---------------

Since Figures needs to add entries to the ``WEBPACK_LOADER`` and ``CELERYBEAT_SCHEDULE`` settings vars, you need to restart the LMS Django app server.

*NOTE:* You do **NOT** have to restart Nginx or the host.

Exit the ``edxapp`` user to go back to the admin shell.

Run the following:

::

	sudo /edx/bin/supervisorctl restart edxapp:lms

Although it shouldn't be necessary, you can restart both the LMS and CMS by running:

::

	sudo /edx/bin/supervisorctl restart edxapp:


------------------------------------
Installing Figures in Open edX Forks
------------------------------------

Please see the :ref:`Appsembler <appsembler_install>` installation instructions for instructions specific to Appsembler's fork of edx-platform.

* TODO: Add instructions for community members to add instructions for their own ``edx-platform`` forks
