Platform Setup & Installation

How to install and run the BodhiTree e-learning platform on your own machine. The platform repository contains scripts that do most of this for you.

For the release this documentation describes, and the full release history, see Current & Past Versions.

Original Repository

The original repository for Bodhitree E-Learning Platform can be found at:

https://github.com/bodhitree-iitb/Bodhitree

To clone the original repository:

# using SSH
git clone git@github.com:bodhitree-iitb/Bodhitree.git

# or using HTTPS
git clone https://github.com/bodhitree-iitb/Bodhitree.git

Directory Structure

bodhitree/
├── haproxy/            # HAProxy configuration
├── wsgi/               # Python/Django backend
├── nodejs/             # Node.js frontend
├── nginx/              # Nginx web server
├── registry/           # Docker registry
├── templates/          # Template files
├── install.sh          # Main entry point (refactored)
├── README.md           # This file

Prerequisites

Before installing, make sure your machine meets the following requirements:

  • A Linux host (Ubuntu/Debian or CentOS/RHEL/Fedora). Other systems can be used, but Docker must be installed manually.

  • Docker Engine (Community Edition). The interactive installer can install this for you on supported distributions.

  • Docker Swarm mode, the platform is deployed as a Docker Swarm stack. The installer initializes this automatically.

  • At least 12 GB of RAM (minimum requirement).

  • At least 16 GB of free disk space.

  • git to clone the repository.

  • sudo/root privileges (required only for installing Docker and managing the Docker service).

Installation

You can install the Bodhitree platform in two ways:

  • Method 1: Interactive Script (recommended): A guided, menu-driven installer that checks prerequisites, generates configuration, builds the images, and deploys the stack for you.

  • Method 2: Manual, Step-by-Step: Run each step yourself for full control or for environments where the interactive script cannot be used.

Both methods perform the same underlying steps. Choose whichever suits your workflow.

Method 2: Manual, Step-by-Step Installation

Use this method if you prefer to run each step yourself, or if the interactive installer is not suitable for your environment. The steps below reproduce exactly what the interactive installer does.

Step 1: Clone the repository

git clone https://github.com/bodhitree-iitb/Bodhitree.git
cd Bodhitree

Step 2: Install Docker

If Docker is not already installed, install Docker Community Edition. The commands below are for Ubuntu/Debian; for other distributions follow the official instructions at https://docs.docker.com/engine/install/.

# Remove any older Docker packages
sudo apt-get remove -y docker docker-engine docker.io containerd runc

# Update the package index and install prerequisites
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Set up the Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Start and enable the Docker service
sudo systemctl start docker
sudo systemctl enable docker

After installation, add your user to the docker group so you can run Docker without sudo:

sudo usermod -aG docker $USER
# Log out and back in, or run the following to apply in the current shell:
newgrp docker

Verify Docker is working:

docker --version

Step 3: Initialize Docker Swarm

The platform is deployed as a Docker Swarm stack, so Swarm mode must be active:

# Check whether Swarm is already active
docker info | grep -i "Swarm"

# Initialize it if it is not active
docker swarm init

Note: If the host has multiple IP addresses on different interfaces, the command above fails with “could not choose an IP address to advertise since this system has multiple addresses on different interfaces”. Pick the IP of the interface you want the Swarm to use and pass it explicitly:

# List the available IPv4 addresses
hostname -I

# Initialize Swarm with the chosen address
docker swarm init --advertise-addr <YOUR_IP>

Step 4: Create the configuration files

Copy the provided samples into their active locations:

# 1. Docker Compose environment file (ports, image tags, DB credentials)
cp templates/docker-compose.env.example docker-compose.env

# 2. Backend Django settings
cp wsgi/bodhitree/elearning_academy/settings.ini.sample \
   wsgi/bodhitree/elearning_academy/settings.ini

# 3. Frontend environment file
cp nodejs/frontend/.env.production nodejs/frontend/.env

Step 5: Edit docker-compose.env

Open docker-compose.env and adjust the values to suit your environment. The defaults are:

# PostgreSQL Configuration
POSTGRES_DB=elearning_academy
POSTGRES_USER=bodhitree
POSTGRES_PASSWORD=bodhitree123
POSTGRES_MAX_CONNECTIONS=10000

# PGAdmin Configuration
PGADMIN_DEFAULT_EMAIL=bodhitree@cse.iitb.ac.in
PGADMIN_DEFAULT_PASSWORD=bodhitree123
PGADMIN_PORT=8087

# Redis Configuration
ALLOW_EMPTY_PASSWORD=yes

# WSGI Configuration
WSGI_IMAGE_TAG=bodhitree3
C_FORCE_ROOT=true
WSGI_PORT=9090
API_PORT=3000
DJANGO_PORT=8000

