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. (GitHub's tutorial is a good place to start for learning git, and Git Bash is recommended for Windows users.)

Cloning

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

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

Dependencies

Malasakit is written primarily 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 verify your version of Python by running python -V from the command line.

Python Packages

In addition, Malasakit requires additional packages not included in a base Python installation. These packages include:

• django: a web application framework
• openpyxl: a library for reading and writing Microsoft Excel spreadsheets
• numpy: a numerical computation library
• MySQL-python: a Python interface for MySQL, a SQL database implementation
• pylint: a code style evaluator
• pylint_django: a pylint plugin that is aware of Django-specific conventions
• pyyaml: a library for parsing YAML files
• django-htmlmin: a Django plugin that minifies a rendered template's HTML before serving the page (reduces the amount of data that needs to be sent to the client)
• unicodecsv: a wrapper around Python's default csv package that supports Unicode strings
• selenium: the Selenium WebDriver, bindings to automate browser interactions in Python for integration testing (requires the ChromeDriver binary)

The easiest way to install these packages is to use pip, a Python package manager, by running

$ pip install -r requirements.txt

from the top level of the repository. This will install the packages listed in the requirements.txt file globally, which typically requires superuser privileges (that is, sudo).

Using a Virtual Environment

Alternatively, you may only want to install packages locally for this particular project. The virtualenv tool, which can be installed with

$ pip install virtualenv

lets you do this by simulating an isolated Python environment. Note that this command installs virtualenv globally, so you may need to prepend this command with sudo. To use virtualenv, from the top level of the repository, run

$ virtualenv -p python2 venv

This creates a new directory in the top level called venv that simulates a clean Python installation. (You may notice the -p python2 flag, which avoids issues where virtualenv mistakenly uses python3.) Next, run

$ source venv/bin/activate

to enable the virtual environment. You should now see (venv) before your command line prompt. To install the dependencies locally, run the pip command given like you would for a global installation (see above). To leave the virtual environment, use

$ deactivate

Note that the packages you installed are only available to you when the virtual environment is active. Therefore, you should activate the virtual environment prior to working on the project. You can also set up a virtual environment with Anaconda.

JavaScript Packages

For front-end 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.)

The packages Malasakit uses are:

• less: a compiler for LESS, a CSS preprocessor that allows for greater abstraction
• watch-lessc: an application that watches your LESS files for changes, then automatically compiles them with lessc

To install these packages with npm, run

$ npm install <package-name> -g

where <package-name> is the name of the package you are trying to install. The -g flag tells NPM to install the package 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 template 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-django directory, run

$ python manage.py migrate

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

To obtain a populated SQLite file, contact the maintainers.

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.