KA Lite Documentation

by Learning Equality

Welcome to the KA Lite Documentation page! Here, you will find all the information needed to set up the KA Lite software. Additionally, there’s information on how to manage KA Lite and how to perform role-specific tasks. If you have any questions that are not addressed by the documentation and you have access to the Internet, please be sure to check our Forums!

Main sections

KA Lite Installation Guides

Installers for a number of platforms are available, each with separate installation steps. Click ahead for installation instructions, and if you’re updating be sure to check out our release notes.

Windows

Installation

1. Download the KA Lite Windows installer v. 0.17.5.
2. Double-click the downloaded .exe file, and the wizard window will appear to guide you through the process of installing KA Lite on your server.

Upgrade

Upgrading KA Lite in Windows over an existing installation is easy – just run the installer and follow the prompts! You don’t need to uninstall your old KA Lite installation first. You can follow the prompts to either keep your existing data or delete old data and start over. See the release notes for critical upgrade information for specific versions.

When you start the KA Lite program, you will find a leaf icon in your task tray. Right click on this icon to start/stop the server, open the application in a browser, or set other options:

By default, you can access KA Lite on the installation computer from the address http://127.0.0.1:8008. To access KA Lite from other machines, you will need to connect to the same network as the installation computer and access port 8008 using the its IP address. For example, if the installation computer has the IP address 192.168.0.104 on your network then you can access it from other machines on the same network at the address http://192.168.0.104:8008.

For more advanced use of KA Lite, such as changing the default port, see Running KA Lite with your own settings or use the command-line kalite program, which in typical installations can be found at the path C:\Python27\Scripts\kalite. Run kalite --help for usage info.

Warning

If you need to download and install contentpacks locally for languages other than English, make sure you are doing it as the same user that installed KA Lite in the first place. If you perform the contentpack installation as a different user, some content will not load properly. For downloading and installing content packs for offline methods and automatic deployments, see How can I install a language pack without a reliable internet connection?.

Mac OS X

Installation

1. Download the KA Lite OSX installer v. 0.17.5.
2. After the download is complete, double click the .pkg file.
3. Click on the Continue button to allow the installer program to check for pre-installation requirements.
4. Follow the prompts in the installer dialog to install KA Lite.
5. The “KA Lite app” will launch automatically during installation, display notifications and a menu bar icon.
6. When the installation finishes, you will be notified that “KA Lite is running…”. The installer will also show the “Summary” page with instructions to start using KA Lite.
7. To start using KA Lite, click on the menu bar icon and select “Open in Browser”.

Upgrade

To upgrade an existing KA Lite installation.

1. Download the KA Lite OSX installer v. 0.17.5.
2. Make sure that you stop the server and quit the KA Lite Monitor.
3. After the download is complete, double click the .pkg file.
4. Click on the Continue button to allow the installer program to check for pre-installation requirements.
5. Follow the prompts in the installer dialog to install KA Lite.
6. The “KA Lite app” will launch automatically during installation, display notifications and a menu bar icon.
7. When the installation finishes, you will be notified that “KA Lite is running…”. The installer will also show the “Summary” page with instructions to start using KA Lite.
8. To start using KA Lite, click on the menu bar icon and select “Open in Browser”.

See the release notes for critical upgrade information for specific versions.

Linux

Ubuntu/Debian .deb

Download the latest .deb installer v. 0.17.5, and run this command:

sudo dpkg -i FILENAME.deb

Warning

Double-clicking the .deb in Ubuntu will open it in Ubuntu Software Center. This will fail on a default installation due to a bug in Ubuntu. To make it work, you need to install libgtk2-perl, for instance by running sudo apt-get install libgtk2-perl. After that, make sure Software Center is closed and double-click the .deb file.

FILENAME should be replaced with the name of the file you downloaded. The file may be named as if it was intended for Ubuntu but works just as well for any other Debian-based systems like Debian, Raspberry Pi, Linux Mint etc.

You will be prompted to enter some configuration information. You should read the on-screen instructions carefully, but some explanation is included here:

1. Choose weather you want to run KA Lite on boot or not. We recommend choosing yes, as it simplifies data management. If you choose not to, you must manually start KA lite every time.

Note

Running KA Lite as different users creates different sets of data files, so it’s recommended that you run KA Lite as the same user every time.

2. If you chose to start on boot in the previous step, you will be prompted to choose the owner for the KA Lite server process. Generally the default value is ok.

3. You will be asked to review your choices, and finally KA Lite will start automatically when installation is complete.

Tip

If you want to receive automatic updates from online sources, you can also use Debian/Ubuntu: Subscribe to updates through a PPA.

Upgrade

To upgrade KA Lite on Linux, simply download the latest deb file and follow the instructions above for installation. Your existing data will be preserved by default. See the release notes for critical upgrade information for specific versions.

Raspberry Pi

For a Raspberry Pi running a Debian system, you can install the special Debian package ka-lite-raspberry-pi (Download as .deb file v. 0.17.5).

To download and install it from command line:

# Install dependencies
sudo apt-get install python-m2crypto python-pkg-resources nginx python-psutil

# Fetch the latest .deb
sudo wget https://learningequality.org/r/deb-pi-installer-0-17 --no-check-certificate --content-disposition

# Install the .deb
sudo dpkg -i ka-lite-raspberry-pi*.deb

You can also add the PPA, see Debian/Ubuntu: Subscribe to updates through a PPA, and then run sudo apt-get install ka-lite-raspberry-pi.

For a more thorough guide, see Raspberry Pi 3 Tutorial.

Other distributions

KA Lite is available for all platforms (e.g. non-Debian compatible platforms) through PyPi. See Generic installation pip install.

Other options

Note

Every time you update kalite, you should (re)run kalite manage setup to ensure that the database and contents are kept updated.

Generic installation pip install

You can install KA Lite from the online Python Package Index (PyPi) using its package system pip.

Note

PyPi sources do not contain content and exercise data, so you need to download the contentpack en.zip manually (>700 MB).

If you are installing system-wide, it’s preferable to use ka-lite-static which has dependencies bundled in and doesn’t interfere with your system’s setup:

sudo pip install ka-lite-static

You can also install KA Lite in a virtual environment or on the current user’s local python packages without dependencies bundled in:

pip install ka-lite

Portable tarballs / zip files with setup.py

If you can’t install KA Lite on systems with the standard Windows/Mac/Linux installers, you can fetch the KA Lite python package from PyPi.

To unpack the package for installation on Linux/Mac, run:

tar -xf ka-lite-static-0.17.5.tar.gz

Once it’s unpacked, install it by entering the extracted directory and running:

cd ka-lite-static-0.17.5
sudo python setup.py install

Debian/Ubuntu: Subscribe to updates through a PPA

We maintain a PPA on Launchpad and if you are connected to the internet, this will also give you automatic updates.

To add the PPA as a repository on an apt-based system, you need to ensure that a few libraries are present, and then add our repository and the public key that packages are signed with:

sudo apt-get install dirmngr
sudo su -c 'echo "deb http://ppa.launchpad.net/learningequality/ka-lite/ubuntu xenial main" > /etc/apt/sources.list.d/ka-lite.list'
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 74F88ADB3194DD81
sudo apt-get update
sudo apt-get install ka-lite  # ...or 'ka-lite-raspberry-pi'

User interface for Linux/GTK

A Control Panel for simple start/stop functionality and a bit of user setup is available with a user interface. It’s not feature-complete, but good enough for simple usage.

Make sure you have the PPA added (see Debian/Ubuntu: Subscribe to updates through a PPA), then run:

sudo apt-get install ka-lite-gtk

On non-Debian systems, you can install the GTK interface with Pip:

sudo pip install ka-lite-gtk  # Install
ka-lite-gtk  # Launch the KA Lite UI

Development

A guide recommending how to install KA Lite for development is available in Getting started.

Specific system setups

Nginx / Apache setup

This section is written for the Django-knowledgable crowd.

KA Lite includes a web server implemented in pure Python for serving the website, capable of handling hundreds of simultaneous users while using very little memory. So you don’t have to run Apache or Nginx for efficiency.

Apache configuration, using mod_wsgi, example would work for an Ubuntu .deb installation:

<VirtualHost *:80>
    ServerName kalite.com
    DocumentRoot /var/www/html/

    <Directory />
        Require all granted
    </Directory>

    Alias /static /var/www/.kalite/httpsrv/static
    Alias /media /var/www/.kalite/httpsrv/media
    Alias /content /var/www/.kalite/content

    WSGIScriptAlias / /usr/lib/python2.7/dist-packages/kalite/project/wsgi.py

    # Possible values include: debug, info, notice, warn, error, crit,
    # alert, emerg.
    LogLevel warn

    ErrorLog ${APACHE_LOG_DIR}/kalite-error.log
    CustomLog ${APACHE_LOG_DIR}/kalite-access.log combined
</VirtualHost>

Note

It’s recommended that you install ka-lite-static in a virtualenv. If you are using Apache+mod_wsgi, you should copy & modify wsgi.py to reflect the path of your venv.

If you are using uwsgi+Nginx, this is the critical part of your uwsgi configuration, provided that you have installed kalite from PyPi or .deb:

module = kalite.project.wsgi

Remember that KA Lite runs in user space and creates data files in that user’s home directory. A normal Debian/Ubuntu system has a www-data user for Apache which is the default user for mod_wsgi and will create database files, static files etc. for kalite in /var/www/.kalite/. If you run it as another user, it may be located somewhere else.

Note

Log in as the Django application server’s user, e.g. www-data and initialize the kalite static files and database before anything you can run kalite with uwsgi / mod_wsgi !

Example of setting up kalite for the www-data user:

sudo su -s /bin/bash www-data
kalite manage setup
exit

Raspberry Pi 3 Tutorial

Raspberry Pi has many versions and the latest one is Pi 3, which this guide is based on. It also works for other editions of The Pi - RPi1, 2, Nano, Zero etc. In order to have complete ka-lite installation one would need a 64GB MicroSD Card (earlier version may need a SD Card) as the reduced size video are currently 34GB in size (see System requirements).

Overview

Installing KA Lite on a Raspberry Pi by using the specialized ka-lite-raspberry-pi package will install a couple of dependencies for Raspbian. One of them is Nginx, a web server.

The main benefit of this setup is that static files are handled by Nginx, meaning all images, javascript files and videos are served by a more efficient application. In older more limited versions of Raspberry Pi, this was critical because of limited hardware.

Step 1: Install Raspbian

First step is to get Raspbian OS installed on Raspberry Pi. There are guides available on their website. Easy way is to format the MicroSD Card as FAT32 and then download NOOBS (https://www.raspberrypi.org/downloads/noobs/) Once downloaded extract and copy it on the MicroSD Card. Pi 3 has a inbuilt WiFi, hence put the Micro SD card and once booted it will ask to connnect to your WiFi. If WiFi isn’t available make sure the ethernet port is connected and internet is accessible. This is required to download the Raspbian OS.

After Raspbian is installed and booted, please upgrade the OS before installing the dependencies:

# Upgrade Raspbian OS
sudo apt-get update
sudo apt-get upgrade

Step 2: Install KA Lite

You will need the customized package ka-lite-raspberry-pi. To get the latest version, see Raspberry Pi.

You can also add the PPA, see Debian/Ubuntu: Subscribe to updates through a PPA, and then run sudo apt-get install ka-lite-raspberry-pi.

Upgrades

To upgrade KA Lite on Linux, simply download the latest deb file and install it on top of the old one (following the same installation instructions). If you use a PPA, you can run apt-get update && apt-get upgrade.

Your existing data will be preserved by default.

See the release notes for critical upgrade information for specific versions.

Configuration during installation or update

Some explanation:

1. Choose weather you want to run KA Lite on boot or not. We recommend choosing yes, as it simplifies data management. If you choose not to, you must manually start KA lite every time.

Note

Running KA Lite as different users creates different sets of data files, so it’s recommended that you run KA Lite as the same user every time.

2. If you chose to start on boot in the previous step, you will be prompted to choose the owner for the KA Lite server process. Generally the default value is ok.

3. You will be asked to review your choices, and finally KA Lite will start automatically when installation is complete.

Tip

If you want to receive automatic updates from online sources, you can also use Debian/Ubuntu: Subscribe to updates through a PPA.

During the setup it will ask to download the English content pack that has all exercises. It is also fundamental to all other language contents, and thus mandatory to run any kind of installation. This file is around 800MB and it will take time to download depending on the internet connection.

Step 3: Usage

You will probably have chosen to start KA Lite automatically, and if that’s the case, it will already be running. Use following command to start/stop KA Lite:

# Starting KA Lite
sudo service ka-lite start
# Stopping KA Lite
sudo service ka-lite stop

After starting KA Lite, point your browser to http://127.0.0.1:8008 and you should see a screen where you can type in your administrator’s password.

Step 4: Downloading the videos

If videos are downloaded in bulk, then they need to be moved to the folder /home/pi/.kalite/content. After copying the files, use the Scan content folder for videos. The tree will turn green for all the videos that are available in the content folder. Time taken for the scan to complete depends on the number of videos in the content folder. For the complete set of downloaded videos (34 GB), it can take more than 2 hours on Raspberry Pi 3. It may take longer for older versions of Raspberry Pi.

Please make sure that all these files once copied, they have permissions to be viewed by everyone (or at least the user account you know is running the KA Lite service, typically the pi user). If correct permissions are not given, videos will not play.

Step 5: Replication to other devices

Here are the basic steps to manually replicate from one KA Lite device to another. We advice you to write your own scripts to automate this process if you are deploying to more than just a couple of devices.

1. Prepare the seed device, your prototype using the above steps. Then:

   1. Download and install all desired videos and content packs.

   2. To remove the data that should NOT be replicated to other devices, run:

      kalite manage clearuserdata
      

      To run the same command as a different user:

      sudo su -l USERNAME -c kalite manage clearuserdata
      

   3. Copy the ~/.kalite folder to a removable device. It’s likely NOT going to save you time to compress it to .zip or .gz.

2. On the target device:

   1. Install KA Lite using the steps above.
   2. Stop kalite: sudo service ka-lite stop
   3. Remove the whole ~/.kalite folder
   4. Copy in the .kalite from your seed device to your target device’s HOME (~/) folder.
   5. Make sure permissions are given to the pi user (or other configured user)
   6. Start kalite: sudo service ka-lite start

After this, the target device should have the same content packs, videos etc. But it will be unregistered. Depending on your deployments internet connectivity, you may want to register it before deploying it.

In any case, you should always manually test a device before deploying it.

System requirements

Operating systems

• Windows Vista, 7, 8, 10
• Mac OSX 10.9, 10.10 and 10.11
• Linux: Any system with Python 2.7
• Debian/Raspberry Pi packages: Wheezy or later
• Ubuntu packages: 14.04, 15.10, 16.04 - anything that’s not end-of-life.

Limited support

The following systems are known to work, but we do not actively ensure their stability and their might be issues.

• Windows XP
• Ubuntu 12.04

Supported Browsers

• IE9+
• Firefox *)
• Chrome
• Safari

KA Lite is currently not supported on Internet Explorer version 8 or lower.

Note

*) Firefox 45+ is the system we run all the automated tests on, and so has the greatest guarantee of working. However, we do not use technology that’s incompatible with other browsers, and so we expect them to work and fix any issues that occur.

Known issues:

• Videos do not play on Windows XP (use the Chrome browser)
• Subtitles do not work for Epiphany (the browser in Raspberry Pi).

Video playback

Videos are MP4 encoded. On Ubuntu/Debian systems, install the Ubuntu restricted extras package.

Videos are not playing?

Presuming that you have videos on your .kalite/content folder from a previous version of KA Lite or from a torrent, make sure you have checked the following common problems:

• Have you pressed “Scan videos” on the Manage->Videos page?
• Did you download videos matching your KA Lite version? New version of KA Lite may ship with different content packs, or you may have downloaded a new one your self.
• Is your video content folder readable for the KA Lite user? The folder has to have the correct permissions. If you copied it using an administrative account, the user running KA Lite may not have access.
• Does your browser play videos? If you can locate the videos on your drive but can’t play them, it’s an indicator that

Real issues:

• Are you seeing javascript errors?

Hardware requirements

Clients

Very old desktops and very low-power computers can be used as client devices to access KA Lite. For instance, some deployments are known to use first-gen Raspberry Pi as desktop computers.

It is always a good idea to do a practical test, but when you want to do a project with KA Lite involved, it’s not necessary to scale your hardware because of KA Lite.

The main concern is that your system needs a video card and driver that can play the videos. Please note that we serve two sets of videos, the individual downloads and the torrent with resized videos – the latter requires the least from hardware.

Servers

KA Lite’s hardware requirements as a server are next to nothing.

• 256 MB
• 500 MHz CPU

• Hard drive space:

  • ~39GB HDD (full set of English resized videos)
  • ~18GB HDD (Spanish)
  • ~15GB HDD (Portuguese/Brazilian)
  • ~10GB HDD (French)
  • ~265GB (full set of English, non-resized videos + partner contents)

If you have a center with less than 30 computers, a device as simple as a Raspberry Pi is known to work fine as a server.

Note

In case you are deploying on Linux and want an efficient setup, use the ka-lite-raspberry-pi package, it doesn’t require a specific architecture, but it’s required to use if you deploy on a system with specs equivalent to or smaller than Raspberry Pi.

Please note that during the very first run or after upgrades or installation of new languages, the server has to scan for videos and update its database. If you have a slower device, this one-time action will require a lot of time.

Getting the videos

Remember that you need a very fast internet connection to get the initial set of videos, and that the application itself including English content databases is ~500MB.

Uninstalling

Windows

1. Uninstall KA Lite from the Control Panel.
2. In Windows XP, double-click the “Add or Remove Programs” icon, then choose KA Lite.
3. In later version of Windows, click the “Programs and Features” icon, then choose KA Lite.

Mac OSX

Uninstallation from user interface

1. Launch KA-Lite from your Applications folder.
2. Click on the app icon at the menu bar.
3. Click on Preferences in the menu option.
4. Click the Uninstall KA Lite from the Preferences tab.
5. A confirmation dialogue will appear, followed by a dialogue asking for your local administrator password. After confirming these steps, KA Lite will be uninstalled.

Uninstallation from command line

1. Open Terminal.
2. Type bash /Applications/KA-Lite/KA-Lite_Uninstall.tool in your Terminal and press Enter.
3. You will be prompted to choose to keep or delete your data folder.
4. Another dialog will appear asking your Password, type your password then click on Ok button.

Linux: Debian/Ubuntu

Option 1: Open up Ubuntu Software Center and locate the KA Lite package. Press Remove.

Option 2: Use apt-get remove <name of package>. You have to know which package you installed, typically this is ka-lite or ka-lite-bundle.

Installed with pip

You can remove KA Lite (when installed from pip or source distribution) with pip uninstall ka-lite or pip uninstall ka-lite-static (static version).

Removing user data

Some data (like videos and language packs) are downloaded into a location that depends on the user running the KA Lite server. Removing that directory can potentially reclaim lots of hard drive space.

On Windows, the HOME and USERPROFILE registry values will be used if set, otherwise the combination %HOMEDRIVE%%HOMEPATH% will be used. You can check these values from the command prompt using the commands echo %HOME%, echo $USERPROFILE%, etc. Within that directory, the data is stored in the .kalite subdirectory. On most versions of Windows, this is C:\Users\YourUsername\.kalite\.

On Linux, OSX, and other Unix-like systems, downloaded videos and database files are in ~/.kalite.

Release Notes

If you are upgrading KA Lite from a previous version, please always take time to read the release notes.

Warning

You should only upgrade one major version at a time. For instance, upgrading from 0.16.x to 0.17.x is fine - but upgrading from 0.15.x to 0.17.x is not guaranteed to work.

0.17.5

Bug fixes

• Slow download using retrievecontentpack on Raspberry Pi #5575
• Customized content packs may fail depending on the Zip program used #5476

Removed

• Removed --foreground flag from retrievecontentpack command, the default behaviour is foreground #5575

0.17.4

Added

• Progress displayed while downloading content packs #5356
• Customizable welcome message setting KALITE_WELCOME_MESSAGE displayed to admin users on first login #5522

Bug fixes

• Video download retry upon connection establishment errors #5528
• Resume download if unplugged connection while downloading #5545
• Blank videos produced when kalite.learningequality.org server down #5538
• Video download jobs hanging indefinitely after pressing “Cancel” #5545
• Also delete content database when deleting a content pack #5545
• Simplified login is now working when there are 1,000 or more users registered in a facility. #5523

Developers

• Do not use npm clean, now requires npm>=5 for building on unclean systems #5519

Known issues

• The English Math topic (top-level) contains a number of misplaced subtopics in the 0.17 series. The problem has propagated from upstream data. The misplacement clutters/obstructs the navigation for students, and it has been a priority to fix this in 0.18, released shortly after 0.17.4. But it’s recommended to upgrade to 0.18 and download new video contents following from the new content pack (~450 videos). See below for tips on how to install a content pack from a different KA Lite release. #5561
• It isn’t possible to cancel video downloads if a video is downloading while the connection is switched off.
• Chrome 55-56 has issues scrolling the menus on touch devices. Upgrading to Chrome 57 fixes this. #5407
• Windows needs at least Python 2.7.11. The Windows installer for KA Lite will install the latest version of Python. If you installed KA Lite in another way, and your Python installation is more than a year old, you probably have to upgrade Python - you can fetch the latest 2.7.12 version here.
• Windows installer tray application option “Run on start” does not work, see learningequality/installers#106 (also contains a work-around)
• Windows + IE9 One-Click device registration is broken. Work-around: Use a different browser or use manual device registration. #5409
• Firefox 47: Subtitles are misaligned in the video player. This is fixed by upgrading Firefox.
• A limited number of exercises with radio buttons have problems displaying #5172

Tip

It is possible to install a 0.16 content pack in a 0.17 release as a work-around. Download a specific content pack and then install it from command-line. Example:

# Download content pack to "en_0.16.zip"
$ wget -r -O en_0.16.zip http://pantry.learningequality.org/downloads/ka-lite/0.16/content/contentpacks/en.zip
# Install "en_0.16.zip"
$ kalite manage retrievecontentpack local en en_0.16.zip

0.17.3

Bug fixes

• Remaining content titles and message IDs in Coach Reports translated #5511 #5509

0.17.2

Warning

New content packs were built for this release (July 2017). Users of non-English content packs should upgrade both the content packs and the videos. For the English content update, there are 396 new videos to be downloaded.

If you are using only English contents, you have the option to stay with previously downloaded content packs, provided that you use an installer that does not bundle the English content pack (Debian/Ubuntu packages or pip).

If you are downloading videos from torrent (see: Downloading Videos in Bulk), you should re-use the target directory of your previously downloaded videos, then only 396 videos need to be downloaded.

Bug fixes

• Severe: Missing translations - all content packs rebuilt #5477
• Do not rely on ifconfig removed in Ubuntu 17.04+ #5455
• Display resource titles on the chosen locale inside the Teach tab #5494
• Broken questions removed upstream (missing radio buttons) #5172

New Features

• Enabled captions by default for English dubbed videos #5464
• About/Diagnose page #5452

Installers

• Windows: Update notification message when starting KA Lite server ka-lite-installers#461
• Windows: Menu item for displaying log ka-lite-installers#457
• Windows: Notification message when port 8008 is occupied ka-lite-installers#454
• Debian/Ubuntu/Raspberry Pi: Support for system.d systemctl enable command ka-lite-installers#450
• Debian/Ubuntu/Raspberry Pi: System command service ka-lite status fixed

Developers

• We now build with Node.js v.6

0.17.1

Bug fixes

• Touch devices: Scroll events drop through to underlying page rather than scrolling long sidebar lists #5407 #5410
• Respect selected date range on tabular coach report #5022
• Correct summary of total exercise attempts on coach reports #5020
• Do not load video into memory to check its size, just use disk stats #2909
• Print server address after kalite start #5441
• Log everything from automatic initialization in kalite start and kalite manage setup #5408
• Remove unused Django package installed in kalite/packages/dist #5419
• Add line breaks in buttons so text isn’t cut #5004

New features

• Log rotation: Logs for 30 days are now stored in ~/.kalite/logs #4890

Installers

• Raspberry Pi Nginx configuration in ka-lite-raspberry-pi served wrong static item path #5430 (also fixed in latest 0.17.0 build, 0.17.0-0ubuntu3)
• Mac/OSX solved 100% CPU usage issue ka-lite-installers#447
• Mac/OSX correctly display KA Lite’s version number ka-lite-installers#448
• Debian/Ubuntu/Raspberry Pi (all packages) correctly adds system.d startup service - solves KA Lite not starting at boot ka-lite-installers#440

Known issues

• Chrome 55-56 has issues scrolling the menus on touch devices. Upgrading to Chrome 57 fixes this. #5407
• Windows needs at least Python 2.7.11. The Windows installer for KA Lite will install the latest version of Python. If you installed KA Lite in another way, and your Python installation is more than a year old, you probably have to upgrade Python - you can fetch the latest 2.7.12 version here.
• Windows installer tray application option “Run on start” does not work, see learningequality/installers#106 (also contains a work-around)
• Windows + IE9 One-Click device registration is broken. Work-around: Use a different browser or use manual device registration. #5409
• Firefox 47: Subtitles are misaligned in the video player. This is fixed by upgrading Firefox.
• A limited number of exercises with radio buttons have problems displaying #5172

Code cleanup

• Remove PROJECT_PATH from kalite.settings.base (it wasn’t a configurable setting). #4104
• Make tests run on Selenium 3.3+ and geckodriver 0.15 (Firefox) #5429
• Fixed an issue in code coverage, added tests for CLI, coverage is now at >61% #5445

0.17.0

Content

Contents have been updated from upstream Khan Academy. We have solved issues regarding contents merged from both Youtube and KhanAcademy.org, meaning that previous inaccuracies in 0.16 content packs are now solved.

• Languages fixed/added in 0.17:

  • Kannada, Malay, Polish, Swahili, Zulu

• Languages updated:

  • Bulgarian, English, Bengali, Danish, German, Spanish (Castilian), French, Hindi, Indonesian, Georgian, Portuguese (Brazil), Portuguese (Portugal), Tamil, Xhosa

• Languages with remaining issues:

  • Arabic, we are still receiving wrong data from upstream APIs that we cannot fix.

• General updates:

  • English subtitles are now available by default for all videos in the English content pack.
  • Many exercises are rearranged and updated, as with javascript libraries. This will solve an unknown number of javascript errors, for instance #5316

Note

After upgrading to version 0.17, you should visit the Manage tab to upgrade your languages and videos. You can also use kalite manage contentpackchecker all --update to automate the download and installation of new content packs.

You should always upgrade the English content pack because it contains exercise data needed by the other content packs. However, most installers bundle the English content pack, so after updating the software, you may find that you only need to upgrade other installed languages.

New features

• New management command clearuserdata, makes it easy to prepare a prototype device for subsequent cloning. #5341
• Patch from Rachel means you can now deep link a page in a specific language, using this URL shortcut: /api/i18n/set_default_language/?lang=es&returnUrl=/learn/khan/math #5342 - (Thanks: Jonathan Field)
• Updates for improved Raspbian Jessie support.

Bug fixes

• Forward admin user to Manage tab after device registration #4622
• The bundled requests library is now version 2.11.1, fixing various download issues #5263
• Reduced memory footprint and added PyPy support by not spawning a new interpreter #3399 #4315
• Upgrades from 0.15 on a Windows system broke video download #5263
• Release .whl format on PyPi, it installs faster, it’s the future. Users will no longer be warned about Wheel incompatibilities when installing from Pip. #5299
• Activating simplified login results in blank login modal #5255
• favicon.ico missing in distributed set of files, little KA green leaf now appears in browser window decorations and shortcuts #5306
• Use current year in footer text #5055
• New setting HIDE_CONTENT_RATING for hiding content rating box #5104
• Redirect to front page if user logs in from the signup page #3926
• Progress bar missing when decimals in progress percentage #5321
• Missing cache invalidation for JavaScript meant client-side breakage: Upgraded CherryPy HTTP server to 3.3.0 #5317
• Error pages now include Traceback information to include for technical support #5405
• Implement friendlier user-facing error messages during unexpected JS failures #5123
• Source distribution and ka-lite + ka-lite-raspberry-pi debian packages no longer ship with English content.db, means they have reduced ~40% in file size #5318
• Installation works with latest setuptools >= 30.0 affecting almost any recent system using pip install. #5352
• Installation works with latest pip 9. #5319
• kalite manage contentpackchecker all --update wrongly retrieved all available content packs. Now only updates installed content packs.
• No content pack files are placed in STATIC_ROOT, ensuring that kalite manage collectstatic will not remove any files from content packs (subtitles!). #5386 #5073
• Online availability incorrectly detected, bypassing registration progress on Video and Language downloads #5401
• The rsa library has been upgraded to 3.4.2 following device registration blockers on Mac and Windows. #5401
• Windows: Logging works again: Writing to server.log was disabled on Windows #5057
• Dev Loading subtitles now works in bin/kalite manage runserver --settings=kalite.project.settings.dev
• Dev Auto-discovery of content-packs in well-known location /usr/share/kalite/preseed/contentpack-<version>.<lang>.zip, example: /usr/share/kalite/preseed/contentpack-0.17.en.zip. Happens during kalite.distributed.management.commands.setup.
• Dev Test runner is now compatible with Selenium 3 and Firefox 50
• Dev Test runner based on empty database instead of 92 MB English content, means tests are >30% faster.
• Dev Circle CI now caches node build output between each test build, reduces test time by 2 minutes.
• Dev Circle CI updated from Ubuntu 12.04 to 14.04 + Python 2.7.11

Known issues

• Windows needs at least Python 2.7.11. The Windows installer for KA Lite will install the latest version of Python. If you installed KA Lite in another way, and your Python installation is more than a year old, you probably have to upgrade Python - you can fetch the latest 2.7.12 version here.
• Windows installer tray application option “Run on start” does not work, see learningequality/installers#106 (also contains a work-around)
• Windows 8 installation on 32bit is reported to take ~1 hour before eventually finishing.
• Windows + IE9 One-Click device registration is broken. Work-around: Use a different browser or use manual device registration. #5409
• Firefox 47 has misaligned subtitles in the video player. This is fixed by upgrading Firefox.

Note

Code and command cleanups listed below are harmless if you installed KA Lite using an installer and only relevant in these cases:

• You run a specialized setup or deployment
• Your deployment is 1½+ years old
• You’re a KA Lite developer

Code cleanup

• (List of removed commands)
• Test coverage is now tracked by Codecov instead of mostly broken Coveralls.io #5301
• Fixed unreliable BDD test #5270
• Cleaned up deprecated settings CONTENT_DATA_PATH and CONTENT_DATA_URL #4813
• kalitectl.py has been removed, instead we invoke kalite.__main__ from bin/kalite.
• All files distributed as “data files” in /usr/share/kalite (or similar location) have been removed. Everything is now distributed as “package data”, meaning that several upgrade issues are fixed moving forwards.
• The parts of kalite.testing application related to benchmarks have been unmaintained and are outdated. Now the application’s sole focus is utilities for CI.
• The whole kalite.basetests application has been removed. It was used to do nonsensical tests of the host system, not actual unit or functional testing.
• Both CONFIG_PACKAGE and local_settings raised an exception, all code pertaining these settings has been removed and settings code is now much more readable #5375
• kalite.updates.management.commands.classes refactored so it doesn’t show up as a command classes (nb: it wasn’t a command!).
• python-packages/fle_utils/build, unused build utility from 2013.
• The manage.py script has been removed from the source tree (use bin/kalite manage <command> instead.)
• When running KA Lite straight from source, we used some very legacy conventions for data locations. But you can achieve the same effect by specifying a non-default locations using the KALITE_HOME environment variable. Example: KALITE_HOME=/path/to/.kalite kalite start.
• PyRun is no longer supported and has been removed (it was lacking multiprocessing).
• Static files are only served by Django’s HTTP server in DEBUG=True mode. It was already handled by Cherrypy in other cases, and WSGI deployments are now required to implement this behavior.
• We no longer release sdists (tar.gz) on PyPi, instead only .whl. #5299
• Unfinished backup commands removed. It’s extremely easy to backup and restore (read: duplicate) a KA Lite setup, see Backing up data: is there any easy way to do it locally?.
• Removed profiling via PROFILE=yes (broken since 0.16)

Debian/Ubuntu installer

• Everything in the debconf regarding assessment items has been removed. This only has an effect if you had automated deployments. Instead of automating deployments and their content through debconf settings, use your own custom .kalite user data directory or invoke kalite manage retrievecontentpack. learningequality/installers#422
• ka-lite-bundle now comes bundled with the English content pack learningequality/installers#422
• No Python files (*.py) are placed in /usr/share/kalite.
• Systemd support introduced, fixes specific bug on unupdated Raspbian Jesse learningequality/installers#422
• Systemd support fixed and released in 0.17.0-0ubuntu2 build learningequality/installers#440

Mac installer

• OSX 10.11 (El Capitan) + MacOS Sierra 10.12 are now supported.
• User friendly warning message when port 8008 is occupied
• Uses PEX instead of PyRun

Windows installer

• Static data is now removed during uninstallation

Command cleanup

In 0.17, we cleaned up a lot of unused/broken/deprecated commands, #5211.

In case you are using any of them (we hope not), you will have to pay attention that the following management commands have been removed:

• kalite manage gitmigrate
• kalite manage katest
• kalite manage initdconfig
• kalite manage nginxconfig
• kalite manage apacheconfig
• kalite manage todolist
• kalite manage i18nize_templates
• kalite manage benchmark
• kalite manage createmodel
• kalite manage modifymodel
• kalite manage readmodel
• kalite manage runcode
• kalite manage unpack_asessment_zip
• kalite manage create_dummy_language_pack
• kalite manage generate_blacklist
• kalite manage compileymltojson
• kalite manage restorebackup
• kalite manage kalitebackup
• Remove --watch option from bin/kalite start because bin/kalite manage runserver does the job. #5314

0.16.9

Bug fixes

• Learner is not notified of mastery level, exercises keep displaying #4875
• Test improvements: Avoid test failure due to race condition #5252
• Activating simplified login results in blank login modal #5255

Known issues

• Windows installer tray application option “Run on start” does not work see learningequality/installers#106
• Writing to server.log is disabled on Windows #5057
• Installing on Windows 8, 32bit is reported to take ~1 hour before eventually finishing.
• If you are upgrading from 0.15 on a Windows system, you have to manually locate python-packages\requests, typically in C:\Python27\share\kalite\python-packages\requests and delete it (after completing the installation process). Otherwise video download breaks. #5263

Paper cuts

• Old versions of pip installer breaks because of requests library downgrade. #5264
• Exercise “Measure area with unit squares” is broken #5130
• VTT Subtitles are broken in Epiphany browser #5125
• Viewing subtitles on Ubuntu requires ubuntu-restricted-extras #4993
• Individual Student Progress Report may take a long time to load #5106
• Button “Show Keypad” may be missing on some exercises due to upstream data API issue #5103

0.16.8

Bug fixes

• Mac OSX installer version (based on pyrun) crashes #5211
• Confusing and harmless “error” message removed from first-runs #5236
• Tests now run several minutes faster and are more reliable #5242

Known issues

• Windows installer tray application option “Run on start” does not work see learningequality/installers#106
• Learner is not notified of mastery level, exercises keep displaying #4875
• Writing to server.log is disabled on Windows #5057
• Installing on Windows 8, 32bit is reported to take ~1 hour before eventually finishing.

Paper cuts

• Exercise “Measure area with unit squares” is broken #5130
• VTT Subtitles are broken in Epiphany browser #5125
• Viewing subtitles on Ubuntu requires ubuntu-restricted-extras #4993
• Individual Student Progress Report may take a long time to load #5106
• Button “Show Keypad” may be missing on some exercises due to upstream data API issue #5103

0.16.7

Bug fixes

• Restore learner stats: Correctly display login count and aggregate login durations (previously uncollected data!) #5157
• Mastery percentage wrongly displayed on learner stats page #5181
• Speed up content scanning for up to 10x speedup when scanning big video directories, meaning content scanning drops from hours to minutes #5201
• Lockdown fix for user logins #5202
• Initial “pragma” support for SQLite and setting CONTENT_DB_SQLITE_PRAGMAS. Use this to improve performance, such as allocating more memory for caching. Peewee docs. #5225
• Put max-height CSS rule on navbar logo #5206
• Submit correct HTTP user-agent for learningequality.org stats #5226
• Broken legacy assessment item download fixed (affects mainly some Debian packages) #5214
• Fix automatic CI tests so they now run (development issue, not related to deployments) #5201
• Added automatic coverage reports (development issue, not related to deployments) #5230
• Running setup command as root will give a warning + prompt, because we don’t advice running as root. #5032
• Docs updates: Tested and updated Apache/Nginx WSGI guide, updated PPA setup to work on Debian/Raspbian
• Content packs: Added ~1700 dubbed videos in Non-English versions of the content packs, populating content databases and thus adding language support for: Burmese, Indonesian, Kannada, Swahili, Tamil, Xhosa, Zulu. content-pack-maker#28. #5120

Known issues

• Mac OSX installer version (based on pyrun) crashes #5211 - will be fixed in 0.16.8
• Windows installer tray application option “Run on start” does not work see learningequality/installers#106
• Learner is not notified of mastery level, exercises keep displaying #4875
• Writing to server.log is disabled on Windows #5057
• Exercise “Measure area with unit squares” is broken #5130
• VTT Subtitles are broken in Epiphany browser #5125
• Viewing subtitles on Ubuntu requires ubuntu-restricted-extras #4993
• Individual Student Progress Report may take a long time to load #5106
• Button “Show Keypad” may be missing on some exercises due to upstream data API issue #5103
• Installing on Windows 8, 32bit is reported to take ~1 hour before eventually finishing.

0.16.6

Bug fixes

• Content packs updated, bulk of broken exercises fixed and all languages rebuilt (and should be re-downloaded), pay attention to a couple of known issues!
• Allow logins during LOCKDOWN #5117
• Remove RPI warning message about max number of concurrent downloads, there’s no longer a limit on small platforms #4982
• Make ROOT_DATA_PATH consider the KALITE_DIR environment variable #5143
• Restore downloading on RPI w/ m2crypto: Unbundle requests and use requests.get instead of urllib.urlretrieve #5138
• Docs: Add warning message on KA Lite windows application docs #5137
• Treat socket.error as if no server is running #5135
• Docs: Connect to ka-lite on IRC #ka-lite (Freenode) - #5127
• Notify student when all exercises in a series are completed (level has been mastered) #4875
• Use current year in parts of footer #5112
• Handle socket.error: Fix some cases where KA Lite fails to start due to a previous unclean shutdown #5132
• Content packs 1800 outdated questions (assessment items) inside exercises (English version) used to cause problems due to their widgets and have been removed - not only by KA Lite, but also on KhanAcademy.org. This does not affect the number of exercises and there are still 29,839 assessment items left, so it’s not a big concern! #5131

Known issues

Please note that issues with content packs are not related to the software itself but are being fixed and updated along side our release.

Watch individual issues on Github or dev@learningequality.org for announcements and updates.

• Content packs ~1700 dubbed videos are missing in Non-English versions of the content packs, making the following languages have empty content databases: Burmese, Indonesian, Kannada, Swahili, Tamil, Xhosa, Zulu. These issues can be tracked in content-pack-maker#28. #5120
• Learner is not notified of mastery level, exercises keep displaying #4875
• Login counts and session times in Learner progress reports are wrong #5157
• Browsers on Windows XP are experiencing issues with SVG images #5140
• Exercise “Measure area with unit squares” is broken #5130
• VTT Subtitles are broken in Epiphany browser #5125
• Viewing subtitles on Ubuntu requires ubuntu-restricted-extras #4993
• Individual Student Progress Report may take a long time to load #5106
• Button “Show Keypad” may be missing on some exercises due to upstream data API issue #5103
• Writing to server.log is disabled on Windows #5057

0.16.5

Bug fixes

• Missing fonts for some icons and math symbols #5110

0.16.4

Bug fixes

• Update Perseus JS modules resulting in many broken exercises #5105 #5036 #5099
• Fix broken unpacking of legacy assessment items zip #5108

0.16.3

Bug fixes

• Fix for ‘nix based systems with unconventional kernel versioning #5087

0.16.2

Bug fixes

• Fix attempt log filtering #5082

0.16.1

Bug fixes

• Tweaks to our documentation #5067
• Refactor assessment item asking logic in the setup command #5065
• Properly copy over docs pages while preserving content pack assets #5074

0.16.0

General

• KA Lite is officially supported on OSX 10.11 (El Capitan).
• We’ve revamped the language packs into a new format, called content packs. This results in significantly faster startup times across the board. .. WARNING:: You will have to redownload all your languages to fully support 0.16.
• We introduced a new beta inline help system. Check this out by going to the Facility management page and clicking “Show me how!”
• A lot of UI tweaks and bugfixes. KA Lite is now more stable than ever!

0.15.0

General

Python 2.6 is no longer supported. It may still work, but we are no longer actively supporting it. Other known issues:

• The latest OSX version (EL Capitan) is not yet supported. KA Lite is officially supported on OS X 10.8 - 10.10.
• On OSX, you must restart the server after downloading videos in order for them to be marked as available.
• On all platforms, you must restart the server after downloading a language pack in order to use it.
• You can no longer configure your server using local_settings.py. Instead, custom settings must appear in settings.py in the user’s .kalite directory.

0.14.0

General

Installation from source (using git) is no longer supported. If you have previously installed from source, in order to upgrade you must first install KA Lite again in a new location using one of the supported installers. Then you can migrate your database and content from your old installation to your new one using the command:

kalite manage setup --git-migrate=/path/to/your/old/installation/ka-lite

You must use the kalite command that comes with your new installation. The path you should specify is the base project directory – it should contain the kalite directory, which should in turn contain the database directory. Follow the on-screen prompts to complete the migration. You should then no longer use the old installation, and should consider deleting it.

0.13.0

General

Interacting with the system through kalite/manage.py has now been deprecated. Please use the kalite executable under the bin/ folder. Run bin/kalite -h for more details.

If you are pulling the source from git, you will need to run the setup command to complete the upgrade. From the base directory run:

bin/kalite manage setup

On Windows, use the bin\windows\kalite.bat in the cmd.exe prompt:

bin\windows\kalite.bat manage setup

When you are asked whether or not to delete your database, you should choose to keep your database! You will also be prompted to download an assessment items package, or to specify the location if you have already downloaded it. If you wish to download the package and specify the location during the setup process:

