Getting started

Firstly, thank you for your interest in contributing to KA Lite! The project was founded by volunteers dedicated to helping make educational materials more accessible to those in need, and every contribution makes a difference. The instructions below should get you up and running with the code in no time!

Setting up KA Lite for development

First of all, make sure you've forked the main KA Lite repository (sign up and configure a GitHub account first, if needed).

If you would like to learn more about using Git, try this tutorial!

Prerequisites

You'll need git, Python 2.7.x, pip, and Node.js 0.12 or higher installed.

Checking out the Code

• Fork the KA-Lite repo.
• Clone your fork to your local computer. In your console, use one of these commands with $USERNAME replaced by your GitHub username:
• git clone [email protected]:$USERNAME/ka-lite.git (if using SSH, make sure you register your SSH keys on GitHub
• git clone https://github.com/$USERNAME/ka-lite.git (if using HTTPS)
• Run cd ka-lite to change into the newly cloned directory
• Add the upstream remote so you can pull in the most recent changes:
• git remote add upstream [email protected]:learningequality/ka-lite.git
• Run git fetch and then git checkout develop to get you into the latest changes in KA Lite. (See the note below for more about branches)

Install Dependencies

It's generally good practice to use virtualenv for Python development to isolate your project/s and allow you to install different packages, even with different versions.

If you're using virtualenv, create a new virtual environment and activate it now. If not, you may need to use sudo with the pip commands below, which is not recommended.

To install the Python dependencies, make sure you're in the ka-lite directory and run:

pip install -r requirements.txt
pip install -r requirements_dev.txt

KA-Lite uses npm to retrieve client-side javascript dependencies. To install these dependencies, run:

npm install

If you see a few errors here, it's most likely okay.

Setup Installation

Run these commands to initialize the databases:

./bin/kalite manage setup --username=admin --password=pass --noinput
./bin/kalite manage retrievecontentpack download en --minimal
./bin/kalite manage collectstatic
node build.js --debug

Notes:

• Mac OSX users may run into an error message similar to Error: EMFILE, open '/Users/.../package.json'. A workaround is to add ulimit -n 2560 to your ~/.bash_profile file and then re-run node build.js --debug.
• If you get a missing module error, make sure you have the latest npm installed.

Start Server

You should be all set and ready to go! Run ./bin/kalite start --foreground (python.exe bin/kalite start --foreground on Windows), wait for the output to stop scrolling, and then visit 127.0.0.1:8008 in your browser.

There won't be any content (like videos or exercises) until you add a content pack. See instructions below.

To run in development mode, run ./bin/kalite manage runserver --settings=kalite.project.settings.dev. On Windows, you must specify a python interpreter: C:\path\to\your\python.exe bin/kalite manage runserver --settings=kalite.project.settings.dev

In case you want to access your development server from another IP in the network, you need to add an additional argument: bin/kalite manage runserver 0.0.0.0:8008 --settings=kalite.project.settings.dev

Which branch should I work on?

The develop branch is reserved for active development. It's very unstable and may not be usable at any given point in time -- if you encounter an issue running it, please check with the development team to see if it's a known issue before reporting it.

When we get close to releasing a new stable version of KA Lite, we generally fork the develop branch into a new branch (like 0.16.x). If you're working on an issue tagged for example with the 0.16.0 milestone, then you should target changes to the 0.16.x branch. Changes to such branches will later be pulled into develop again. If you're not sure which branch to target, ask the dev team!

Putting some sample user data into KA Lite

To generate sample Learner and Facility data to help you test KA Lite features, run the generaterealdata management command from the command line:

bin/kalite manage generaterealdata

Adding content packs

• If you skipped the step for adding content packs during install, run the following command (beware it can take a while, zip size is over 500Mb):

bin/kalite manage retrievecontentpack download en

• You can alternatively download the zip file from http://pantry.learningequality.org/downloads/ka-lite/0.16/content/contentpacks/en.zip and unpack it locally by running bin/kalite manage retrievecontentpack local en <path to zip>

Getting your changes back into KA Lite

See the guide for opening pull requests.

---

Next steps

• Once you've toyed around with things, check out our [style & structure guide](Coding guidelines and conventions) to understand more about the conventions we use.
• Now that you're up to speed on conventions, you're probably itching to make some contributions! Head over to the GitHub issues page and take a look at the current project priorities. Try filtering by milestone. If you find a bug in your testing, please [submit your own issue](Report Bugs by Creating Issues)!
• Once you've identified an issue and you're ready to start hacking on a solution, read through our instructions for [submitting pull requests](Submitting pull requests) so that you know you can cover all your bases when submitting your fix! You might wanna look at [some common Git commands](Helpful Git Commands) to get you up and running.