Install Kolibri

See the Kolibri changelog here to review specific changes in each version of Kolibri. Documentation for previous Kolibri versions are available here.

Hardware requirements

To install Kolibri on a device that will act as a server, check the hardware requirements first, and then follow the procedure for the operating system on your device.

Tip

Below you will find general recommendations regarding hardware requirements to run Kolibri. To read more detailed information and find out examples of hardware setups that have been implemented by our users, download the full Kolibri Hardware Guide and examples of Hardware Configurations for Kolibri (PDF documents).

Servers

Minimum hardware requirements to run Kolibri as a server:

  • 500 MB RAM (1 GB recommended)
  • 500 MHz CPU (1 GHz recommended)
  • Hard drive space depends on the size of the content channels you intend to import from Kolibri Studio or a local storage device.

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

Clients

Very old desktops and very low-power computers can be used as client devices to access Kolibri. For instance, some implementations 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 implement Kolibri, usually it’s not necessary to scale your hardware. The main requirement is that your system needs a video card and driver that can play the videos.

Windows

Compatibility

  • Supported: Windows 7, 8.1 and 10, with IE 11+, Chrome or Firefox
  • Not supported: Windows XP cannot be used to install Kolibri server, but could potentially work as a client device if the browsers are as up-to-date as possible.

Install

  1. Download the Kolibri Windows installer.
  2. Double-click the downloaded .exe file.
  3. Select the language for the installation.
  4. Python 3 installer is included, confirm the installation or the upgrade to proceed.
  5. Follow the rest of the instructions in the Kolibri installation setup wizard.
  6. Once the installation finishes, Kolibri will auto-start and open in the default browser on your computer at http://127.0.0.1:8080. This may take a moment, so please be patient.
  7. Proceed with the Initial Setup of your facility.

Warning

Windows firewall will prompt you to allow the Python process needed to run Kolibri. Click Allow access to accept and proceed.

Allow the Python process needed to run Kolibri.

Allow the Python process needed to run Kolibri.

Uninstall

  1. Open the Windows Control Panel.
  2. Select Programs and Features option.
  3. Select Kolibri from the list of programs.
  4. Click the button Uninstall/Change and follow the instructions.

Upgrade

To upgrade Kolibri, follow these steps.

  1. Download the new version of Kolibri Windows installer.
  2. Double-click the downloaded .exe file.
  3. Follow the instructions in the installation wizard window.
  4. Once the installation of the upgrade is finished, Kolibri will auto-start and open in the default browser on your computer.
  5. Go explore the new and improved Kolibri features!

Debian/Ubuntu

Compatibility

Debian/Ubuntu 14.04, 16.04 and up - anything that’s not end-of-life

Install from PPA repository

Use the following commands in Terminal to add the PPA and install Kolibri:

sudo apt-get install software-properties-common python-software-properties
sudo add-apt-repository ppa:learningequality/kolibri
sudo apt-get update
sudo apt-get install kolibri

Install from a .deb file

The advantages of downloading a .deb file is the portability: you can copy the file from device to device and install Kolibri without internet access.

  1. Download the latest Kolibri .deb installer, or have it copied to your local drive.

  2. Run this command from the location where you downloaded the DEB file:

    sudo dpkg -i kolibri-installer-filename.deb
    
  3. Wait for the installation to finish and run this command to start Kolibri:

    kolibri start
    

    Note

    If you choose to install Kolibri as a system service, you will not need to start it manually.

  4. When the command finishes, open the default browser at http://127.0.0.1:8080 and proceed with the Initial Setup of your facility.

Uninstall

  • Open Software on Ubuntu and locate the Kolibri. Press Remove.
  • Or from the command line: sudo apt-get remove kolibri.

Upgrade

When you use the PPA installation method, upgrades to newer versions will be automatic, provided there is internet access available.

To upgrade Kolibri on a Debian device without internet access, bring the updated .deb file and follow the same steps as in Install from a .deb file.

Changing the owner of Kolibri system service

The system service is the script that runs Kolibri in the background when your system boots on Debian-based distributions.

You may need to change the system service to run with the permissions of a different user account. Prior to v0.10, kolibri user account was the owner of the system service, while from v0.10 and later, desktop user’s account is preferred, in order for Kolibri to access the local USB storage.

To change the system service owner, you need to change the configuration of the system service: move the .kolibri data folder (containing channels, databases etc.), and assign owner permissions to the new user. Follow these steps.

# Stop Kolibri
sudo systemctl stop kolibri
# Move data to your desktop user:
sudo mv /var/kolibri/.kolibri /home/$USER/.kolibri
# Change ownership
sudo chown -R $USER /home/$USER/.kolibri
# Change the username configuration
sudo sh -c 'sudo echo -n $USER > /etc/kolibri/username'
# Start Kolibri again
sudo systemctl start kolibri

Note

Replace the $USER in commands above with the name of the user you wish to be the new Kolibri system service owner.

Raspbian

Compatibility

Kolibri works well on Debian-based distributions for Raspberry Pi, such as Raspbian, and has been tested on RPi 3 models.

