Setup

This guide will help you run Malasakit on your local machine. You should have basic knowledge of the git version control system and access to a UNIX-like machine or emulator (for Windows, try Git Bash).

Cloning

To download a copy of Malasakit, navigate to your directory of choice, then run

$ git clone https://github.com/BerkeleyAutomation/malasakit.git

Dependencies

Malasakit is written in the Python and JavaScript programming languages. To run Malasakit, your machine must have a web browser and a Python 2 interpreter (preferably Python 2.7). Python is typically shipped with most UNIX-like systems, including macOS and Linux. You can check your version of Python by running python -V from the command line.

Python Packages

Malasakit also requires additional packages not included in a base Python installation.

Name	Description	Version
django	A "batteries-included" web application framework	1.11.3
django-htmlmin	Django plugin for minifying HTML (reduces page size)	0.10.0
django-settings-export	Makes Django settings available to the templater	1.2.1
twilio	Simplifies interfacing with Twilio's REST API	latest
openpyxl	Library for reading and writing Excel spreadsheets	2.4.7
numpy	Scientific computing library to simplify some analysis	1.12.1
MySQL-python	Python interface for MySQL, a SQL implementation	1.2.5
pylint	Code style evaluator	1.7.1
pylint_django	pylint plugin aware of Django-specific conventions	0.7.2
pyyaml	Library for parsing YAML files	3.12
unicodecsv	Wrapper around Python's default csv library	0.14.1
selenium	Browser automation library (requires ChromeDriver)	3.4.3
decorator	Library for maniulating Python decorators	latest
sphinx	Library for generating HTML documentation from docstrings	latest
sphinxcontrib-napoleon	sphinx extension to support Google-style docstrings	latest

First, install pip, the standard Python package manager. Next, install virtualenv by running:

$ pip install virtualenv

virtualenv is a tool that allows you to simulate isolated Python environments. Since this command installs virtualenv globally, you may need to prepend this command with sudo.

From the top level of the repository, run:

$ virtualenv -p python2 venv

This creates an environment inside the directory malasakit/venv that uses Python 2.

Environments can be "activated" or "deactivated". Once "activated", any packages installed within the virtual environment become available to the Python interpreter. Therefore, any time you work on or run Malasakit, you should activate the virtual environment we just created by running:

$ source venv/bin/activate

You should now see (venv) before your command line prompt. Also, any packages installed or removed at this point through pip does so for the virtual environment in venv.

To install all the packages listed above at once, run:

$ pip install -r requirements.txt

requirements.txt is a plain text file that lists the packages needed and their versions.

To deactivate the virtual environment, use:

$ deactivate

JavaScript Packages

For frontend development, you should install node and npm, which will allow you to install packages written in JavaScript. (You can think of npm as the JavaScript analog of pip for Python.)

Name	Description	Version
less	A compiler for LESS, a CSS preprocessor	2.7.2
watch-lessc	Automatically compile LESS files that have changed on disk	0.0.3
jshint	A JavaScript linter	2.9.5

To install these packages with npm, from the top level of the repository, run:

$ npm install -g

The -g flag tells NPM to install the packages listed in dependencies and devDependencies in package.json globally, so you may need to prepend this command with sudo.

To compile the stylesheets once, navigate to malasakit-v1/malasakit-django/pcari/static/css, then run

$ lessc -x main.less main.min.css

main.min.css is the minified stylesheet each HTML page uses. To automatically compile main.less when you make changes to the file, run

$ watch-lessc -i main.less -o main.min.css

Other Dependencies

Django's translation system relies on GNU's xgettext. xgettext is installed by default on most Linux systems. On macOS, xgettext can be installed through brew.

Data

This repository does not include data generated in production. To set up a local database for development purposes, from the malasakit directory (not the top-level directory), run:

$ python manage.py migrate

After this command, you should now see a db.sqlite3 file in the malasakit directory.

To obtain a populated SQLite file, contact the maintainers.

If you plan to work on the feature phone application, you will also need to populate your database with voice prompts:

$ python manage.py loaddata feature_phone/fixtures/*-instructions.yaml

Running the Application

Once you have run the migration command, run:

$ python manage.py runserver

to bring up a local development server, which will print out helpful debug information. Next, open up a web browser, navigate to localhost:8000. If everything worked, you should see a landing page.