Getting started with QuizApp

Quickstart

Cloning the repository

The first step is to clone the repository onto your disk.

git clone --branch=master git@github.com:PlasmaSheep/quizApp.git

This will check out the most recent stable version of QuizApp. If you like to live dangerously and want the bleeding edge version, replace master with develop.

Installing python dependencies

It is best practice to install python dependencies using a virtual environment. This means that the packages that QuizApp installs are independent from any packages you already have installed, which reduces any possible compatibility nightmares.

Before continuing, you should follow the installation instructions for virtualenvwrapper.

Now that you’ve done that, create a virtual environment for QuizApp.

mkvirtualenv quizApp

Now, in the QuizApp directory, run:

pip install -r requirements.txt

This will install all requirements necessary for QuizApp to run.

Setting up the database

Lastly, you need to set up the database. QuizApp uses MariaDB. If you use MySQL instead of MariaDB, QuizApp should still work normally. If you have neither, you should install MariaDB.

Once you have MariaDB installed and running, you need to set up the database:

./manage.py create-db

You will be prompted for your MySQL root password. This will create a database called quizapp and a user named quizapp.

If you would like to have a different username/password combo, edit quizApp/config.py, find the configuration you wish to modify (e.g. development, production) and modify the variables to your new values. You will then have to re-run create-db. Note that your information is not secure if you do not modify the database username and password.

Note

manage.py can handle creation and population of multiple database configurations. If you are running a development sever, the above command is sufficient. This is because manage.py defaults to the development configuration.

If you want to set up a production server, you must specify the --config option:

./mange.py --config production create-db

Keep this in mind when you see other commands using manage.py.

Creating a user

You will need to create a user to work with QuizApp. Full details are available on Managing users, but your command should look something like this:

./manage.py create-user --username experimenter --password password --role experimenter

Running QuizApp

This is essentally all you have to do to install QuizApp. To run QuizApp using the default Flask webserver, simply run:

./manage.py run

However, it is not recommended to use this server for production environments. See Production servers for instructions on running QuizApp in a production environment.

Configuration and security

If you are running quizApp in a production environment, you are definitely going to want to modify the password of the QuizApp database user for extra security. You are maybe going to want to modify the database name or username that QuizApp uses.

In any case, the easiest method to change the database setup is by modifying quizApp/config.py. There are 3 main environments that QuizApp recognizes - testing, development, and production. You are probably most interested in modifying production settings - however note that the Production class does not contain any database particulars. This is because database information for production is stored using instance configuration.

In QuizApp, the instance folder is called instance. There is a file there called instance_config.py.ex. If you wish to override any of the default production database settings, you should copy this file to instance/instance_config.py.

In that file, there are four options. The first option is the database URI. The full reference for the URI syntax is located here.

The second is the secret key. This is used for various cryptographic purposes and needs to be randomly generated. Refer to the flask documentation for instructions on generating secret keys.

Repeat the process above for the third option, SECURITY_PASSWORD_SALT.

The fourth option represents what email address QuizApp will use to send emails such as registration confirmation, password recovery, etc.

In addition, if you plan to use QuizApp with Amazon Mechanical Turk, you will need to move instance/mturk.yaml.ex to instance/mturk.yaml and update the AWS access key ID and secret key for your mechanical turk user. Remember to follow best practices and use IAM for this.

Production servers

There are many ways to run QuizApp in a server. However, QuizApp is merely a platform and does not include a web server.

One popular way to run a server is via gunicorn and nginx. Here is a good tutorial for setting up that configuration.

QuizApp already includes a wsgi file for use with gunicorn, located at wsgi.py.