# Node.js Configuration
NODEJS_IMAGE_TAG=bodhitree3
NODE_DEV_PORT=9000
NODE_PROD_PORT=9999

# Nginx Configuration
NGINX_PORT=9763

Note: Change the default passwords (POSTGRES_PASSWORD, PGADMIN_DEFAULT_PASSWORD) before deploying to any non-local environment.

Step 6: Generate docker-compose.yml

The deployment manifest is generated from templates/docker-compose.yml.example, which uses ${VARIABLE} placeholders. Copy the template and load the environment values so they are available to Docker:

# Copy the template
cp templates/docker-compose.yml.example docker-compose.yml

# Export the variables from docker-compose.env into the current shell
export $(grep -v '^#' docker-compose.env | xargs)

Note: If you change any variable value in docker-compose.env, run this command again before deploying the stack.

Exporting the variables ensures docker stack deploy substitutes them when it reads docker-compose.yml in the next step.

Step 7: Adjust the worker settings for development (development mode only)

If you are setting up the platform for development, lower the Celery and Gunicorn worker values in wsgi/entrypoint.sh so they are suitable for a local machine. The production defaults are tuned for a server and will be too heavy for development.

Edit wsgi/entrypoint.sh and change the following values:

  • In the Celery worker command, change --concurrency=48 to --concurrency=2.

  • In the Gunicorn command, change --workers "12" and --threads "4" to --workers "2" and --threads "2".

Note: Skip this step for a production setup and keep the default values.

Step 8: Build the Docker images

Build the backend (WSGI) and frontend (Node.js) images using the tags from your env file:

docker build ./wsgi   -t wsgi:$WSGI_IMAGE_TAG
docker build ./nodejs -t nodejs:$NODEJS_IMAGE_TAG

Step 9: Deploy the stack

Deploy the platform as a Docker Swarm stack (named bodhitree here; choose any name you like):

docker stack deploy -c docker-compose.yml bodhitree

Check the status of the services:

docker stack services bodhitree

Step 10: Run the Django setup (first-time only)

Once the backend (wsgi) service is running, run the database migrations and collect static files. First find the WSGI container ID:

WSGI_CONTAINER=$(docker ps --filter name=bodhitree_wsgi --format "{{.ID}}" | head -1)

Then run the setup commands:

# Generate and apply database migrations
docker exec $WSGI_CONTAINER python manage.py makemigrations
docker exec $WSGI_CONTAINER python manage.py migrate

# Collect static files
docker exec $WSGI_CONTAINER python manage.py collectstatic --noinput

# Load the seed data (load the *.common.json fixtures first, then the environment-specific fixtures)
docker exec $WSGI_CONTAINER python manage.py loaddata elearning_academy/fixtures/*.common.json

# For dev
docker exec $WSGI_CONTAINER python manage.py loaddata elearning_academy/fixtures/*.dev.json

# For prod
docker exec $WSGI_CONTAINER python manage.py loaddata elearning_academy/fixtures/*.prod.json

# Create an admin (superuser) account (interactive)
docker exec -it $WSGI_CONTAINER python manage.py createsuperuser

Step 11: Access the platform

Using the default ports from docker-compose.env:

  • Frontend: http://localhost:9763

  • Django admin: http://localhost:8000/admin

  • PGAdmin: http://localhost:8087

Removing the stack

To tear down the deployment when you are finished:

docker stack rm bodhitree

Developing with VS Code

Once the stack is running, you can attach VS Code to the wsgi and nodejs containers to develop and debug them directly.

Step 1: Install the required VS Code extensions

Install the following extensions from the VS Code Marketplace:

  • Remote Development (ms-vscode-remote.vscode-remote-extensionpack)

  • Docker (ms-azuretools.vscode-docker)

Step 2: Attach VS Code to the containers

  1. Open the Docker view from the Activity Bar.

  2. Under Containers, find the running wsgi and nodejs containers.

  3. Right-click each container and choose Attach Visual Studio Code. This opens a new VS Code window connected to that container.

Open one window for the wsgi container and another for the nodejs container.

Step 3: Run and debug the wsgi (backend) container

  1. In the VS Code window attached to the wsgi container, install the Python Debugger extension (ms-python.debugpy) inside the container.

  2. Open the menu Run → Start Debugging to launch the Django backend in debug mode.

Step 4: Run the nodejs (frontend) container

In the VS Code window attached to the nodejs container, open a terminal and start the frontend:

npm run start

Contributing

  1. Clone the repository:

    git clone https://github.com/bodhitree-iitb/Bodhitree.git

  2. Create a new branch for your changes (see Branching Style):

    git checkout -b feature/my-new-feature

  3. Commit your changes (see Writing a Git Message):

    git new 'Add some feature'

  4. Push to your branch:

    git push origin feature/my-new-feature

  5. Submit a pull request