Skip to main content
This guide will help you set up a local development environment for Kolibri Studio using Docker.
If you are developing on Windows, it is recommended to use WSL (Windows Subsystem for Linux). See the WSL setup guide in the source repository for detailed instructions.

​
Prerequisites

Before you begin, you’ll need to install the following tools:
  • Docker and Docker Compose - for running services (PostgreSQL, Redis, Minio)
  • Python 3.x - for the Django backend
  • Node 20.x - for the Vue.js frontend
  • Volta - for managing Node.js and pnpm versions
  • uv - for Python package management
  • pnpm - for frontend package management
For detailed instructions on installing and configuring Volta and uv, see the Prerequisites section in the host setup guide in ~/workspace/source/docs/local_dev_host.md.

​
Set Up Python Environment

1

Create virtual environment

Create and activate a Python virtual environment:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
2

Install Python dependencies

Install Studio’s Python dependencies:
pip install -r requirements.txt
pip install -r requirements-dev.txt
If you encounter errors with the grpcio package on Apple Silicon, set these environment 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

Studio requires Node 20.x and uses pnpm as the package manager. With Volta installed, run: 
corepack use pnpm  # or: volta install pnpm
pnpm install

​
Start Services

Studio requires several background services:
  • Minio - local S3 storage emulation
  • PostgreSQL - relational database
  • Redis - key/value store for caching
  • Celery - task manager and executor
Confirm that Docker-based services are running:
docker ps
You should see three containers:
CONTAINER ID   IMAGE            COMMAND                  STATUS        PORTS                    NAMES
e09c5c203b93   redis:6.0.9      "docker-entrypoint.s…"   Up 49 secs    0.0.0.0:6379->6379/tcp   studio_redis_1
6164371efb6b   minio/minio      "minio server /data"     Up 49 secs    0.0.0.0:9000->9000/tcp   studio_minio_1
c86bbfa3a59e   postgres:12.10   "docker-entrypoint.s…"   Up 49 secs    0.0.0.0:5432->5432/tcp   studio_postgres_1

​
Stop Services

To stop the services:
  1. Press Ctrl+C in the terminal where services are running
  2. Remove the Docker containers:
make dcservicesdown

​
Initialize the Database

With services running, initialize the database in a new terminal: 
pnpm run devsetup
This command:
  • Initializes database tables
  • Imports constants
  • Enables required PostgreSQL extensions
  • Creates a development user account

​
Run the Development Server

Start the development server with hot module reloading: 
pnpm run devserver:hot
The server will build the frontend and start the Django development server. When complete, access Studio at:

​
Development Workflow

1

Start services

make run-services
2

Start dev server (in a new terminal)

pnpm run devserver:hot
3

Make changes

Edit code in your editor. Frontend changes will hot-reload automatically.
4

Restart Celery for backend task changes

If you modify Celery tasks, stop and restart:
# Ctrl+C to stop
make devceleryworkers

​
Running Celery Separately

Celery doesn’t auto-reload like Django’s dev server. To develop Celery tasks:
  1. Start only Docker services:
make dcservicesup
  1. In a separate terminal, run Celery:
make devceleryworkers
  1. Stop and restart Celery (Ctrl+C then re-run) after making changes.

​
Useful Make Commands

CommandDescription
make run-servicesStart all services including Celery
make dcservicesupStart Docker services only
make dcservicesdownStop and remove Docker containers
make devceleryworkersRun Celery workers
make testRun backend Python tests

​
Next Steps

Architecture

Learn about Studio’s architecture

Frontend Development

Work with Vue.js components

Backend Development

Develop Django APIs

Testing

Run and write tests

Build docs developers (and LLMs) love

Get started for freeTalk to us