Installation¶

Within the gateway4labs project, two main components need to be installed:

The LabManager, which is the software system
The LMS plug-in (only if a LMS that does not support LTI is installed)

Cardinality:

There should be a LabManager representing each university or secondary school.
While uncommon, there could be more than one LMS for each LabManager
Each LabManager will support more than one RLMS
Each RLMS must be prepared to support more than one LabManager

LabManager installation¶

The LabManager has been implemented in Python, so the first dependency to be installed is Python itself. In OS X and Linux, you usually have it already installed. In Windows, you should go to the Python website and download the latest 2.x version (e.g. 2.7).

The LabManager also uses the Flask microframework, and sqlalchemy to wrap the database, being able to use multiple systems but we have only tested MySQL and sqlite. If you want to use MySQL, you’ll have to install it (in Windows, you may download it from the MySQL website or use the XAMPP package, which also comes with Apache; in Linux systems you can install it using your package manager -e.g. sudo apt-get install mysql-server -).

So at this point, the following software packages are assumed:

Python 2.x (do not use Python 3.x; it is not yet supported)
MySQL (unless you prefer using sqlite)

In order to deploy it, some Python packaging notions are required, explained in the first section. Then, the deployment itself is detailed for Microsoft Windows and Linux systems. Finally, notes on the development are described.

Notes on pip and virtualenv¶

Python open source packages are usually uploaded to PyPI (commonly refered to as the cheese shop), and tools such as easy_install and pip make it easy to query, search and install those packages. During this document we’ll use pip, which is indeed a replacement for easy_install.

In order to install pip, we’ll use our distribution package manager in Linux systems. For instance, in Ubuntu we can simply run:

$ sudo apt-get install python-pip

On Windows systems, the process is slightly longer since we have to install first setuptools. So download the distribute_setup.py file and run it, and then place the Python installation Script directory to the PATH environment variable. So append the following to the PATH variable:

;C:\Python27\Scripts

Once setuptools is installed, type the following on CMD:

easy_install pip

From this point, you’ll have pip running in your Windows system.

When installing Python packages, by default they are all installed in a system-wide location. However, for different projects we might be interested in installing different versions of the same libraries. In order to avoid conflicts, and manage the installed libraries in an easy way, the virtualenv project was created.

With virtualenv, it is possible to create a virtual environment in a directory, where one can install a certain set of packages with particular versions. All those versions are managed in that particular directory, so you can later delete it, upgrade only that one, and especially, create other environments for other applications.

Warning

In some scenarios, using virtualenv causes certain problems (when trying to instantiate a virtual environment fails, etc.). While using virtualenvs is highly recommended, it is still optional, so if you’re running into problems and you can’t advance, you can go ahead and install the libraries in your system directly without any virtualenv.

The way to use it is very simple. First you need to install virtualenv, using pip:

$ pip install virtualenv

Or using your package manager in Linux systems:

$ sudo apt-get install python-virtualenv

And then, you can create an environment by running:

$ virtualenv --no-site-packages env1
New python executable in env1/bin/python
Installing distribute........done.
Installing pip...............done.

At this point, the environment has been created, but it is not yet being used. In order to start using this environment, we have to do the following on Linux and OS X:

$ . env1/bin/activate

Or the following on Windows:

> env1\scripts\activate

From this point, you’ll see that in the prompt of your shell there is an indicator such as (env1). At this point, we will be working with that environment. So if we install Flask:

$ pip install Flask

It will be installed in that isolated virtual environment. We can test it by running Python and checking that Flask is actually installed:

$ python
Python 2.7.2+ (default, Oct  4 2011, 20:06:09)
[GCC 4.6.1] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import flask
>>>

If we go out of the Python shell (Ctrl + D / Ctrl + Z), and we deactivate the environment:

$ deactivate

Or we simply open a new terminal, then we’ll see that we are not using that environment anymore:

$ python
Python 2.7.2+ (default, Oct  4 2011, 20:06:09)
[GCC 4.6.1] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import flask
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: No module named flask
>>>

To start using it again, we only have to call or import the activate script again.

Notes on WSGI¶

WSGI stands for Web Server Gateway Interface, which is an interface that different Python web application providers will use and they can automatically be integrated in other web servers. For instance, there is a WSGI module for Apache or for nginx, so any application developed in a WSGI-compliant framework (such as Flask) can be deployed in those web servers. There is plenty of information and links about the support in the WSGI official site.

Lms4labs has been developed using Flask, which is WSGI-compliant microframework. Therefore, a WSGI-compliant server is required. There are two approaches:

Use Apache, nginx, IIS or any other well known web server. There is plenty of documentation on how to deploy Flask applications on those environments in the Flask documentation.

Use a Python WSGI-compliant web server such as cherrypy. The advantage of this is that it does not require you to deploy any additional plug-ins to the web server you are already using, and then you can use that server directly or the proxy module of the web server to manage the connections. This approach might be slower, but it is useful to test the system and even to use it in production with a small number of students.

This document covers both approaches, but it is important to understand the benefits and drawbacks of each one.

Deploying Lms4labs¶

In this section, it is assumed that you already have installed pip and virtualenv, and that you have notions of how you want to deploy the Lms4labs application.

First of all, download the source code of the gateway4labs project and go to the labmanager code:

$ git clone https://github.com/gateway4labs/labmanager/
$ cd labmanager

Then, create an environment called env in the same directory where the labmanager is installed, and activate it:

$ virtualenv --no-site-packages env
$ . env/bin/activate
(or, on Windows)
$ . env\scripts\activate

Install all the requirements. They are detailed requirements.txt file, so you can install them all by running:

$ pip install -r requirements.txt

Warning

In Microsoft Windows, some libraries are not installed automatically unless you have installed a proper development environment. If you’re running Microsoft Windows, you need to download and install manually (if you’ve installed Python 2.7 for 32 bits, you’ll need to install the file that is called whatever-win32-python2.7.exe or so):

lxml

PyCrypto

PyYAML

Once installed, then run the command:

C:\...\> pip install -r requirements.txt

At this point, everything is ready to be deployed. First, we should add the configuration file. A sample one is distributed, so you can copy it:

$ cp config.py.dist config.py

And modify it so as to fit your local data. If the engine is sqlite, you don’t need to worry about the connection DB configuration (username, password, hostname, etc.). If you are using MySQL, you don’t need to create the user and the database by your own, since that is managed by the deployment script itself. Just check that you’re fine with the credentials you’re going to establish in the config.py file. Then you can create the database by running:

$ python deploy.py -cdu

Finally, you can test it by running:

$ python run.py

If you open http://localhost:5000/ with your web browser, you should see the system up and running in development mode. You’ll be able to use the username admin and the password password.

Development¶

The development mode is a Flask mode used during the application development. By running:

$ python run.py

You are using that mode. It is a risky mode since users might be able to execute random code in the server, so use it only while developing or testing a particular condition.

While using the development mode, the application will be automatically reloaded every time you modify any code file, and if an exception is raised, you’ll be able to see the complete trace and even evaluate conditions through the web browser by writing Python code in any stack level. To see further information, please refer to the official flask documentation.

Production¶

In order to run the system in production, there are two ways, as previously detailed. The easiest mode is to rely on a Python web server such as cherrypy. A very simple example is provided in the run_cherry.py script, which basically does the following:

from cherrypy import wsgiserver
from labmanager import app

PORT = 8080
server = wsgiserver.CherryPyWSGIServer(('0.0.0.0', PORT), app)
server.start()

This code is enough for deploying a threaded HTTP server. So as to run it, you must run:

$ python run_cherry.py

If you want to work with this server behind an Apache server, you can still use the Apache mod_proxy module, which comes by default with Apache. Refer to the Apache documentation for details, but this is an example of configuration (once the module has been enabled):

ProxyVia On
ProxyPass        /gateway4labs http://localhost:8080/gateway4labs
ProxyPassReverse /gateway4labs http://localhost:8080/gateway4labs

The other approach is using WSGI in the web server. Refer to the Flask documentation on how to deploy it. In the particular case of Apache, the documentation on how WSGI works on Apache is also very good.

As a summary for the deployment on Apache: first, download mod_wsgi. In Linux systems, it may be available in the package repositories (e.g. in Ubuntu, you may install the libapache2-mod-wsgi package). In Windows, the process is documented here. Once mod_wsgi is installed in Apache, the following configuration may work:

WSGIDaemonProcess labmanager user=weblab group=weblab threads=5 python-path=/PATH/TO/ENV/lib/pythonVERSION/site-packages/
WSGIScriptAlias /labmanager /PATH/TO/labmanager/run_wsgi.wsgi
WSGIRestrictStdout Off
WSGIPassAuthorization On

<Directory /PATH/TO/labmanager/>
    WSGIProcessGroup labmanager
    WSGIApplicationGroup %{GLOBAL}
    Order deny,allow
    Allow from all
</Directory>

Being /PATH/TO/labmanager/ the labmanager root project. Additionally, you will need to modify the run_wsgi.wsgi script to change the project directory.

Table Of Contents

This Page