Kolibri on Ubuntu 24.04 on Azure User Guide

Overview

Kolibri, from the non-profit Learning Equality, is an open-source learning platform built for places where connectivity is scarce, expensive or unreliable. One Kolibri server holds a library of open educational content - videos, exercises, documents and interactive HTML5 activities - imported from the Kolibri Studio catalogue or from a local drive, and serves it over the network to any device with a browser. Learners work through lessons and quizzes and their progress is recorded even when the server has no internet at all; coaches group learners into classes, assign material and follow progress reports; administrators manage the facility, its users and which channels are available.

The cloudimg image installs Kolibri 0.19.5 from the official upstream wheel into a dedicated Python virtualenv, runs it as an unprivileged service account, and pins both of the ports Kolibri serves so they can be allowed through a cloud network security group. There is no default login: the device ships deliberately unprovisioned and the sole administrator account, along with the application's signing key, is generated on the first boot of every VM and recorded in a root-only file. Backed by 24/7 cloudimg support.

What is included:

• Kolibri 0.19.5 installed from the official upstream PyPI wheel, pinned so it never silently upgrades
• The learner, coach and administrator web interface on port 8080, and Kolibri's separate sandboxed origin for interactive HTML5 and EPUB content on port 8081
• A per-VM administrator account created on first boot, with a random password recorded in a root-only file, so every VM is secured independently and no default credential exists
• A per-VM application signing key, replacing the single published key that upstream Kolibri uses on every installation, so signed values from one VM are worthless on another
• Anonymous account sign-up and password-free learner sign-in both disabled by default
• Kolibri running as the unprivileged kolibri system account under a kolibri.service systemd unit that will not start until first-boot provisioning has completed
• Only 22/tcp (SSH), 8080/tcp and 8081/tcp exposed
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting size. Size the OS disk for the content you intend to import - Kolibri channels range from tens of megabytes to several gigabytes each. NSG inbound: allow 22/tcp from your management network, and 8080/tcp and 8081/tcp from the devices your learners will use. Kolibri serves plain HTTP; for production, put it behind your own domain and TLS.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Kolibri by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22), then add 8080 and 8081 after deployment. Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name kolibri \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name kolibri --port 8080 --priority 1010
az vm open-port --resource-group <your-rg> --name kolibri --port 8081 --priority 1011

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm Kolibri is running

On the first boot of your VM, kolibri-firstboot.service generates this VM's application signing key and administrator password, provisions the device and its facility, and only then releases kolibri.service. Both units are enabled, so Kolibri starts automatically on every later boot.

systemctl is-active kolibri.service kolibri-firstboot.service

Both report active. Kolibri initialises its caches on the first request, so allow a few seconds after the VM finishes provisioning before the interface answers.

Step 5 - Retrieve your per-VM administrator credentials

The administrator account is created uniquely on the first boot of your VM and its password is written to a root-only file. Confirm the file exists (it is 0600, root-only):

sudo ls -l /root/kolibri-credentials.txt

Then read it to get your credentials:

sudo cat /root/kolibri-credentials.txt

The file contains KOLIBRI_URL (the address to browse to), KOLIBRI_ADMIN_USERNAME, KOLIBRI_ADMIN_PASSWORD and KOLIBRI_FACILITY (the name of the facility created for you). Store them somewhere safe.

The per-VM application signing key lives alongside it, readable only by root and the kolibri service account:

sudo ls -l /etc/kolibri/secret_key

Step 6 - Confirm the pinned release and the listening ports

The appliance is pinned to Kolibri 0.19.5 so it never silently upgrades:

sudo kolibri --version

Kolibri publishes a small device-information endpoint that needs no authentication:

curl -s http://localhost:8080/api/public/info/

Kolibri listens on two ports - 8080 for the web interface and 8081 for the sandboxed origin that serves interactive HTML5 and EPUB content. Both must be reachable by your learners, or interactive content will not render:

sudo ss -tlnp | grep -E ':(8080|8081) ' | awk '{print $1, $4}'

You can also ask Kolibri which URLs it is serving on:

sudo kolibri status

Step 7 - Confirm administration is locked down

The device administration API is refused to anonymous callers. Only the public device-information endpoint answers without a session:

for u in / /api/public/info/ /api/device/deviceinfo/; do
  printf '%-26s HTTP %s\n' "$u" \
    "$(curl -s -o /dev/null -w '%{http_code}' http://localhost:8080$u)"
done

/ returns 302 (a redirect to the sign-in page), /api/public/info/ returns 200, and /api/device/deviceinfo/ returns 403 because no session is attached. The image also ships with no swap, as Azure requires:

sudo swapon --show | wc -l

Step 8 - Sign in to Kolibri

Browse to http://<vm-public-ip>:8080/ and sign in with the username and password from Step 5. Kolibri's sign-in is a two-step form: enter the username, choose Next, then enter the password. The facility name created for your VM is shown above the form.

Step 9 - Import your first content channel

Kolibri ships with no learning content - you choose what to bring in. Signed in as the administrator, go to Device -> Channels and select Import. Kolibri offers three sources: the online Kolibri Studio catalogue, another Kolibri server on your network, and an attached drive. Choosing Kolibri Studio lists the full public catalogue of open educational channels, each with its language, version and description, and lets you take a whole channel or pick individual topics within it.

Downloads run in the background and are resumable, so a large channel can be imported over an intermittent link. Content is stored under /var/lib/kolibri/content on the OS disk - size the disk for the channels you plan to keep, and use Device -> Settings -> Primary storage location if you want to add another location later.

For sites with no internet at all, export the channels you want onto a USB drive from a connected Kolibri server, then choose Attached drive or memory card on this VM.

Step 10 - Explore the library as a learner

The Learn section is what your learners see. It lists the channels installed on this server, and - while the VM still has internet - the wider Kolibri Library, so you can browse what is available before importing it.

Step 11 - Add learners, coaches and classes

Under Facility -> Users you manage everyone on this server. A fresh VM has exactly one account - the super administrator created for you on first boot. Use New user to add learners, coaches and additional administrators, then group them into classes under Facility -> Classes so coaches can assign lessons and quizzes drawn from your imported channels.

Anonymous access

Kolibri is designed so learners can browse content without an account, and the sign-in page therefore offers Explore without account. This is upstream Kolibri's default and the image keeps it, because it is a deliberate part of how the product is used in schools and community sites. It exposes only the content you have chosen to import - never the administration interface, never user records - and a freshly deployed VM has no content at all until you import some.

If your VM is reachable from the public internet and you want every visitor to sign in first, turn it off in Device -> Settings: choose Learners must sign in to explore resources and select Save changes. Two related protections are already on by default in this image:

• Anonymous visitors cannot create their own accounts - self-sign-up is disabled
• Learner accounts cannot be created without a password

Both are under Facility -> Settings if you later want to relax them for a closed network.

Maintenance

• Administrator credentials: the per-VM administrator account is in /root/kolibri-credentials.txt. Change the password from the user menu in the web interface after your first sign-in, and keep the file for the record of which facility was created.
• Content: imported channels live under /var/lib/kolibri/content. Back the VM up by snapshotting the OS disk, or re-import channels from Kolibri Studio - they are reproducible.
• Data: learner accounts, class membership, lesson assignments and progress records live in the SQLite database at /var/lib/kolibri/db.sqlite3. Stop Kolibri before copying it: sudo systemctl stop kolibri, copy, then sudo systemctl start kolibri.
• Service: manage Kolibri with sudo systemctl <status|restart|stop> kolibri. Run administrative commands with sudo kolibri manage <command> - the wrapper loads the appliance environment and drops to the kolibri service account for you, so nothing is left owned by root.
• Custom domain and TLS: Kolibri serves plain HTTP on ports 8080 and 8081. For production, put a TLS reverse proxy (Caddy, or nginx with certbot) in front of both ports for your own domain. Keep the two origins distinct - Kolibri deliberately serves interactive content from a separate origin so embedded activities are sandboxed away from the application.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.