Installation Guide

git --version
# Should show: git version 2.x.x

git lfs version
# Should show: git-lfs/2.x.x

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Replace $USERNAME with your GitHub username
git clone [email protected]:$USERNAME/kolibri.git
cd kolibri

git lfs install

git config blame.ignoreRevsFile .git-blame-ignore-revs

git remote add upstream [email protected]:learningequality/kolibri.git
git fetch --all
git checkout -t upstream/develop

pyenv --version
# Should show: pyenv 2.x.x

# List available Python versions
pyenv install --list | grep "^  3\.(9|10|11|12|13)\."

# Install a compatible version (e.g., 3.9.9)
pyenv install 3.9.9

# Set it as global default (optional)
pyenv global 3.9.9

# Verify
python --version
# Should show: Python 3.9.9

# Create virtualenv named 'kolibri-py3.9'
pyenv virtualenv 3.9.9 kolibri-py3.9

# Activate it
pyenv activate kolibri-py3.9

# Your prompt should now show: (kolibri-py3.9)

# To deactivate later
pyenv deactivate

# Create virtual environment
python3 -m venv kolibri-env

# Activate it
source kolibri-env/bin/activate  # Linux/macOS
# kolibri-env\Scripts\activate   # Windows (not recommended)

# Deactivate when done
deactivate

# Install virtualenvwrapper
pip install virtualenvwrapper

# Add to ~/.bashrc
export WORKON_HOME=$HOME/.virtualenvs
source /usr/local/bin/virtualenvwrapper.sh

# Create and activate environment
mkvirtualenv kolibri-py3.9
workon kolibri-py3.9

export KOLIBRI_RUN_MODE="dev"

export KOLIBRI_HOME="$HOME/.kolibri-dev"

# Core dependencies
pip install -r requirements.txt --upgrade

# Development dependencies (required)
pip install -r requirements/dev.txt --upgrade

# Install Kolibri in editable mode
pip install -e .

# Testing dependencies
pip install -r requirements/test.txt --upgrade

# Documentation building
pip install -r requirements/docs.txt --upgrade

# PostgreSQL support (optional, SQLite is default)
pip install -r requirements/postgres.txt --upgrade

django==3.2.25              # Web framework
djangorestframework==3.14.0  # REST API
morango==0.8.6               # Sync framework
le-utils==0.2.13             # Learning Equality utilities
cheroot==10.0.1              # WSGI server
requests==2.27.1             # HTTP library
django-filter==21.1          # API filtering

pre-commit     # Git hooks for code quality
tox            # Multi-environment testing
ipdb           # Enhanced debugger
nodeenv        # Node.js environment manager

# Ensure Python virtualenv is active
pyenv activate kolibri-py3.9  # or your virtualenv name

# Install Node.js 20.19.0
nodeenv -p --node=20.19.0

# Verify installation
node --version
# Should show: v20.19.0

npm install -g pnpm

# Verify installation
pnpm --version
# Should show: 10.4.1 or similar

# From the kolibri/ directory
pnpm install

// Key frontend dependencies (from package.json)
{
  "vue": "2.7.16",
  "vuex": "...",
  "webpack": "^5.104.0",
  "jest": "^30.2.0",
  "@testing-library/vue": "^5",
  "babel-jest": "^30.2.0"
}

pre-commit install

# Run all checks on all files
pre-commit run --all-files

git add my_file.py
git commit -m "Add new feature"
# Pre-commit runs automatically...
# If checks fail, files are auto-fixed
# Review changes, then:
git add my_file.py  # Stage auto-fixes
git commit -m "Add new feature"  # Commit succeeds

kolibri manage migrate

Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK
  Applying kolibriauth.0001_initial... OK
  Applying kolibriauth.0002_facilitydataset... OK
  ...
  Applying logger.0015_auto_20230615_2045... OK

pnpm run devserver

pnpm run devserver-hot

pnpm run python-devserver

pnpm run watch

# Build all frontend assets
pnpm run build

# Start production server
kolibri start

kolibri stop

xcode-select --install

# Install Homebrew if not present
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install build dependencies
brew install openssl readline sqlite3 xz zlib

sudo apt install build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev curl \
  libncursesw5-dev xz-utils tk-dev libxml2-dev \
  libxmlsec1-dev libffi-dev liblzma-dev

# One-time: build base image
make docker-build-base

# Start devserver in container
make docker-devserver

# Generate .whl and .pex files in dist/
make docker-whl

pyenv activate kolibri-py3.9
pip install -e .

# Reinstall nodeenv
nodeenv -p --node=20.19.0

npm install -g pnpm

# Reinstall JavaScript dependencies
rm -rf node_modules
pnpm install

export NODE_OPTIONS="--max-old-space-size=4096"
pnpm run build

pip install --upgrade pre-commit
pre-commit clean
pre-commit install

# Find KOLIBRI_HOME
kolibri manage shell -c "from kolibri.utils.conf import KOLIBRI_HOME; print(KOLIBRI_HOME)"

# Backup if needed, then remove
rm $KOLIBRI_HOME/db.sqlite3

# Recreate
kolibri manage migrate