Getting started

Tip

Find additional knowledge in Getting Started on our Github Wiki.

KA Lite is discontinued and thus contains several legacy and end-of-life. It is recommended that you set up your development environment in a virtual machine, for instance using Virtualbox.

Ubuntu 18.04 LTS

To avoid walking down an uncertain path when you set up this project, consider using Ubuntu 18.04 LTS in a virtual machine.

These steps are largely based on the Dockerfile from the repository’s root.

  1. Install prerequisits. The development environment needs Python 2.7, pip and curl.

    sudo apt install python2.7 curl python3-pip git make
    
  2. Add the nodejs 6.x repo and install it.

    # Get the key and add the repo
    wget -qO- https://deb.nodesource.com/gpgkey/nodesource.gpg.key | sudo apt-key add -
    echo 'deb https://deb.nodesource.com/node_6.x bionic main' | sudo tee /etc/apt/sources.list.d/nodesource.list
    
    # Overrule the newer version shipped by Ubuntu
    printf "Package: *\nPin: origin deb.nodesource.com\nPin-Priority: 600" | sudo tee /etc/apt/preferences.d/nodejs
    
    # Update and install
    sudo apt update
    sudo apt install nodejs
    
  3. Fork the project on github, clone the git repository

    git clone git@github.com:USERNAME/ka-lite.git cd ka-lite

  4. Create a virtual environment and activate it:

    pip3 install virtualenv
    virtualenv -p python2.7 venv
    
    # Activate the virtualenv - you need to do that everytime you open a new command line
    source venv/bin/activate
    
  5. Install a development version of KA Lite inside the virtual environment:

    pip install -e .
    
  6. Install development requirements:

    # Development
    pip install -r requirements_dev.txt
    # Building docs
    pip install -r requirements_sphinx.txt
    # Test requirements
    pip install -r requirements_test.txt
    
  7. Install JavaScript (nodejs) libraries and build them:

    make assets
    
  8. You are now ready to run KA Lite. You can run a foreground version of the HTTP server like this:

    kalite start --foreground
    
  9. Run the setup, which will bootstrap the database:

    .. code-block:: bash
    

    kalite manage setup

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

    .. code-block:: bash
    

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

Tip

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.

Every time you work on your development environment, remember to switch on your virtual environment with source venv/bin/activate. You can use virtualenvwrapper for more convenient ways of managing virtual envs.

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

Ensure that you install the test requirements:

pip install -r requirements_test.txt

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