• Download the assessment items package here. Save it in the same folder as the setup script.
• During the setup process you will see the prompt “Do you wish to download the assessment items package now?”. Type “no” and press enter to continue.
• You will then see the prompt “Have you already downloaded the assessment items package?”. Type “yes” and press enter.
• Finally, you will see a prompt that begins with “Please enter the filename of the assessment items package you have downloaded”. A recommened file may appear in parentheses – if this is the file you downloaded, then press enter. Otherwise, enter the name of the file you downloaded. (Absolute paths are okay, as are paths relative to the directory you are running the setup script from.)

Windows

Warning

Internet Explorer 8 is no longer supported in this version. Please use a newer browser, or stick to version 0.12 to maintain compatibility.

Raspberry Pi

If you’re updating a current Raspberry Pi installation, make sure to put this in your local_settings.py to avoid slow performance:

DO_NOT_RELOAD_CONTENT_CACHE_AT_STARTUP = True

Purging *pyc files

Previously, kalite would look for *pyc files every time it was launched, and that was quite a waste since its only useful when upgrading. In dev environments, we recommend that the developer keeps track of these issues on his/her own as with any other project.

Tips: http://blog.daniel-watkins.co.uk/2013/02/removing-pyc-files-coda.html

> Luckily, it’s pretty easy to fix this in git, using hooks, specifically the > post-checkout hook. To do that, add the following to .git/hooks/post-checkout, and make the file executable:

#!/bin/bash
find $(git rev-parse --show-cdup) -name "*.pyc" -delete

For the normal user, reset assured that the upgrade notes contain more info.

Which version can I upgrade from?

0.12

Changes in scripts/

The scripts/ directory now has everything OSX-specific in mac/ and Windows stuff in win/.

These scripts are intended to all deprecate sooner down the road as such platform-specific logic will be maintained in separate distribution projects.

Scripts have been modified to continue to work but you are encouraged to make your system setup only invoke the kalite in the bin/ directory.

Starting and stopping kalite

Starting and stopping kalite is now performed from the new command line interface kalite. Examples:

kalite start  # Starts the server
kalite stop  # Stops the server
kalite restart  # Restarts the server
kalite status  # Returns the current status of kalite, 0=stopped, 1=running
kalite manage  # A proxy for the manage.py command.
kalite manage shell  # Gives you a django shell

User Manual

This guide assumes that you have already downloaded and installed the KA Lite software on your computer. If you have not yet completed these steps, please see the KA Lite Installation Guides.

Contents

Introduction

KA Lite is a lightweight web application software that allows users without Internet access to engage with Khan Academy videos and exercises in completely offline settings. It brings the flipped classroom model to some of the most remote areas in the world. Users can track their progress through videos and exercises, and coaches can log in to check students’ progress, identifying which areas the students need the most help in. If KA Lite ever reaches an Internet connection, it can sync this usage data with the KA Lite Hub – an online data repository that allows project administrators to view data and manage accounts remotely of offline deployments.

What are the goals of KA Lite?

Learning is fundamental to human flourishing, and at Foundation for Learning Equality, we strive to support learning opportunities on every front. That’s why we created KA Lite, with the goal of making high-quality educational resources and tools provided by Khan Academy accessible to the estimated 65% of the world that don’t have access to Internet.

How KA Lite works

KA Lite can be used in two different ways, depending on your needs:

1. KA Lite can be installed on one local computer which acts as a server, with client devices connecting to this local server to watch the Khan Academy videos, and to work on practice problems. A coach/teacher can then check on each student’s progress. This method is typically used by schools and other educational institutions.
2. KA Lite can be installed on the client device itself, and be used to download Khan Academy videos for offline viewing. In this way, KA Lite is almost like a piece of software that you’d install on your computer, except it runs in the Internet browser.

Who can use KA Lite?

Reaching offline or low-bandwidth communities with KA Lite is a team effort, and we find that a wide variety of people come together to make that happen. In a typical KA Lite deployment, there are 3 types of people involved with the project, which are organized into user types:

1. Administrators

   Administrators plan out the deployment and logistics, procure the devices and installs KA Lite, and oversee their delivery and integration into the classroom or community. They can also update the software, add content, customize configuration settings, and manage user accounts.

2. Coaches

   Coaches (also referred to as ‘facilitators’ or ‘teachers’) are users who add, manage, and track the progress of groups of students. They have access to student progress data in the form of coach reports, and can step in and provide individualized instruction when the student needs it.

3. Learners

   Learners (also referred to as ‘students’) are users who use KA Lite primarily for learning. They earn points for watching videos and answering exercises correctly, and their progress is tracked by the system.

Administrator User Manual

Who is an “administrator”?

A person who :

• helps to plan and oversee a project using KA Lite
• installs and updates KA Lite
• can create Coach logins, Learner logins, download videos and language packs

Administrator Glossary

If you choose to register online, these important terms will help you better understand the flow of data between your installations and the online data hub.

Sharing Network

A Sharing Network is a group of devices that share user data. This data is synced to the central server when an Internet connection is available, and then synced down onto other devices in the same Sharing Network.

Organization

An organization is a group of people responsible for administering a set of Sharing Networks. An organization can have multiple administrators and manage multiple sharing networks.

Facility

A facility is the physical space in which a device is located (e.g. a school or a computer lab in a community center). Learner, coach, and admin accounts are associated with a particular facility.

Device

A device should be able to run a KA Lite server (most computers) and other devices to be used as clients. One common configuration is using a Raspberry Pi or other inexpensive computer as a server and relatively cheap tablets as client devices. Tablets can access the servers through an access point, such as a Wi-Fi dongle, or some other networking device such as a router.

Web Browser

A program that retrieves and presents information resources on the World Wide Web. Popular web browsers include Internet Explorer, Google Chrome, Mozilla Firefox, and Safari.

Running the KA Lite Server

At the very end of the setup you are prompted to run KA Lite. Make note of the command needed to run the server - usually just kalite start.

Windows or OSX behind a Firewall

When you start KA Lite your operating system might prompt you to allow “Python.app” to accept incoming connections. The message dialogue may look like the following, depending on your operating system:

Please allow the app to run. This will make it possible for the KA Lite application to be accessible by other computers in your local network.

Accessing KA Lite

Once the server has started, you will be given two IP addresses that you can copy and paste into a web browser to to access KA Lite.

• To access KA Lite from the same machine where the server is installed use the http://127.0.0.1:8008 IP address.
• In order to access KA Lite from other machines in your local network, use the second IP address (different from the above) listed in Terminal after running kalite start.

Setting up KA Lite

Once you have successfully installed KA Lite, the installation script will give you a URL (http://127.0.0.1:8008/) to visit so that you can open KA Lite and login for the first time.

1. Copy and paste the URL into a web browser. The KA Lite application should show up.
2. Login to KA Lite using the username and password you created during the installation process.

• If you have forgotten the username/password combination, simply run kalite manage createsuperuser in your Terminal.

Once you’ve logged in, the next step in the setup process is to register your device with the KA Lite Hub.

Registering Your Device with the Hub

By registering your device with FLE, you can sync data back with our central data hub. This is useful for many reasons:

1. The Project administrator can manage user accounts and view usage data from afar, without the need to physically visit the offline device.
2. Syncing back usage data can inform the FLE team of multiple users in a certain geographic region, and we can connect people that might be able to help one another.
3. It helps FLE and our partners understand where and how the software is being used, so we can keep adding features that support you!

You will have two options:

1. One click registration. This is the perfect option for individual users who just want to get KA Lite up and running fast, and don’t need online access to data. This allows you to get the registration process over in one-click without worrying about creating a login that you’re never going to use.
2. Register with online access to data. Choose this option if you’re an administrator of larger projects. This option allows you to access your uploaded data and connect multiple installations to the same account.

Warning

If you choose to one-click register, you will unable to register with online access to data later. (If you chose this option by accident and would like to start over, navigate to the folder KA Lite is installed and re-run the setup command).

How to register your device with online access to data

Note

You will need Internet access in order to perform these steps.

1. Log into KA Lite with the username and password that you chose during setup.
2. If you have not already registered your device, you will be redirected to a page that displays your options. Click the “Register with an online account now!” button to get started with the registration process.

If you do not see this page, click on the “Manage” tab. At the top of the page you should see a link similar to this, offering to register your device:

You will be prompted to log in with your central server login credentials. Please note that these credentials are different from your login credentials created during setup. Click on the “Sign up here” link, and you will be redirected to a page that prompts you to create an account on the central server.

Once you have filled out the form and submitted it, you will be sent an activation link to the email address you supplied.

Post Registration Setup

Now that you have registered successfully, it’s time to configure your local KA Lite installation to suit your needs. If any terms like ‘facility’ or ‘device’ become unclear, check the Administrator Glossary for a quick reminder.

Create a Facility

KA Lite assumes that you are going to be using the software primarily in one place. This could be a school, a home, a community center, etc. We call this place a “facility”, and use it to help differentiate users who are syncing back data with our central data hub. In order to create a facility, follow the steps below.

1. Log in to KA Lite.
2. Click the “Manage” tab at the top of the page.

3. Make sure that the “Facilities” tab is selected.
4. Under the Facilities section, click on “Add a new facility…”

5. Fill in the information for all the fields you find below the map
6. Click the “Save facility” button when you are finished.

7. Once the information has been saved, you will be redirected back to the “Facilities” page, where you will see a message indicating that you have successfully saved your new facility.

Delete a Facility

1. Log in to KA Lite.
2. Click the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.

4. Find the facility you would like to delete, and click the trash can icon to delete the facility.

5. You will be prompted to type in the name of the facility you wish to delete for confirmation.
6. If your delete is successful, you will be redirected back to the “Facilities” page, where you will see a message indicating that you have successfully deleted the facility.

User Management

Coaches and learners are the other types of users that KA Lite supports. In order for them to be able to login, you need to create accounts for them.

Adding Learners

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Select the facility that the learner will belong to.

5. Under the “Learners” header, click on “Add a new Learner”.

6. You will be redirected to a page that says “Add a new Learner”. Fill in all the information. The facility dropdown defaults to the facility you selected in the previous steps.
7. Click “Create user”. You should be redirected to the “Facilities” page, where you will see a message indicating that you have successfully created a Learner user.

Permanently Deleting Learners

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Under the “Facilities” header, select the facility the Learner belongs to.
5. Under the “Learners” header, mark the box to the left of the Learner account you would like to delete.

6. Press the “Delete Learners” button.

7. You will be prompted to confirm your decision to delete. Press “OK” to proceed.

Adding Coaches

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Select the facility that the coach will belong to.
5. Under the “Coaches” header, click on “Add a new coach”.

6. You will be redirected to a page that says “Add a new coach”. Fill in all the information. The facility dropdown defaults to the facility you selected in the previous steps.
7. Click the “Create User” button.

8. If the user was successfully created, the page will reload with a message indicating that you have created the user.

Permanently Deleting Coaches

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Under the “Facilities” header, select the facility the coach belongs to.
5. Under the “Coaches” header, mark the box to the left of the coach account you would like to delete.

6. Press the “Delete Coaches” button.

7. You will be prompted to confirm your decision to delete. Press “OK” to proceed.

Adding a Group

You can create groups within a facility. Each group can represent a classroom, a study group, or any other way you would like to group Learners. To create a group, follow the instructions below:

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Select the facility that the group will belong to.
5. Under the “Learner Groups” header, click on “Add a new group”.

6. Fill out the name of the group, and provide a description.
7. Click “create group”.

8. You should be redirected back to the Facility page. If the group was successfully created, you will see it listed under the “Learner Groups” section.

Deleting a Group

1. Log in to KA Lite.
2. Click on the “Manage” tab at the top of the page.
3. Make sure that the “Facilities” tab is selected.
4. Select the facility that the group you would like to delete belongs to.
5. Mark the box to the left of the group you would like to delete.
6. Press the “Delete Groups” button under the “Learner Groups” header.

7. You will be prompted to confirm your decision to delete. Press “OK” to proceed.

Moving a User to a New Group

1. Navigate to the page for the facility the user belongs to.
2. Under the “Learners” header, select the Learner you would like to move by clicking in the checkbox to the left of the Learner name.

3. In the dropbox, select the group you would like to move the user to.

4. Click the “Change Learner Groups” button.

5. The page will refresh, with a message at the top indicating a successful move.

Removing Users from a Group

If you’d like to remove a user from a group without permanently deleting the user, please follow the instructions below:

1. Follow the same instructions as for “Moving a User to a New Group”, but select “Ungrouped” from the dropdown menu.

Group Summary Statistics

For each group, you should be able to view some statistics.

1. Navigate to the Learner Groups section of the facility you wish to look at.
2. Click on the group that you wish to view.

3. The statistics for the group should be displayed at the top of the page.

Edit User Information

1. Navigate to the page for the facility that the user belongs in.
2. Find the user you would like to edit.
3. Click the blue pencil icon next to the name of the user that you would like to edit.
4. Make all necessary changes on the edit user page, and click “Update user”.
5. You will be redirected to the previous page, with a message at the top indicating that your changes have been saved.

Allowing Other Users to Connect

In order for other users to be able to connect with the KA Lite from different computers, you will need to give them an IP address with which to access the software. The rest of the users should use the second IP address, different from the one you use (usually 127.0.0.1:8008 received during setup), to connect with KA Lite.

Downloading Videos

Now that you’ve created a facility and user accounts, it’s time to add video content to your local KA Lite installation! Since the videos can take up a large amount of space, you can choose to download only the videos that you need. If your device has enough space and you wish to download all of the videos, we recommend using the Downloading Videos in Bulk option.

Downloading Individual Videos

After registering your device:

1. Click the “Manage” tab at the top of the page.
2. Click on the “Videos” tab.

3. View subtopics by clicking on the subject of your choice. You can close them by clicking on the subject again.
4. Mark the content you wish to download by clicking the checkbox to the left of the content name.
5. Click the the first “Download n new selected video(s)” button (colored green) in the top left box of the page. The button should also show you the total number of videos you have selected to download, as well as the total size of the content.
6. Once the download is completed, video content will be ready for Learners to watch!

Downloading Videos in Bulk

The full set of videos, if downloaded through the KA Lite interface, will occupy more than 150GB. If you want to download all the videos, we also have torrent files with resized videos (~33 GB for English). To fetch all the videos, download and open the appropriate torrent file.

Save the videos in the CONTENT_ROOT directory of your installation. By default, that is the .kalite/content/ folder in the home directory of the user running KA Lite.

On Windows, navigate to something like C:\Documents and Settings\<username>\.kalite\content.

Note

If the drive where your .kalite/ folder is located does not have enough free disk space, you can change the path of the CONTENT_ROOT in your Configuration Settings, and define a different folder where your want to store videos. Remember to move the files from your old /content/ folder into the new one.

Note

The .kalite folder may be hidden on some systems, so you have to enable showing hidden files and folders in your file browser.

After you copied in the new video files or changed the CONTENT_ROOT path, you need to register those changes with KA Lite:

1. Click the “Manage” tab at the top of the page.
2. Click on the “Videos” tab.
3. Click the “Scan content folder for videos” button (third one, colored blue) in the top left box of the page.

4. Once the scan is completed, video content will be ready for Learners to watch!

Adding Languages

KA Lite content is offered in several languages. If your language is available you can download the contentpack for it with all the available subtitles and user interface translations. After you download and install the contentpack for a desired language, KA Lite will give you the option to download individual dubbed videos from that language’s Khan Academy YouTube channel. For more technical background about the new contentpacks, please refer to our Wiki page.

Warning

If you are upgrading from a previous KA Lite version, you MUST update all the languages you had previously AND restart your server. If you are unsure on how to do this, please see Restarting your server.

Download Language Packs

To download language packs:

1. From the “Manage” page, click on the “Language” tab.
2. Select the language pack you wish to download by selecting from the drop-down menu.

3. Click the “Get Language Pack” button.

4. Once the download finishes, you can see your language in the “Installed Languages”. If you are upgrading from a previous version of KA Lite, you MUST restart your server to make the new content/language pack available for your users. If you are unsure on how to do this, please see Restarting your server.
5. After the server restart, learners and coaches will be able to switch their language to any of the installed language packs. Their default will be the default that you set by clicking on “Set as default”.

Delete Language Packs

To delete language packs:

1. Log in as the administrator.
2. Click the “Languages” link in the navigation bar
3. In the Installed Languages section, there is a button for deletion of each language.

Restarting your server

When you make configuration changes such as changing the filepath for your video content, you may need to restart your server for changes to take effect. Remember that this will cause KA Lite to become inaccessible to users until the server is running again, but it will not delete any user accounts or information that you have configured during setup.

Restart process varies depending on the OS you are running the KA Lite server on.

Restarting Your Server: Windows

In the system tray, right click on the KA Lite icon. Click the “Stop Server” item in the context menu. Right click on the KA Lite icon in the system tray again, and click “Start Server”. If the option is not clickable, wait a while and try again or restart your computer.

Restarting Your Server: Linux

1. Open up your terminal. For most Linux distributions, you can do this by going to Menu -> Accessories -> Terminal or Applications menu -> System -> Terminal.
2. Type in kalite restart. This should stop the server, then attempt to restart it again. The process may take up to a few minutes.
3. Once you see the script that begins with To access KA Lite from another connected computer, try the following address(es): …. you will know that your KA Lite server has been successfully restarted.

Restarting Your Server: Mac

1. Open up your terminal. You may do this by navigating to the magnifying glass at the top right corner of your screen, and typing in “Terminal”, then hitting “Enter” on your keyboard.

1. Your terminal should be opened up. It should look a little something like the following:

1. Type in kalite restart. This should stop the server, then attempt to restart it again. The process may take up to a few minutes.
2. Once you see the script that begins with To access KA Lite from another connected computer, try the following address(es): …. you will know that your KA Lite server has been successfully restarted.

Configuration Settings

Once you have deployed KA Lite to a computer, there are a number of ways you can customize the behavior of your installation. Below, you will find a list of these possible customizations with instructions or descriptions on how to do it.

Warning

Please follow these instructions carefully! Customizing the server incorrectly can break your installation. It can be very hard to find and undo the error.

Running KA Lite with your own settings

In a text editor, open up /home/user/.kalite/settings.py (on Windows, locate something like C:\Documents and Settings\<username>\.kalite). That file is where you should put your custom settings, and KA Lite will load them automatically.

You can also run the kalite with a completely different Python settings module by specifying kalite <command> --settings=my_settings_module.

Note

The .kalite folder may be hidden on some systems, so you have to enable showing hidden files and folders in your file browser.

Changing base settings

By default, /home/user/.kalite/settings.py will load kalite.project.settings.base which are the basic settings. But you can also load Raspberry Pi settings by changing the file to read something like:

from kalite.project.settings.raspberry_pi import *
# Put your settings here, e.g.
# MY_SETTING_VAR = 123

Available settings

See above for instructions on where to configure these settings.

Most common settings

• DEBUG = <True or False> (default = False) Enables debug mode. In case you run into technical issues, enable this setting before troubleshooting / reporting.
• CONTENT_ROOT = "<path to desired content folder>" (default=/home/user/.kalite/content) This is the path that KA Lite will use to look for KA Lite video files to play. Change the path to another local directory to get video files from that directory. NB! Directory has to be writable for the user running the server in order to download videos.
• TIME_ZONE = <desired time zone>  (default = "America/Los_Angeles") You can set this to be the local time zone for your installation. Choices can be found here.
• LANGUAGE_CODE = "<desired ISO 639-1 Language Code>" (default = "en-us") You can set this to the desired language code for this installation (All choices can be found here). If there are translations available, our web server will show them in KA Lite. Soon, we hope to provide support for internationalized content inside the KA Lite interface.
• USE_I18N = <True or False> (default = True) If you set this to False, our web server will make some optimizations so as to avoid loading internationalization tools. Things might run a little faster, but you won’t have support for translated content.
• USE_L10N = <True or False> (default = False) By default, this is set to False. If you set this to True, Django will format dates, numbers and calendars according to the current locale. For example, January 5, 2000 would be 1/5/2000 if locale = “en-us” and 5/1/2000 if locale = “en-gb”
• USER_FACING_PORT = 123 When KA Lite is running behind a proxy (for instance Nginx or Apache), you probably want users to be accessing KA Lite from a different port than the service itself is running from. Setting this option will change certain system messages to use a different port. It does not affect the port that KA Lite is using.
• KALITE_WELCOME_MESSAGE = <str> HTML code to be rendered to admin users on their first login. Default text links to offline documentation and online support forums.

User restrictions

• LOCKDOWN = <True or False> (default = False) With this setting, users must be logged in order to access videos & exercises
• DISABLE_SELF_ADMIN = <True or False> (default = False) Disables user sign ups.
• HIDE_CONTENT_RATING = <True or False> (default = False) Hides content feedback, i.e. the star rating box below videos
• RESTRICTED_TEACHER_PERMISSIONS = <True or False> (default = False) Restricts teachers from editing student accounts. Useful especially at larger institutions where permissions should be reserved for admins.
• USER_LOG_MAX_RECORDS_PER_USER = <max user log records per user> (default = 0 [disabled], -1=unlimited logs) In order to keep local data in the UserLog model, detailing usage, you can choose the number of UserLog objects that you wish to retain. These objects are not sync’ed.
• SIMPLIFIED_LOGIN = <True or False> (default = False). Switches off passwords in the Learner’s login modal.

Online synchronization

• USER_LOG_SUMMARY_FREQUENCY = <desired frequency (number, amount of time)> (default = (1, "months") This determines the granularity of how we summarize and store user log data. One database row is kept for each student, on each KA Lite installation, for the defined time period. Acceptable values are: (1, “months”), (2, “months”), (3, “months”), (6, “months”) - separate logged data for every month, 2 months, 3 months, or 6 months, respectively (1, “weeks”) - separate logged data for every week ** NOTE THIS MAY PRODUCE A LOT OF DATA **
• SYNC_SESSIONS_MAX_RECORDS = <desired max records of sync sessions> (default = 10) Every time your installation syncs data, we record the time of the sync, the # of successful logs that were uploaded and downloaded, and any failures. This setting is how many such records we keep on your local server, for display. When you log in to our online server, you will see a full history of these records.

Other settings

• KALITE_DOWNLOAD_RETRIES = <integer> (default = 5) If you are trying to download videos with a very unstable connection, this setting will increase the number of retries for individual video downloads. The grace period between each attempt automatically increases.

Environment variables

This is usable in advanced deployments.

An environment variable is something which you can define in your terminal or using a terminal script.

• KALITE_HOME = </desired/to/user_data> Sets the home directory which the user data is stored in. Default: ~/.kalite
• KALITE_LISTEN_PORT Instead of using the command line parameter kalite --port=1234, you can also set this environment variable. Default: 8008
• KALITE_DIR = </path/to/shared/data> Where KA Lite finds shared program data (a environment sometimes configured by installers). Default: (unset). If not set, it will be evaluated to <sys.prefix>/share/kalite, for instance that can evaluate to /usr/share/kalite.

Coach User Manual

Who is a “coach”?

A person who :

• adds, manages, and tracks the progress of groups of students.
• has access to student progress data in the form of coach reports
• provides instructions to students

In addition, by default, coaches can:

• create coach logins, Learner logins, download videos and language packs

(This can be disabled by the administrator with the RESTRICTED_TEACHER_PERMISSIONS setting)

Coach Reports

Coach reports are visualizations of the data generated by your learners. The goal of the coach reports is to put the data into an easy to understand format, so you can understand how learners are progressing and where they need the most help.

The Report Page displays an overview of the learners and a tabular report.

Overview

1. Select the “Teach” tab at the top of the page.
2. Select the appropriate facility from the drop down menu to view reports for a specific facility.
3. Select a group from the drop down menu to view the overivew for a specific group or leave the group as is.
4. The display should refresh with the data requested, for student activity from the previous week onwards.
5. To view data over a longer period, select the start and end date using the time picker, and click the ‘refresh’ icon next to the time picker.

The overview will display the activity of the group: the percentage of hours logged on content versus exercises, the average progress in exercises, and the total exercises attempted.

Tabular Report

A tabular report is a grid that can show how students are doing in specific subjects at a high level. As a coach, you can select which group of students you’d like to check progress for, and which subset of videos or exercises you’d like to see reports on. This allows you to easily identify which areas learners are struggling in, as well as which learners are doing well.

1. Click the “Show Tabular Report” button at the bottom of the page.

Progress By Topic

1. Click on the “Show Tabular Report” button.
2. A table should be generated with the data requested.

The color of the rectangles in the table indicate how that student is doing on a particular exercise. The following key explains the color code of the table cells (this information will also be available on the Coach Report page):

	Not Attempted: The student has not attempted the subtopic.
	In Progress: The student has completed a few questions.
	Struggling: The student is struggling on the subtopic.
	Completed: The student has completed the subtopic.

Detailed View

1. Click on the colored cells.
2. A panel should open up below the cell to reveal the number of questions attempted and the actions made on each exercise.
3. Click on the same cell to close the panel.

Inline Help

KA Lite has an inline help system on some pages. On parts of the site where it is available, you can find a “Show me how!” button. If you click this button, you can view a guided tour of the currently shown interface.

Exporting User Data

On the facility management page, you can find the “Export Data” button. If you click this button, you’ll be taken to a page where you can export some user data in CSV format. This is so you can perform analyses on data accumulated in KA Lite using your own methods – in the future such tools may be included in KA Lite itself! You can select which resource you wish to export, and narrow down the list of users to draw data from by selecting facilities and groups. When you have made your selection, click the “Export” button to download a CSV file with the requested data.

Content Ratings

Select the “Ratings” option in the “Resources” dropdown. Ratings are tied to users and content items – each rating has a unique-together user, content type, and content id. The content id is suppressed in the output as it is not human readable, but is replaced with the title. The title of content items may not be unique – for example a video and an exercise might have the same title. In such cases, you can differentiate using the content type.

Learner User Manual

Who is a “learner”?

Anyone who uses KA Lite primarily for learning. Learner accounts will track individual progress through videos and exercises, and learners will only be allowed to view their own data.

Accessing KA Lite

There are two ways KA Lite can be used:

1. Set up on a network with one main server, having machines connect to this server. If this is the setup chosen, installation is not necessary on a learner’s computer, as it can be accessible through a web browser with the IP address of the server. Simply copy and paste the server’s IP address into your web browser any time you’d like to access KA Lite. If you are unsure what the address is, please contact your administrator.
2. Installed for single user, on one machine. If you are not accessing KA Lite through a network or wish to run KA Lite on your own computer, please follow the KA Lite Installation Guides first before proceeding with this user manual. Once you have done so, copy and paste the URL given during the installation process into a web browser to access KA Lite (it should be http://127.0.0.1:8008).

How to Sign Up

Learners may receive their account information from their Coaches or Administrators if their account has been preconfigured. However, it is possible for learners to create their own account. To create an account, please follow the instructions below:

1. Open KA Lite.
2. Click “Sign Up” at the top right of your screen.
3. If you are redirected to a page that asks you to select a facility, please select the facility to which you belong. If you are unsure which facility you belong to, please contact your administrator or coach. Skip this step if you do not see this page.
4. Fill out the information.
5. Click the “Create user” button when you are finished.

How to Log In

1. Open KA lite.
2. Click on the “Log In” tab.
3. Enter your username and password, and then click the “Log in” button.

Navigating through Content

To begin engaging with the Khan Academy videos and exercises, first make sure you are logged into KA Lite. Upon log in, you should see a green menu on the left that lists the content. If you do not see this green menu, please start by clicking on the “Learn” tab on the home page.

Start by selecting the subject you’d like to explore. This will expand the side menu, displaying subtopics within that subject.

The icons to the left of the menu selections describe whether or not it is a video, an exercise, or a menu that can be further expanded:

• icons designate that the selection can be further expanded into subtopics
• icons designate that the selection is an exercise for that topic.
• icons designate that the selection is a video for that topic.

Once you have found the video or exercise that you’d like to engage with, simply click on that selection.

Content Recommendation

The content recommendations based off of your current progress are on the homepage and becomes visible after you have made some progress on at least one exercise. After you have made any form of progress, this is the first page you should see after logging in. If at any point you would like to get to your homepage, please click on the KA Lite logo in the top left hand corner.

The homepage now provides you with three cards:

Resume: This card allows you to navigate to the last exercise you were on. This includes both videos and written exercises.

Next Steps: This card allows you to navigate to excercises you have begun; you can also to navigate to the over-arching topic to which that exercise belongs to.

Explore: This card recommends content for you based on topics you have completed and begun. This card also recommends random content from our collection of topics to encourage learning from multiple fields.

Content Rating

You can leave feedback on each content item. When you are logged in, you’ll find a rating box below each content item. You can rate each content item on Quality and Difficulty on a 1 to 5 scale by clicking on the star icons. 1 represents the lowest rating, and 5 represents the highest rating. You can alter the ratings at any time by clicking on a different star icon.

After rating Quality and Difficulty you’ll be able to leave any comments you wish. Simply click on the text box labeled Your Comments and type away! You can edit your comments freely.

At this time, you are only able to view your own ratings.

Coaches can export the ratings of all users in csv format.

How to Practice Exercises

First, please log into KA Lite. Then, navigate to the topic that you’d like to practice exercises for.

To answer a question, enter the answer in the box on the top right of the module, or select the bubble next to the answer choice in the exercise panel. Once you have decided on your answer, click “Check Answer”.

After answering a question, the exercise module will not advance to the next question until you click the “Next Question…” button on the right hand side of the module.

The bar on the top right will display your progress as you go through the exercises. After 8 correct answers out of the last 10 answered, your points for the exercise will be added to our total and you will have mastered the exercise. If you get an answer wrong or ask for a hint, you will be unable to earn points from that question until it is presented again.

Hint

If you are stuck on a problem, you can ask for a hint by clickin on the “Show hints” button! Use your hints wisely, for there are a limited number of them for every section.

Saved Progress

If at any point during an exercise you wish to watch a video to refresh your memory, feel free to navigate to the video by expanding the green tab which will bring up the content menu. Your progress for that exercise will be saved and you will not lose your work.

How to View Your Progress

At any point in time, you should be able to view your progress on any topic. In order to do this,

1. Log into KA Lite.
2. Then, click on your name in the top right of the page.
3. It will then show a drop-down menu, from which you can click on “My Progress”.

On the progress page, you will be able to view your progress on each topic. There will be two bars for each topic. The top bar represents your progress on the videos for that topic, and the bottom bar will represent your progress on the exercises for that topic.

The kalite command

Once installed, a new command kalite is available from your terminal:

# Start the server in the background (as a daemon)
kalite start

# Stop the server
kalite stop

# Stop and start the server in the background (as a daemon)
kalite restart

# Runs a foreground process where you can see output of the server
kalite start --foreground

# Show available commands
kalite manage help

Warning

When the KA Lite software is installed using a .deb package, on Ubuntu, Debian, or Raspbian, do not use the kalite command directly. Instead, use system commands like sudo service ka-lite start, sudo service ka-lite stop or sudo service ka-lite restart.

Using the package ka-lite-raspberry-pi, it runs on a different port.

These configurations will not be active if you run a kalite command from your own command line.

KA Lite Command Line Interface (CLI)

Auto-generated usage instructions from kalite -h:

KA Lite (Khan Academy Lite)

Supported by Foundation for Learning Equality
www.learningequality.org

Usage:
  kalite start [--foreground] [options] [DJANGO_OPTIONS ...]
  kalite stop [options] [DJANGO_OPTIONS ...]
  kalite restart [options] [DJANGO_OPTIONS ...]
  kalite status [options]
  kalite shell [options] [DJANGO_OPTIONS ...]
  kalite test [options] [DJANGO_OPTIONS ...]
  kalite manage [options] COMMAND [DJANGO_OPTIONS ...]
  kalite diagnose [options]
  kalite -h | --help
  kalite --version

Options:
  -h --help             Show this screen.
  --version             Show version.
  COMMAND               The name of any available django manage command. For
                        help, type `kalite manage help`
  --debug               Output debug messages (for development)
  --port=<arg>          Use a non-default port on which to start the HTTP server
                        or to query an existing server (stop/status)
  --settings=<arg>      Specify Django's settings module. Must follow python's
                        import syntax.
  --skip-job-scheduler  KA Lite runs a so-called "cronograph", it's own built-in
                        automatic job scheduler required for downloading videos
                        and sync'ing with online sources. If you don't need this
                        you can skip it!
  DJANGO_OPTIONS        All options are passed on to the django manage command.
                        Notice that all django options must appear *last* and
                        should not be mixed with other options. Only long-name
                        options ('--long-name') are supported.

Examples:
  kalite start          Start KA Lite
  kalite status         How is KA Lite doing?
  kalite stop           Stop KA Lite
  kalite shell          Display a Django shell
  kalite manage help    Show the Django management usage dialogue
  kalite diagnose       Show system information for debugging

  kalite start --foreground   Run kalite in the foreground and do not go to
                              daemon mode.

Planned features:
  Universal --verbose option and --debug option. Shows INFO level and DEBUG
  level from logging.. depends on proper logging being introduced and
  settings.LOGGERS. Currently, --debug just tells cherrypy to do "debug" mode.

Frequently Asked Questions

Something isn’t working - does KA Lite have log files?

It’s very important to get more technical information if KA Lite is not working or crashing.

Have a look at ~/.kalite/logs (on Windows, locate something like C:\Documents and Settings\<username>\.kalite), where you will find the log files which KA Lite writes to while it’s running. If KA Lite has crashed, have look at the latest log file. You can also refer to ~/.kalite/server.log which may in some cases contain more information regarding a crash.

How do I install KA Lite?

Information on how to install KA Lite is available via our user guides.

How much does KA Lite cost to install?

It is FREE – both free as in “free speech” and free as in “free beer”! To learn more about free software, see this Free Software Foundation article.

How do I report a problem?

Please follow the instructions on our Github Wiki for reporting bugs.

Why are my downloaded videos not displaying?

Please refer to Video playback.

How do I change KA Lite’s content folder?

If you want to change your installation’s content folder from the default (say, to point to a shared folder across installations), see how to configure CONTENT_ROOT in the “Configuration Settings” section.

How do I change the directory where all of KA Lite’s runtime files go, including content?

You can change this directory by setting the KALITE_HOME environment variable to the path of your choice.

If the variable is left unset (default), KA Lite’s runtime files will be placed in your user’s home directory under the .kalite subdirectory. Typically, it is /home/user/.kalite/ (on Windows, locate something like C:\Documents and Settings\<username>\.kalite).

There are many ways to set an environment variable either temporarily or permanently. To start kalite on OSX or Linux with a different home, run:

KALITE_HOME=/path/to/home kalite start

The change requires that you first stop the server, change the KALITE_HOME environment variable, and then copy the contents from the default .kalite directory to the new directory you just specified. When you start the server again, all your files should be seamlessly detected at that location.

I would like to download the videos for KA Lite via BitTorrent, is this possible?

Yes! Please see the instructions for “Downloading Videos in Bulk”.

How can I install a language pack without a reliable internet connection?

In version 0.16 we changed the proces for making KA Lite available in other languages. For more technical background about the new contentpacks, please refer to our Wiki page.

You can download from our server the new contentpacks for all the languages, and carry around the zip file to computers you want to install the contentpack to.

Once you have downloaded the contentpack for install on a computer without a reliable internet access, use the following command:

kalite manage retrievecontentpack local <language code> <path to zip file>

Use the language code indicated below:

Language name	Code
Arabic	ar
Bulgarian	bg
Burmese	my
Danish	da
English	en
French	fr
German	de
Hindi	hi
Kannada	kn
Lao	lo
Polish	pl
Portuguese, BR	pt-BR
Spanish	es
Swahili	sw
Tamil	ta
Xhosa	xh
Zulu	zul

An example invocation for installing the French contentpack on Windows would be:

C:\Python27\Scripts\kalite manage retrievecontentpack local fr fr.zip

After starting up your server, you should now see your new language in the Manage > Language page.

Do I need the internet to run KA Lite?

No. The only time you need an internet connection is for the initial download of the content (either to the target device, or to a USB stick that can then be carried or mailed). After installation, you can serve the content from a local server or use it directly on the server device without an internet connection.

How do you operate in the field?

The Learning Equality team primarily works in our San Diego offices, building software and shaping our roadmap based on our interactions with our partners around the world. We work with individual humanitarians and NGOs of all sizes to help them distribute KA Lite to offline communities around the world.

What are the typical deployment scenarios?

A typical school deployment varies depending on whether or not a school already has a computer lab.

School with an existing computer lab: In this case, KA Lite would be deployed as a server on one of the existing computers. Students would connect using client devices over the local intranet.

School with no existing computer lab: For schools that do not have an existing computer lab, a KA Lite deployment would involve obtaining a device that can run as a KA Lite server (most computers) and other devices to be used as clients. One common configuration is using a Raspberry Pi or other inexpensive computer as a server and relatively cheap tablets as client devices.

What are some possible hardware configurations for deploying KA Lite?

You will need:

1. A computer that is running the KA Lite software (e.g. a desktop computer, laptop, or Raspberry Pi).
2. One or more client devices that have web browsers (laptops, tablets, desktop computers, etc)

Note that for a single-user deployment (1) and (2) can be the same computer, with the browser connecting to the locally running KA Lite server software. To make the software accessible to multiple client devices, you will need to put them on the same local network as the KA Lite device (1), e.g. through a WIFI access point.

To read more details, see System requirements.

What sort of processing power is required for KA Lite?

See System requirements.

What are the operating system (OS) and software requirements for running KA Lite?

KA Lite can run on almost any major operating system: Windows, Linux, and Mac/OSX. The only software dependency is the Python 2.7 runtime.

See System requirements.

What is data syncing?

KA Lite is capable to share your student progress data with a central data repository when you are online. This enables the system to have an online backup of your data, allows you to view your student progress online, and to share your data across multiple KA Lite installations.

Who maintains the KA Lite project?

KA Lite is created, maintained, and operated by the Foundation for Learning Equality, Inc, a California-based nonprofit organization.

What is KA Lite’s affiliation with Khan Academy?

KA Lite is an independent, open-source project maintained by Learning Equality, and is not officially affiliated with Khan Academy, although they are very supportive of the KA Lite project, and are one of our key partners.

How can local curriculum be generated?

Local content creation is something that Learning Equality intends to build into future platforms. If you would like to be notified when it is available, subscribe for updates, or if you would like to help fund this project, please click here.

How is it possible to compress the content into KA Lite?

Users are able to select which videos they wish to download through the user-interface, allowing to customize the amount of space used.

What languages is KA Lite available in?

KA Lite was released with internationalization support on 2014/03/07, including support for a translated interface, dubbed videos, subtitles, and translated exercises. Currently we have varying levels of support Portuguese, Danish, French, Polish, Spanish, and many others. Please visit our blog for the latest information about language support.

Can I contribute to KA Lite as a developer?

Yes! KA Lite is an open source project, and developers are encouraged to contribute! If you are interested in developing for KA Lite, check out the instructions for getting started.

Can I contribute to KA Lite as a translator?

Yes, absolutely! If you would like to contribute to KA Lite as a translator, you can get started over on our translations and internationalization page on our GitHub Wiki!

Can I contribute even if I don’t know how to code?

Yes! There are many ways!

How do I find out more?

To stay up-to-date on all our activities, follow our blog, Twitter, and Facebook!

How does Learning Equality measure the impact of KA Lite?

Because KA Lite is freely available and designed to run offline, collecting impact data can be challenging.

KA Lite is capable of synchronizing data with our central data repository when an online connection exists.

For the deployments in which we do have direct involvement, we receive updates from our partners with quantitative data from the built-in coach reports and attain qualitative data from our on-site visits. For example, we know that 20 out of 20 students in the Idaho Department of Corrections deployment have passed their GED using KA Lite.

Backing up data: is there any easy way to do it locally?

Yes! Just copy the .kalite folder, typically located in /home/user/.kalite. To restore, simply copy the backup data file to the same location. If you have changed versions, please run:

kalite manage setup

to guarantee your database is compatible with the current version of KA Lite you have installed! Note that online data back-ups occur if you “register” your KA Lite installation with an online account on our website.

If you only want to backup the database, locate the .kalite/database/ folder and copy and restore that one.

I can’t get KA Lite to work on Windows! The installation succeeded, but nothing happens!

KA Lite on Windows is controlled through a task-tray program. See the installation guide for some more info.

I can’t see videos in Firefox on Ubuntu/Debian!

Install Ubuntu restricted extras package in the Ubuntu Software Center.

I am online but device registration freezes

Recent efficient versions of ad blockers and anti-trackers have started to block scripts from third-party servers, including the server we use to register a device against.

The solution is to add an exception to unblock hub.learningequality.org (or staging.learningequality.org if you are a developer).

Windows: “python.exe has stopped working”

This is likely due to a broken Python installation or that you installed 32 bit Python on a 64 bit system (or vice versa). Try fetching a new Windows installer from python.org.

Developer Docs

Useful stuff our devs think that the rest of our devs ought to know about.

Getting started

Warning

These directions may be out of date! This page needs to be consolidated with the Getting Started page on our wiki.

Recommended setup

KA Lite is like a normal django project, if you have done Django before, you will recognize most of these steps.

1. Check out the project from our github

2. Create a virtual environment “kalite” that you will work in:

   sudo pip install virtualenvwrapper
   mkvirtualenv kalite
   workon kalite
   

3. Install kalite in your virtualenv in “editable” mode, meaning that the source is just linked:

   cd path/to/repo
   pip install -e .
   

4. Install additional development tools:

   pip install -r requirements_dev.txt
   

5. Build static assets such as javascript:

   make assets
   

6. Run the setup, which will bootstrap the database:

   kalite manage setup
   

7. Run a development server and use development settings like this:

   kalite manage runserver --settings=kalite.project.settings.dev
   

You can also change your ~/.kalite/settings.py to point to kalite.project.settings.dev by default, then you do not have to specify –settings=… every time you run kalite.

Now, every time you work on your development environment, just remember to switch on your virtual environment with workon kalite.

Static vs. Dynamic version

Apart from Python itself, KA Lite depends on a couple of python applications, mainly from the Django ecosystem. These dependencies can be installed in two ways:

• Dynamic: Means dependencies are automatically installed through PIP as a separate software package accessible to your whole system. This is recommended if you run KA Lite and have internet access while installing and updating.
• Static: Static means that KA Lite is installed with all the external dependencies bundled in. Use this method if you need to have KA Lite installed from offline media or if KA Lite’s dependencies are in conflict with the system that you install upon.

Virtualenv

You can install KA Lite in its very own separate environment that does not interfere with other Python software on your machine like this:

pip install virtualenv virtualenvwrapper
mkvirtualenv my-kalite-env
workon my-kalite-env
pip install ka-lite

Running tests

On Circle CI, we run Selenium 2.53.6 because it works in their environment. However, for more recent versions of Firefox, you need to upgrade Selenium:

pip install selenium\<3.5 --upgrade

To run all of the tests (this is slow):

kalite manage test

To skip BDD tests (because they are slow):

kalite manage test --no-bdd

To run a specific test (not a BDD test), add an argument <app>.<TestClass>:

kalite manage test updates.TestDownload --no-bdd

To run a specific item from Behavior-Driven Integration Tests, use <app>.<feature_module_name>:

kalite manage test distributed.content_rating --bdd-only

Front-End Code

All of our front end code is written in Javascript, with much of it using Backbone.js (and its dependencies jQuery and Underscore.js).

All new code, where possible, should be written using Backbone.js to modularize functionality, and allow code to be reused across the site.

Inline Javascript (i.e. Javascript directly in the Django templates inside <script> tags) should be avoided except where absolutely necessary (such as to initialize some master object on a page).

For templating on the front end, we use Handlebars.js to render templates with a restricted set of statements and access to all variables passed into the template context.

Modularity

In order to maintain modular code and be explicit about our dependencies, we use Browserify to build Javascript code into bundles for use on the client side.

To specify a bundle to be imported into the page, you need to create a ‘bundle module’ - this will be automatically detected by our Javascript build script, and be built into a bundle that can then be included as a script tag in a Django template.

‘Bundle modules’ are specified inside the static/js directory of a Django app - e.g. ‘bundle modules’ in distributed are under kalite/distributed/static/js/distributed/bundle_modules. Here is a simple example of a bundle_module:

var $ = require("base/jQuery");
var TopicChannelRouter = require("topics/router");
var Backbone = require("base/backbone");

module.exports = {
    $: $,
    TopicChannelRouter: TopicChannelRouter,
    Backbone: Backbone
}

This is the ‘learn’ bundle module (a file called learn.js in the above directory) - all it specifies is a set of top level objects that need to be exposed to be run within the context of the Django template (because we need Django template context variables to be passed into the Javascript) - here are the relevant <script> tags from the template:

<script src="{% static 'js/distributed/bundles/bundle_learn.js' %}"></script>
<script type="text/javascript">
    var bundle = require("learn");
    bundle.$(function() {
        window.channel_router = new bundle.TopicChannelRouter({default_channel: "{{ channel }}"})
        bundle.Backbone.history.start({pushState: true, root: "{% url 'learn' %}"});
    });
</script>

Here, we require the learn bundle (all bundles can be referenced by their name in this way), and are then able to access the objects defined in its module.exports.

For more information about using Browserify to handle dependencies, please refer to the Browserify Handbook.

Building Frontend Code

The build script uses node.js - to run the build server for production simply run npm install --production and node build.js or build all assets with one command, make assets.

Alternatively, for development, running bin/kalite start with the --watch flag will automatically run the build process in watch mode, recompiling Javascript as it changes, on the fly.

If you prefer to run the compilation process separately, it has the following flags:

--watch         Run in watch mode - automatically recompile Javascript when modules imported into bundles are changed (N.B. this will not detect new bundles being created.)
--debug         Compile in debug mode - do not minify source code, and create source maps for easier client side debugging.
--staticfiles   Saves built files directly to the static files dir, rather than into the original app directories - useful if collectstatic has already been run.

Implementing with Backbone

Most of our front end code uses only three kinds of objects, Backbone Models, Collections, and Views.

Backbone Models contain data that we use to render the page - in the case of a coach report, for example, this might be data about each student.

Backbone Collections are groups of Models - so you might have a Collection where each model represents the progress data for an individual student.

The Views define how this data is displayed in the browser, and also defines responses to user interaction to the current display.

Most Views also have an associated Handlebars template, which defines the HTML and how the data passed into the template is displayed in the rendered View.

Often the data contained in a Backbone Model can change while the user is still on the same page (for example, a student’s total points can change while they are interacting with an exercise, so we want their displayed points to update whenever the ‘points’ attribute of the model updates too).

Here is an example of a Backbone View in KA Lite that does just that:

var TotalPointView = Backbone.View.extend({

    initialize: function() {
        _.bindAll(this);
        this.listenTo(this.model, "change:points", this.render);
        this.render();
    },

    render: function() {

        var points = this.model.get("points");
        var message = null;

        // only display the points if they are greater than zero, and the user is logged in
        if (!this.model.get("is_logged_in")) {
            return;
        }

        message = sprintf(gettext("Points: %(points)d "), { points : points });

        this.$el.html(message);
        this.$el.show();
    }

});

The initialize method is called whenever a new instance of TotalPointView is instantiated (by calling e.g. my_total_point_view = new TotalPointView({model: model})). There are several arguments that will automatically get set on the view if passed in to the constructor, model is one of them. See the Backbone.js for more details.

_.bindAll(this); is included in many initialize methods we use, this helps to ensure that whenever a View method is called, then the this variable inside each method always refers to the view itself - without this, especially when methods are called due to being bound to events, the this variable can refer to something completely different.

this.listenTo(this.model, "change:points", this.render); is an example of such an event binding. Here, the view is being told that whenever its model fires the event “change:points”, then it should call its own render method (this.render). Backbone models fire “change” events whenever one of their attributes changes, and also a specific event like “change:points”, which would only fire when the ‘points’ attribute of the model changes.

Finally this.render(); calls the render method of the view. This method is generally reserved for creating and modifying DOM elements that we will insert into the page.

Inside the render function var points = this.model.get("points"); locally defines the points - as you can see from this example, to access the attributes of a Backbone Model, the get("<attribute>") method is used.

The content to be rendered into the DOM in this instance is so simple that a Handlebars template is not used. Rather message = sprintf(gettext("Points: %(points)d "), { points : points }); simply fills in the %(points)d with the ‘points’ attribute of the second argument of sprintf. See the sprintf docs for more information.

The part of the page that the view is scoped to can be refered to by this.$el - this is a jQuery object for the subsection of the DOM of the view, so any whole view operations (such as this.$el.html(message); or this.$el.show();) will change the entire subsection of the DOM for that view (but will normally only be a subset of the DOM of the entire page). this.$el.html(message); sets the entire HTML content of the view DOM subsection to the content of the message variable, and this.$el.show(); makes the DOM subsection visible.

Creating Your Own Backbone View

To create a new Backbone View, you will either add to an existing Javascript file in the project, or create a new file. For example if you were to add a new View to the coachreports app you could create a file under kalite/coachreports/static/js/coachreports/hexagon_report.js. Some boilerplate to start off with might look something like this:

var HexagonReportView = BaseView.extend({

    template: HB.template("reports/hexagon-counting")

    initialize: function() {
        _.bindAll(this);
        this.listenTo(this.model, "change:number_of_hexagons", this.render);
        this.render();
    },

    render: function() {
        this.$el.html(this.template(this.model.attributes));
    }

});

this.$el.html(this.template(this.model.attributes)); this line will insert all the attributes of the model into the template for rendering, and then set the HTML of the subsection of the DOM for the view to the resulting HTML.

For this to work, there must be a file kalite/coachreports/hbtemplates/reports/hexagon-counting.handlebars that contains the Handlebars.js template for this view. For a simple report, the template might look something like this:

<div class="hexagon-report">
    <h3>{{_ "Hexagon Report" }}</h3>
    <p>{{_ "Current number of hexagons:" }}{{number_of_hexagons}}</p>
</div>

To have this render in a particular Django template, both of the above files would need to be imported through <script> tags in the Django template. The relevant tags to add in this case would be:

<script src="{% url 'handlebars_templates' module_name='reports' %}"></script>
<script type="text/javascript" src="{% static 'js/coachreports/hexagon_report.js' %}"></script>

Note that for the Handlebars importing, only the folder name is necessary to be imported, not each individual template. It is also important that you do not place this script tag inside a Django-Compressor compress block.

Finally, to actually have this render on the page, we would need to have a Backbone Model that is able to fetch the data from an API endpoint on the server, and when the fetch is successfully completed, prompt the view to be created. Assuming we have a HexagonReportModel already defined, we could insert the following code into the template to initialize this report:

<script>
    $(function(){
        window.hexagonReportModel = new window.HexagonReportModel();
        hexagonReportModel.fetch().then(function(){
            window.hexagonView = new HexagonReportView({
                el: $("#student-report-container"),
                model: hexagonReportModel
            });
        });
    });
</script>

Line by line this means - $(function(){<code here>}); wait for the browser to finish rendering the HTML before executing the code inside this function. window.hexagonReportModel = new window.HexagonReportModel(); make a new instance of the HexagonReportModel. hexagonReportModel.fetch().then(function(){<code here>}); get the data for this particular model from the server, and when that has finished, then execute the code inside the function.

window.hexagonView = new HexagonReportView({
    el: $("#student-report-container"),
    model: hexagonReportModel
});

make a new instance of the HexagonReportView. This will automatically call initialize and so the view will render. In addition, el: $("#student-report-container"), tells the view that it should set its subsection of the DOM to be the DOM element selected by $("#student-report-container") (i.e. the element with the id ‘student-report-container’), and model: hexagonReportModel tells it to set its ‘model’ attribute to the hexagonReportModel we instantiated and fetch before.

TL;DR (or 7 quick steps to creating a Backbone View in KA Lite)

1. Find the appropriate app folder inside KA Lite - inside <folder>/static/js/<folder>/ either create a folder for your Backbone files, or find an existing one with a name that fits.
2. Inside this folder either create or open views.js.
3. To start creating a view, type: var MyViewNameView = BaseView.extend({});
4. Define at least an initialize method, and a render method.
5. If you want a Handlebars template for your View, look inside <folder>/hbtemplates/ and either create a folder for your Handlebars templates, or find an existing one with a name that fits.
6. Inside this folder create a new file for your handlebars template mytemplatename.handlebars.
7. Add this to your View definition code (inside the curly braces and don’t forget commas to separate key/value pairs!): template: HB.template("<templatefolder>/mytemplatename").

Purpose and creation of Javascript Unit Tests in KA Lite

Purpose

Our Backbone Models and Views can end up having a lot of methods. It is important that all of those methods observe the correct input output characteristics. Hence it is important that we write tests that guarantee that our methods either take the correct input and produce the right output, or, as is often the case, produce the right side effects on models, views, or the DOM.

In pursuit of this lofty goal of having every method and object testable and tested, there will be some requirements of refactoring along the way. Some of the code that has already been written for the KA Lite project is not conveniently parcelled in such a way as to be conducive to testing individual components in an atomic fashion. In order to ensure that functionality does not break as a result, we have integration tests (which are currently only implemented using Selenium scripted by Python) - for now we are avoiding writing such integration tests in Javascript as well so as to avoid duplication.

Setting up your Test Environment

1. Install requirements:

   • install node if you don’t have it already.
   • install pip if you don’t have it already.

2. Install the dependencies listed in requirements.txt: pip install -r requirements.txt
3. Install the dependencies listed in packages.json: sudo npm install

Getting Your Javascript to be Testable in KA Lite

Before you can test your javascript, it must be capable of being bundled in such a way that django-compress (the asset compression package we use) is able to write it to a Javascript file which can then be loaded by the Javascript test runner, karma.

In order to make this happen, use compression tags around blocks of Javascript script imports inside django templates for example, from learn.html:

{% compress js file learnjs %}
<!--[if !IE]> -->
<script src="{% static "video-js/video.js" %}"></script>
<script src="{% static "video-js/video-speed.js" %}"></script>
<script>
    _V_.options.flash.swf = window.flash_swf;
</script>
<!-- <![endif]-->
<script src="{% static "soundmanager/soundmanager2-nodebug-jsmin.js" %}"></script>

<script src="{% static 'js/distributed/content/models.js' %}"></script>
<script src="{% static 'js/distributed/content/views.js' %}"></script>

<script src="{% static 'js/distributed/video/models.js' %}"></script>
<script src="{% static 'js/distributed/video/views.js' %}"></script>

<script src="{% static 'js/distributed/audio/views.js' %}"></script>

<script src="{% static 'js/jquery.slimscroll.min.js' %}"></script>
<script src="{% static 'js/distributed/topics/models.js' %}"></script>
<script src="{% static 'js/distributed/topics/views.js' %}"></script>
<script src="{% static 'js/distributed/topics/router.js' %}"></script>

{% endcompress %}

You will also need to inclue the tag {% load compress %} at the top of a template in order to make use of the compress template tag.

Let’s examine the important details of {% compress js file learnjs %} - the compress tag name is followed by the kind of file being compressed (js), then two optional parameters. The first tells django-compress to compress the assets to a separate file (rather than rendering the concatenated Javascript inline in the HTML), the second gives a name to the code block. This should be a unique name across the entire code base. At current there is no way to know what names have already been used, except by examining karma.conf.js in the root of the project.

The name of the block is important for making it available for Javascript testing - it needs to be manually added to the karma.conf.js here:

// list of files / patterns to load in the browser
files: [
  file_map['basejs'].slice(1),
  file_map['perseusjs_1'].slice(1),
  file_map['perseusjs_2'].slice(1),
  file_map['learnjs'].slice(1),
  file_map['pdfjs'].slice(1),
  // INSERT NEW JAVASCRIPT BUNDLES HERE
  '**/tests/javascript_unit_tests/*.js',
  'testing/testrunner.js'
],

So if you had created a new compression block called ‘exparrotshop’ then you would add the element file_map['exparrotshop'].slice(1) to the array.

Writing a Test

You are now ready to write a test. All Javascript unit tests live inside the appropriate app. For example, if you were writing a unit test for Javascript code for the coachreport app, you would put your test file in kalite/coachreports/tests/javascript_unit_tests/. Call your file the name of the Model, View, or Router you are testing, or use an existing test file if you are extending an already tested Model or View. For example, the Session Model test file is called:

session_model_test.js

Each test file should start with a definition statement:

module("Session Model Tests", {
  setup: function() {
    return this.sessionModel = new SessionModel();
  }
});

The text gives the name of the suite of tests you will be writing in this file. The setup method defines something that happens prior to every single test being run. this gets returned to every subsequent test as this also, so anything set as an attribute of this will be available inside each test.

After the module definition, you can define any number of tests. Here is a simple example:

test("Default values", function() {
  expect(2);

  equal(this.sessionModel.get("SEARCH_TOPICS_URL"), "");
  equal(this.sessionModel.get("STATUS_URL"), "");
});

This simple test is checking the default values for the Session Model defined during the setup method above. At the beginning of the test, we declare how many assertion statements will be made during the course of the test. Not specifying this number correctly will cause a failure. The tests are written in QUnit whose docs can be referred to for a complete set of assertions.

Running Tests

When you have written your tests, before you can run them, we need to bundle the Javascript for testing. In order to do this, from the root of the project run:

bin/kalite manage bundleassets

This will bundle all the django-compress tags and make concatenated files. It will also update the file_map that our Karma config uses to find these files. When this is complete, simply run:

karma start

This will run through all the Javascript tests and report on failures. N.B. Karma is often, and most helpfully, run in continuous integration mode - our code base does not currently suppor that, but hopefully will in the future.

Behavior-Driven Integration Tests

Part of our comprehensive testing intiative is to write better integration tests. The goals are to:

1. Stop using browser driven integration tests as unit tests. (Such slow…)
2. Have robust integration tests that don’t fail randomly.
3. Use behavior-driven tests to clarify design goals of features.

We’re using behave 1.2.4 to run our integration tests. Behavior driven tests are specified using the Gherkin specification language, and then behave builds a test suite from step implementations that are directly mapped to clauses from the Gherkin specification.

Running the integration tests

To get the dependencies run `pip install -r dev_requirements.txt`. This should install the correct version of behave. Selenium is also required but is currently included in our python-packages directory.

To run the tests simply run `bin/kalite manage test` just like you used to. This will automatically search out tests using both the unit test framework and the behave framework. You can specify apps, but right now there’s no way to just run integration tests.

Running a specific test

If you want to run for instance the set of tests in kalite/distributed/features/content_rating.feature, use this command, applying the app label distributed and the name of the feature content_rating:

bin/kalite manage test distributed.content_rating --bdd-only

Anatomy of the integration tests

The test command will look inside each app for a `features` directory. Inside that directory should be one or more `[name].feature` files written in the Gherkin specification language. See the behave docs for more details on Gherkin, or look in the `control_panel` app, where your humble author has attempted to provide some examples.

The test runner will parse the `.feature` files and attempt to build a test suite from step specifications found in any python files (the name is irrelevant) in the `steps` subdirectory. There is a 1-to-1 mapping between the clauses you write in the Gherkin specification and the steps you implement, so it can save you time to reuse clauses. Steps can also be templated to match clauses that follow a pattern.

You can also set up the test environment at key stages in the testing process by writing hooks in an `environment.py` file in the `features` directory. In the `control_panel` example, the `before_feature` function is defined to log the testing user in as an admin before each feature tagged with the `@as_admin` tag in the specification. In `testing/base_environment.py`, the `before_all` and `after_all` hooks are defined to set up a Selenium WebDriver instance on the context object that is passed around by the test runner. This file is intended to be used as a base for all the integration tests, so if there is some setup common to all integration tests then put it there. You can then import those functions in the `environment.py` of specific apps, and extend or overwrite as necessary.

Finally, in `testing/behave_helpers.py` you’ll find various functions that should be generally useful for all integration tests. If you find yourself wishing you had a nice useful function, add it here. In order to avoid reproducing functionality while we phase out the old integration tests, if some functionality already exists in the form of a mixin, you should import it into that file and wrap it in a new function. Be very reticent about importing mixin code! A good rule of thumb is to glance at how something is implemented in the mixins first, and only import it if it’s not trivial to reproduce. Only re-write if there’s no chance of the new code producing an error! The main goal is to avoid maintaining two sets of code.

Suggested workflow for writing new features

Ideally you should:

1. Specify your integration tests.
2. Write failing steps.
3. Write code that makes your tests pass.

In practice, at least try to specify the tests first. Then you can seek out assistance implementing the steps.

Selenium gotchas (aka race conditions)

Finding elements on the page can be subject to race conditions if the page is not yet completely loaded, or if the DOM changes in response to AJAX stuff. Selenium pprovides methods for finding elements with and without explicit waits. When in doubt, use a wait. If your app is AJAX-y, write testable code by putting in events or flags that Selenium can explicitly wait for. The Selenium `get` method of browsing will wait for the page to fully load. Do not assume that following links using e.g. the `click` method will wait for the page to load – it does not. To summarize:

1. Incorporate explicit flags in your code that Selenium can use in waits.
2. Don’t use unsafe methods that don’t wait unless you’re 100% certain there’s no possibility for a race condition.

Developer Utility Commands

Django Management Commands

All Django management commands can be run by typing:

bin/kalite manage <command_name>

in the root directory of the KA Lite project.

generaterealdata

This function is designed to produce example user data for testing various front end functionality, such as coach reports and content recommendation.

It does take some shortcuts, and will not produce accurate answer data for exercises. This is a Django management command and can be run with the following command:

kalite manage generaterealdata

Logging

KA Lite application logs are stored in ~/.kalite/logs/. When going to daemon mode using kalite start, all outputs are additionally stored in ~/.kalite/server.log, which may contain more crash information for the last running instance.

In Python, please always log to logging.getLogger(__name__)! Fore more information on how logging is setup, refer to kalite.settings.base.LOGGING.

If you wish to view output from the server, you have a few options:

• Start the server with kalite start --foreground. This will start the server using CherryPy and a single thread, with output going to your terminal.
• Start the server in development mode kalite manage runserver --settings=kalite.project.settings.dev (this doesn’t start the job scheduler).

Inline help

In order to write inline help, refer to the file kalite/inline/narratives.py.

You don’t have to understand Python to write it really, just reuse the structure that’s already there.

Simple workflow

You should be able to write inline help for a page following these simple steps:

1. Clone the repository and setup a development environment following the steps in Getting started.

2. Open up the file kalite/inline/narratives.py

3. Add a new entry of a page you wish to write inline help for, for instance if the URL of the page is /learn, then you can add this entry:

   u'learn/?$': [
       {u'#css-id': [
           {u'step': 1},
           {u'text':
               _(u'This is the explanation for the user')}
       ]},
   ],
   

   Note

   The URL entry is a regular expression. You might want to implement variations of the URL in case it can be parameterized. Do not include

4. After changing the documentation, you can view the results by running the development server from command line:

   bin/kalite manage runserver --settings=kalite.project.settings.dev
   

Once you written inline help, go and open up a Pull Requestion for the develop branch on our Github page.

How to contribute to documentation

You can propose changes to the docs directly on Github (instructions below) or email your recommendations to info@learningequality.org.

To propose changes directly, you’ll need to create an account on github and open a pull request. This document assumes you are somewhat familiar with that process, and will not explain all the steps in detail. For full instructions on how to make a pull request, see Github’s help section.

Documentation development

1. Work from the develop branch.

2. From the base directory, the documentation can be found in the docs/ subdirectory. Specific pages of the docs are each associated with a different .rst file, potentially in a subdirectory of docs/.

3. The documentation is written in ReStructured Text format, so please see the primer!

4. After making your changes, try to build the docs to review them. This process can take some time, as an instance of the server and a browser may need to be started. To build the docs:

   pip install -r requirements_sphinx.txt  # To install software for building docs
   make docs
   

5. You can view the docs in a browser by opening docs/_build/html/index.html.

6. After you are satisfied with your changes push them to your fork of the ka-lite project, and then open a PR.

Screenshots

Screenshots are made automatically following the screenshots directives. They are stored in a folder docs/_static/, which is also sync’ed to Github.

To grab new screenshots, you have to have Firefox installed and run:

cd docs/
SPHINX_SS_USE_PVD=true make SPHINXOPTS="-D screenshots_create=1" html

Usage of screenshot Sphinx directive

Example code:

.. screenshot::
  :navigation-steps: LOGIN admin superpassword
  :focus: #id_username | Enter your username and password using this form!
  :class: screenshot

Warning

Read the following, but then read The thing about click before using the screenshot directive.

A screenshot directive has a number of required options:

• :user-role: which can be one of guest, learner, coach, or admin, and determines what kind of user is logged in for the screenshot.
• :url: which is the relative URL to take the screenshot at (or start a sequence of navigation actions to get to the page to take the screenshot at). Don’t use urls with UUIDs, as those are dependent on the database and we can’t guarantee what will be in the database for screenshot purposes.
• :navigation-steps: which is a sequence of steps that needs to be taken. See the docstring of _parse_nav_steps in screenshot.py file for specification. If you find yourself writing the same sequence of nav steps over and over again, possibly with minor variations, then we can write an alias for it as for LOGIN.

• :focus: which will highlight an element specified by jQuery-style selector (by giving it a nice red border) and optionally add a floating annotation box. Works like this:

  focus:the_selector | A nice little message that follows.

Just use arbitrary selection a la jQuery (so put a hash in front of IDs, etc). Whitespace can be included, e.g. li a.classname. Use the separator for annotations!

The thing about click

The :navigation-steps: option is meant to simulate user interaction for screenshots. Unfortunately, it can be dangerous!

Basically, if you use click on an element and want to use the result of the click, you can get into trouble if the result takes a long time.

For example, something like #link_to_another_page click that causes a page load is probably a mistake – the directive doesn’t know how long to wait for the page to load, and will probably throw an error.

Using click to interact with UI elements on the same page should be ok, as long as the result of interacting with the UI element happens really, really fast.

The rule of thumb is, if a click loads a page or waits for an AJAX result, think twice about using it.

Contribute to make KA Lite accessible to all

Why

Because inclusive design benefits all users!

• Ensuring that KA Lite is easily navigable with the keyboard will help blind users AND those who cannot use the mouse (or just prefer using the keyboard most of the time).
• Using the appropriate color contrast or making available a high contrast version of KA Lite content will benefit the users with low vision AND all those who need to use it in highly illuminated settings.
• Offering captions and transcripts for KA Lite video content will benefit auditory challenged audience AND improve its comprehension for everybody.
• Maintaining consistent structure, navigation and language will reduce cognitive load for all the audiences AND make it easier for KA Lite content to be localized.

How

For general introduction check the Accessibility resources, tools and tips on KA lite GitHub Wiki pages:

• Accessibility Resources (Articles & Links)
• Accessibility Resources (Tools)
• Accessibility Tips & Tricks

To make sure you catch the most common a11y pitfalls, use tota11y , an accessibility visualization toolkit made available by Khan Academy.

Using tota11y

tota11y is integrated into KA Lite that you cloned from GitHub and will be visible in all the pages of your development server IF you include DEBUG = True in your local settings (edit your ~/.kalite/settings.py file).

tota11y presents as a small button in the bottom left corner of the document you are viewing.

Once you press the button, it will open a menu of seven checkup-choices each of which you can activate by using the corresponding circle checkbox on the left. In the image bellow you can see the Headings activated that “annotates” all the <H> elements in the page and their issues.

This will allow you to keep correcting the annotated issues, and reload the page to check weather they are solved.

What can you check with tota11y

With tota11y you can easily visualize for:

• Inconsistent and nonconsecutive heading levels (find out more about the accessible headings)
• Insufficient contrast ratio (aim for 4.5 at least; you can use Color Contrast Tools linked in the Wiki)
• Unclear text links (consider making use of Bootstrap screen reader classes if necessary)
• Missing labels on form or button elements (good read about Forms & Labels)
• Images without an ALT attribute (always include the alternative text for images, but remember to tag the purely descriptive content accordingly)
• All the ARIA landmarks included in the page (reed more about ARIA landmark roles)

Tip

tota11y is an open source project made available by Khan Academy, remember to report any issues you may find on their GitHub page !

Translating KA Lite

We release a “content pack” for a language once a sufficient portion of the content (videos and user interface) have been translated.

There are two aspects to translation of KA Lite:

• Translating the KA content itself (dubbing videos, subtitling, and translating titles/descriptions). This is done through Khan Academy. Only videos that are included on official Khan Academy YouTube language channels, and mapped to their English counterparts in Khan Academy’s API, will be included in KA Lite.

• Translating the KA Lite interface text. For user interface translations, we use a website called CrowdIn. In order to contribute translations, follow the steps below:

  1. Sign up for the KA Lite Volunteer Translation Group.
  2. Create an account on CrowdIn, our online translations portal.
  3. Start contributing translations on CrowdIn! You will want to focus on the files for the version you’re targeting – for instance, to translate the strings for KA Lite 0.14, you should focus on translating strings in 0.14-django.po and 0.14-djangojs.po.

Creating new source translations

Facilitators of CrowdIn should do the following each time that a new major release approaches:

1. Navigate to the root of your ka-lite git checkout. Make sure your environment is activated.

2. Run:

   make msgids
   

3. After this, you should have updated files in locale/.

4. Commit the files to Github in a PR and have them merged. We track these changes in Git to ensure a transparent mechanism for changes.

5. Upload the files with their versioned file names to CrowdIn.

Legacy

Our translations have worked slightly differently since they were introduced in 0.11. On CrowdIn, we have older versions avaiable, for which 0.14 through to 0.16 all contain translation strings from the central server (the one running on hub.learningequality.org).

As of 0.17, we have started to maintain the English source messages in Git and will sync them to CrowdIn after each string freeze.

About KA Lite

Khan Academy’s core mission is to “provide a free world-class education for anyone anywhere”, and as over 60% of the world’s population is without access to the internet, primarily in the developing world, providing an alternative delivery mechanism for Khan Academy content is key to fulfilling this mission.

KA Lite is a lightweight Django web app for serving core Khan Academy content (videos and exercises) from a local server, with points and progress-tracking, without needing internet connectivity.

Translations

KA Lite is released in many languages, each with its own subset of Khan Academy contents translated: Polish, Georgian, German, Spanish, Xhosa, Indonesian, Burmese, Swahili, Tamil, Hindi, Portuguese (Brazilian and Portuguese), Bulgarian, Danish, Arabic, Bengali, Kannada, and French. See Adding Languages.

Documentation: This documentation is also available in French (PDF).

Get involved!

• Learn how you can contribute code on our KA Lite GitHub Wiki
• Report bugs by creating issues
• Read more about the project’s motivation at Introducing KA Lite, an offline version of Khan Academy.

Connect

• Community forums: community.learningequality.org
• IRC: #kalite on Freenode
• Twitter: @ka_lite
• Mailing list: dev@learningequality.org on Google Groups

Contact Us

Tell us about your project and experiences!

• Email: info@learningequality.org
• Add your project to the map: https://learningequality.org/ka-lite/map/

License information

The KA Lite sourcecode itself is open-source MIT licensed, and the other included software and content is licensed as described in the LICENSE file. Please note that KA Lite is not officially affiliated with, nor maintained by, Khan Academy, but rather makes use of Khan Academy’s open API and Creative Commons content, which may only be used for non-commercial purposes.