Install

  1. Running add-apt-repository as shown in the PPA instructions does not work. Instead, run:

    sudo apt install dirmngr
    sudo su -c 'echo "deb http://ppa.launchpad.net/learningequality/kolibri/ubuntu xenial main" > /etc/apt/sources.list.d/learningequality-ubuntu-kolibri-xenial.list'
    sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys DC5BAA93F9E4AE4F0411F97C74F88ADB3194DD81
    sudo apt update
    sudo apt install kolibri
    
  2. Kolibri does not start after installation. This is because python3-cffi is outdated on Raspbian. Upgrade it like this:

    sudo apt install libffi-dev
    sudo pip3 install pip --upgrade
    sudo pip3 install cffi --upgrade
    sudo systemctl start kolibri
    
  3. When the command finishes, open the default browser at http://127.0.0.1:8080 and proceed with the Initial Setup of your facility.

Note

The following issues are quite common on a Raspberry Pi:

  • The time isn’t set properly and you will have errors downloading software. For instance, SSL certificates for online sources will fail to validate. Ensure that you have the right timezone in /etc/timezone and that the clock is set properly by running sudo ntpd -gq.

  • You run out of storage space. If you have a USB source for additional storage, do something like this:

    # Stop kolibri
    sudo systemctl kolibri stop
    # Move its data
    sudo mv /var/kolibri/.kolibri /your/external/media/kolibri_data
    # Ensure that the kolibri system service user owns the folder
    sudo chown -R `cat /etc/kolibri/username` /your/external/media/kolibri_data
    # Restore the original location with a symbolic link
    sudo ln -s /your/external/media/kolibri_data /var/kolibri/.kolibri
    # Start kolibri
    sudo systemctl kolibri start
    
  • Loading channels can take a long time on a Raspberry Pi. When generating channel contents for Khan Academy, the step indicated as “Generating channel listing. This could take a few minutes…” could mean ~30 minutes. The device’s computation power is the bottleneck. You might get logged out while waiting, but this is harmless and the process will continue. Sit tight!

Uninstall

From the command line: sudo apt-get remove kolibri.

Upgrade

When you use the PPA installation method, upgrades to newer versions will be automatic, provided there is internet access available.

Other Linux & MacOS

Compatibility

  • MacOS: 10.6+, all browsers supported
  • Linux: Any system with Python 2.7, all browsers supported

Install

To install Kolibri on Linux distributions other than Debian, as well as on MacOS, you can use generic installation with pip install command, or follow these steps to run Kolibri with the PEX package.

  1. Download the Kolibri PEX installer.

  2. Make sure to open the Terminal where you downloaded the PEX file. For example, if you saved it in the Downloads folder, type this when you open the Terminal, and press Enter:

    cd Downloads
    
  3. Type the following commands next (press Enter after each one).

    chmod +x kolibri-installer-filename.pex
    ./kolibri-installer-filename.pex start
    

    Warning

    Make sure to substitute the kolibri-installer-filename.pex with the exact name of the file you downloaded in both commands. For example, if the name of the downloaded file is kolibri-v0.10.0.pex, type that instead of kolibri-installer-filename.pex.

  4. When the command finishes, open the default browser at http://127.0.0.1:8080 and proceed with the Initial Setup of your facility.

Uninstall

  1. Delete the PEX file.
  2. Delete the ./kolibri folder in your user’s Home directory if you want to completely remove all the Kolibri files and content channels you imported.

Upgrade

To upgrade Kolibri, follow these steps.

  1. Download the new version of Kolibri PEX installer.
  2. Start Kolibri as during the first install.
  3. Go explore the new and improved Kolibri features!

Python pip package

You can install Kolibri as a standard package from PyPi (works on Mac, Windows, and Linux) using this command:

pip install kolibri

Initial Setup

To do the initial setup of your Kolibri facility after the installation, follow these steps.

Note

You need to do the initial setup only once, the first time you start Kolibri after the installation.

  1. Select the default language for Kolibri.

    Select the default Kolibri language.

    Select the default Kolibri language.

    Warning

    The default language configured for content in your browser preferences might override the language you choose in this step. To ensure that Kolibri displays in the desired language, make sure to configure it as default in the browsers of all the devices that will be used to view Kolibri content.

  2. Name your Facility. A “Facility” is the location where you are installing Kolibri, such as a school or a training center.

    Select the name for the facility where Kolibri is running.

    Select the name for the facility where Kolibri is running.

  3. Choose a Facility setup. Click the link More information about these settings for more details about user permissions for each setup type.

Facility type Users
Self-managed
For parent-child learning, homeschooling
or supplementary individual learning.
  • Guests can create their own accounts.
  • Users can edit their account information.
Admin managed
For schools and other formal learning contexts.

  • Admins must create all user accounts.
  • Users can sign in without password.
  • Users cannot edit their account information.
Informal and personal use
For libraries, orphanages, correctional
facilities, youth centers, computer labs,
and other non-formal learning contexts.
  • Guests can create their own accounts.
  • Users can edit their account information.
Choose a Facility setup.

Choose a Facility setup.

View the Facility setup details.

View the Facility setup details.

  1. Create your Admin account. This Admin user will be a Superuser able to manage all the device content, and all the rest of the facility users and their permissions.

    Select the username and password for the facility Superuser.

    Select the username and password for the facility Superuser.

    Tip

    Make sure to save these superuser credentials in a safe place!

Once you finish the initial setup, proceed to import some content, and create users (if you chose the Admin-managed facility setup). Make sure to check how to configure other computers in the network to access Kolibri.