Skip to content

Latest commit

 

History

History
149 lines (119 loc) · 5.2 KB

local_dev_host.md

File metadata and controls

149 lines (119 loc) · 5.2 KB
Raw

Local development instructions: Run everything on your host machine

This guide will walk through setting up Kolibri Studio for local development, where you'll run Studio's Python apps and all of Studio's services on your host machine, without the need for docker.

Prerequisites

Install system dependencies and services

Studio requires some background services to be running:

  • Minio - a local S3 storage emulation
  • PostgreSQL - a relational database
  • Redis - a fast key/value store useful for caching

Ubuntu or Debian

# Install packages
sudo apt-get install -y python-tk \
    postgresql-server-dev-all postgresql-contrib postgresql-client postgresql-12 \
    ffmpeg libmagickwand-dev redis-server wkhtmltopdf

# Install minio
wget https://dl.minio.io/server/minio/release/linux-amd64/archive/minio.RELEASE.2020-06-01T17-28-03Z -O bin/minio
sudo chmod +x bin/minio

Mac OS

brew install postgresql@12 redis ffmpeg imagemagick@6 gs
# note, this version of minio may not be compatible with Studio
brew install minio/stable/minio
brew link --force postgresql@12
brew link --force imagemagick@6

Windows

Windows is no longer supported due to incompatibilities with some required packages.

Set up the database

Make sure postgres is running:

service postgresql start
# alternatively: pg_ctl -D /usr/local/var/postgresql@12 start

Start the client with:

sudo su postgres  # switch to the postgres account
psql  # mac: psql postgres

Create a database user with username learningequality and password kolibri:

CREATE USER learningequality with NOSUPERUSER INHERIT NOCREATEROLE CREATEDB LOGIN NOREPLICATION NOBYPASSRLS PASSWORD 'kolibri';

Create a database called kolibri-studio:

CREATE DATABASE "kolibri-studio" WITH TEMPLATE = template0 ENCODING = "UTF8" OWNER = "learningequality";

Press Ctrl+D to exit the psql client. Finally

exit  # leave the postgres account

Build your python virtual environment

To determine what version of Python studio needs, you can check the runtime.txt file:

$ cat runtime.txt
# This is the required version of Python to run Studio currently.
# This is determined by the default Python 3 version that is installed
# inside Ubuntu Bionic, which is used to build images for Studio.
# We encode it here so that it can be picked up by Github's dependabot
# to manage automated package upgrades.
python-3.10.13

So to install python 3.10.13 through pyenv and set up a virtual environment:

pyenv install 3.10.13
pyenv virtualenv 3.10.13 studio-py3.10
pyenv activate studio-py3.10

Now you may install Studio's Python dependencies:

pip install -r requirements.txt -r requirements-dev.txt

To deactivate the virtual environment, when you're finished developing on Studio for the time being:

pyenv deactivate

A note about psycopg2

The packages postgresql-12, postgresql-contrib, and postgresql-server-dev-all are required to build psycopg2 python driver.

A note about dependencies on Apple Silicon M1+

If you run into an error with pip install related to the grcpio package, it is because it currently does not support M1 with the version for grcpio Studio uses. In order to fix it, you will need to add the following environmental variables before running pip install:

export GRPC_PYTHON_BUILD_SYSTEM_OPENSSL=1
export GRPC_PYTHON_BUILD_SYSTEM_ZLIB=1
export CFLAGS="-I/opt/homebrew/opt/openssl/include"
export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"

Install frontend dependencies

Ready the version of node.js supported by Studio, and install yarn.

volta install node@16
volta install yarn

Then you can install frontend dependencies

yarn install

Run the services

Having installed all the necessary services, initialized your python virtual environment, and installed yarn, you're now ready to start the services. Generally speaking, you'll want to open a separate terminal/terminal-tab to run the services. The following will ensure all services are started, in addition to starting the celery workers service:

yarn run services

Initializing Studio

With the services running, in a separate terminal/terminal-tab, we can now initialize the database for Studio development purposes. The command below will initialize the database, in addition to adding a user account for development:

yarn run devsetup

Running the development server

With the services running, in a separate terminal/terminal-tab, and the database initialized, we can start the dev server:

yarn run devserver:hot  # with Vue hot module reloading
# or
yarn run devserver  # without hot module reloading

Either of the above commands will take a few minutes to build the frontend. When it's done, you can sign in with the account created by the yarn run devsetup command: