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!

Before proceeding, make sure you register your SSH keys on GitHub.

There are a couple of ways to put a local copy of your fork into your local machine for development

Manually setting up KA Lite

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

0. Make sure you have git and python available in your system. Installation varies by distribution. Consult Google for that.
1. Fork learningequality/ka-lite
2. In your console, type in git clone [email protected]:$USERNAME/ka-lite.git where $USERNAME is your github username.
3. Once the cloning is done, run cd ka-lite.
4. Add the upstream remote so you can pull in the most recent changes: git remote add upstream [email protected]:learningequality/ka-lite.git
5. Run git checkout develop to get you into the latest changes in KA Lite.
6. To ensure you have the required packages:
   • install pip if you don't have it already.
   • Install the dependencies listed in requirements.txt: pip install -r requirements.txt and pip install -r requirements_dev.txt
   • install node if you don't have it already.
   • Install the dependencies listed in packages.json: npm install
7. Run bin/kalite manage init_content_items. If this errors out with Too many SQL Variables error, then run this instead: bin/kalite manage init_content_items --overwrite --no-bulk-create. (for Mac users, make sure to use the --no-bulk-create flag)
8. Run bin/kalite manage setup --username=admin --password=pass --noinput
9. Run node build.js --debug.
   • Mac OSX users may run into an error message similar to the following:
     Error: EMFILE, open '/Users/.../package.json'.
     A current workaround is to add this line of code to your ~/.bash_profile file:
     ulimit -n 2560
     Then, re-run the command node build.js --debug.

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

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

Virtualbox installation procedure (currently broken)

0. Install Virtualbox.
1. Install Vagrant.
2. Fork and then clone your fork of the KA Lite repo.
3. Open your terminal, cd into your copy of the KA Lite repo into your local machine.
4. Fetch the latest version of KA Lite by running git checkout develop.
5. Run vagrant up in your terminal.

That should set up your computer with a virtual machine that's ready to run KA Lite. Once the command finishes running, enter vagrant ssh in the terminal and you should be able to get a terminal into the VM. Once inside the VM's environment you can cd into the ka-lite directory to get to ka-lite from inside the VM.

5. To set up the server for development, run bin/kalite manage setup while in the VM's terminal.
6. When your VM is ready, run the bin/kalite manage kaserve command.

Remember that whenever you want to start KA Lite development, enter the ka-lite directory and run vagrant up. Once the VM is up, enter the VM's environment by entering vagrant ssh into the terminal. To exit the environment, press Ctrl+D. To shut down the VM and free up your resources, enter vagrant halt.

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 assessment items (exercises)

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

./manage.py unpack_assessment_zip -f https://learningequality.org/downloads/ka-lite/0.14/content/assessment.zip

• You can alternatively download the zip file from https://learningequality.org/downloads/ka-lite/0.14/content/assessment.zip and unpack it locally

Getting your changes back into KA Lite

See the guide for opening pull requests.