How to run

This document assumes you have basic knowledge around development environments and how the operating system can affect them. This is written from the perspective of using Linux.

Environment

For the environment, you will need python 2.7, pip and a database. Database packages are out of scope, but the documentation for Flask and SQLAlchemy both provide substantial help in getting this set up. You will also need node.js, npm, git and bower. You will use node.js to install npm, which can be used to install bower. Once you have bower, see notes below.

Windows will need Microsoft Visual C++ Compiler for Python, available at http://aka.ms/python27 (Thanks to @wastevens).

Frameworks

Willow uses Flask and SQLAlchemy for its base framework. This allows for simplified database interaction, but with complete flexibility with regards to the database design. In addition, Flask allows for extending the functionality of the application without interfering with other functions.

Requirements

In the requirements.txt, you will find the latest list of packages needed by Python to run the application.

Installation

Python

Depending on your operating system, you will need Python, basic build tools (gcc or Visual Studio Express C/C++), and Python's setup_tools. With setup tools:

easy_install pip

This will install the latest version of "pip".

pip install virtualenv

This will install "virtualenv", a python tool for creating virtual python environments. Useful for installing packages for python, without making them clobber whatever your system uses - you can have separate containers so you don't mess up your OS.

Source code

Installing git is out of scope for this, as is the general use of git. You will need an account at www.github.com to submit code to our primary repository, but you are free to fork it and make whatever changes you want to your own version. To retrieve the latest source code for exploration:

git clone git@github.com:undergroundtheater/willow.git -b develop

if that fails because of no SSH library, you can try this:

git clone https://github.com/undergroundtheater/willow.git -b develop

These commands will copy down the entire source tree and change history to a folder named "willow" in the same location you're in when you run the command - your "working directory". It will also check out a specific branch, the develop branch, which is our main place to do dirty work.

If you want to contribute code, please fork the project on GitHub, and submit pull-requests as needed. If you need help with this, please reach out to willow@undergroundtheater.org.

Create Virtual Environment

virtualenv will create a full copy of your python installation and virtualize it so you can use it to test this application and separate specific packages it needs from your primary installation.

Still in your working directory mentioned above, you will want to run:

virtualenv willowenv

This will create an additional folder in your working directory, called "willowenv". Note that this will not work as easily for Windows users, but the Virtualenv documentation can help significantly more than this document.

Your structure should now be:

working_folder\
    willow\
       ...
    willowenv\
       ...

Pip Install

First, you'll want to be in your virtual environment - run the following from your working directory:

source willowenv\bin\activate

This will create environment variables in linux that point your current shell to use this copy of python.

Once you have your virtual environment running, change into the source folder and run:

pip install -r requirements.txt

• Note from Drew: The current release of py-bcrypt (0.4) DOES NOT compile for windows. In order to resolve the issue, I had to download the repository locally, and edit the pybc_blf.h file, adding stdlib.h to the other includes (as per comments at https://code.google.com/p/py-bcrypt/issues/detail?id=15)

This may take a few minutes, and will fail for certain if you do not have a binary compiler on your system. Windows users beware.

Bower Components

For bower / node components, you can take a look at the bowerrc / bower.json file for hints, or just:

bower install from within the virtual environment and application root (see above).

Running the Application

Once you've got all the packages installed and are in the active virtual environment, you still need to create a settings.py in the willow/ sub-directory within the app. Find settings_dist.py and copy it to settings.py in the same location. Edit and make sure the SECRET fields all have some random stuff in it, and you'll be okay. Email needs flask-Mail configuration to work, so be advised you may have to manually fish out confirmation email codes to confirm your account.

To start up the built-in server with flask:

python run.py

Details

The details on how Flask and SQL-Alchemy work are beyond the scope of this, and can be found with a little bit of Google-fu. Note that plugin tables are created upon first run, but you will still need to manually create the rest of the tables using the Flask shell provided with the application:

python manage.py shell

>>> from willow.models import db
>>> db.create_all()

That will do it!