How To Install Oppia on Ubuntu 24.04 LTS

Installing Oppia on Ubuntu 24.04 LTS opens up a world of interactive educational content creation and development. This comprehensive guide covers both native Python installation and Docker deployment methods, providing detailed instructions for setting up this powerful open-source learning platform on your local system. Whether you’re an educator, developer, or contributor to the Oppia project, this tutorial will walk you through every step of the installation process.

Understanding the Oppia Educational Platform

Oppia represents a revolutionary approach to online education, designed specifically to serve underserved communities worldwide. This open-source platform enables users to create interactive lessons called “explorations” that simulate one-on-one tutoring experiences through conversational learning interfaces.

The platform’s core mission focuses on making quality education accessible to everyone, regardless of geographic location or economic status. Oppia’s interactive lessons feature captivating stories and virtual tutors that adapt to individual learning styles and paces.

Key features include personalized learning paths, instant feedback mechanisms, and collaborative content creation tools. The platform supports multiple languages and continues expanding its reach through community translations and localized content development.

Unlike traditional static educational content, Oppia’s explorations respond dynamically to learner inputs, creating branching conversations that address misconceptions and provide scaffolded learning experiences. This approach makes learning more engaging and effective for diverse audiences.

System Requirements for Ubuntu 24.04 LTS

Hardware Requirements

Your Ubuntu 24.04 LTS system needs adequate resources to run Oppia smoothly. The minimum RAM requirement stands at 4GB, though 8GB provides better performance during development and testing scenarios.

Free disk space requirements include at least 25GB for basic installation, with 50GB recommended for active development work. The additional space accommodates dependencies, build artifacts, and development databases.

A dual-core processor running at 2 GHz minimum ensures adequate processing power for compilation and runtime operations. Modern multi-core processors significantly improve build times and overall system responsiveness.

Stable internet connectivity proves essential during initial setup for downloading dependencies, cloning repositories, and accessing external services required by the platform.

Software Dependencies Overview

Python 3.10.16 serves as the primary runtime environment for Oppia’s backend services. This specific version ensures compatibility with all platform components and third-party libraries.

Java 11 or higher supports various build tools and development utilities integrated into the Oppia ecosystem. The Java runtime handles compilation processes and serves development tools.

Git version control system enables repository management, code synchronization, and collaboration workflows essential for Oppia development. Modern Git versions provide better performance and security features.

Chrome or Chromium browser integration supports automated testing frameworks and development tools used throughout the platform. Browser compatibility ensures proper testing of frontend components.

Node.js and npm package manager handle frontend dependency management and build processes for the Angular-based user interface components.

Pre-Installation Setup

Updating Ubuntu System

Begin by refreshing your Ubuntu 24.04 LTS system to ensure all packages reflect the latest security patches and updates. Execute the following commands in sequence:

sudo apt update
sudo apt upgrade -y
sudo apt autoremove -y

These commands synchronize package databases, install available upgrades, and remove unnecessary packages that might conflict with new installations.

Installing Essential Dependencies

Install fundamental development tools and libraries required for Oppia installation:

sudo apt install -y curl git unzip build-essential software-properties-common

Next, install OpenJDK 11 for Java runtime support:

sudo apt install -y openjdk-11-jdk
java -version

The version command verifies successful Java installation and displays the current runtime version.

Install Google Chrome for browser-based testing:

wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update
sudo apt install -y google-chrome-stable

User Permissions Configuration

Avoid using sudo during the actual Oppia installation process to prevent permission conflicts. Instead, ensure your user account has proper directory access:

mkdir -p ~/oppia-development
cd ~/oppia-development

This approach maintains consistent file ownership and prevents common permission-related installation failures.

Method 1: Native Installation with Python Virtual Environment

Setting Up Development Environment

Installing pyenv and Python 3.10.16

Pyenv enables precise Python version management essential for Oppia compatibility. Install pyenv using the official installer:

curl https://pyenv.run | bash

Configure your shell environment by adding the following lines to your ~/.bashrc or ~/.zshrc:

export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Reload your shell configuration:

source ~/.bashrc

Install Python 3.10.16 specifically for Oppia compatibility:

pyenv install 3.10.16
pyenv global 3.10.16
python --version

The version command should display “Python 3.10.16” confirming successful installation.

Virtual Environment Configuration

Install direnv for automatic environment management:

sudo apt install -y direnv

Add direnv hook to your shell configuration file:

echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

Create the .direnvrc file in your home directory:

cat > ~/.direnvrc << 'EOF' use_python() { if has pyenv; then local pyversion=$1 pyenv local ${pyversion} fi layout_python() { local python=${1:-python3} [[ $# -gt 0 ]] && shift unset PYTHONHOME if [[ -n $python ]]; then local python_version python_version=$($python -V 2>&1 | cut -d' ' -f2 | cut -d'.' -f1-2)
            if [[ -z $python_version ]]; then
                log_error "Could not detect Python version"
                return 1
            fi
            VIRTUAL_ENV=$(direnv_layout_dir)/python-$python_version
        else
            VIRTUAL_ENV=$(direnv_layout_dir)/python3
        fi
        export VIRTUAL_ENV
        if [[ ! -d $VIRTUAL_ENV ]]; then
            log_status "Installing Python dependencies"
            $python -m venv "$VIRTUAL_ENV"
        fi
        PATH_add "$VIRTUAL_ENV/bin"
        unset PS1
    }
    
    layout_python python3
}
EOF

Cloning Oppia Repository

Repository Setup

Navigate to your development directory and create the project structure:

cd ~/oppia-development

Fork the Oppia repository through GitHub’s web interface, then clone your fork:

git clone https://github.com/YOUR_USERNAME/oppia.git
cd oppia

Replace YOUR_USERNAME with your actual GitHub username.

Git Configuration

Add the upstream repository for accessing latest changes:

git remote add upstream https://github.com/oppia/oppia.git
git fetch upstream

Configure the .envrc file for automatic environment activation:

echo "use_python 3.10.16" > .envrc
direnv allow .

This configuration automatically activates the Python virtual environment when entering the directory.

Python Dependencies Installation

Core Dependencies

Install essential Python packages required for Oppia operation:

pip install --upgrade pip
pip install PyYAML==5.4.1 setuptools==58.5.3

These specific versions ensure compatibility with the Oppia codebase and prevent version conflicts during development.

Run the dependency installation script:

pip install -r requirements.txt

This command processes all Python dependencies listed in the requirements file, downloading and installing each package with appropriate version constraints.

Testing Dependencies

Install additional packages for development and testing:

pip install -r requirements_dev.txt

These dependencies include testing frameworks, code coverage tools, and development utilities that support the complete development workflow.

Monitor the installation process for any error messages indicating missing system libraries or compilation failures. Address any issues before proceeding to server startup.

Running Development Server

Initial Server Startup

Launch the Oppia development server for the first time:

python -m scripts.start

The initial startup process requires significant time as the system downloads additional dependencies, compiles frontend assets, and initializes the local datastore. Expect this process to take 15-20 minutes on most systems.

Monitor the console output for progress indicators and error messages. The system displays various initialization stages including:

• Dependency verification and installation
• Frontend asset compilation
• Backend service initialization
• Database schema creation
• Demo content loading

Server Access and Verification

Once the startup process completes, access the development interface through your web browser:

• Main application: http://localhost:8181
• Admin console: http://localhost:8000

The main interface displays the Oppia homepage with sample explorations and user registration options. The admin console provides development tools and administrative functions.

Test basic functionality by creating a user account and exploring the available sample lessons. Verify that interactive elements respond correctly and that navigation works smoothly.

Server Management

Gracefully shutdown the development server using Ctrl+C in the terminal. The system preserves datastore contents by default, maintaining user accounts and created content between sessions.

For clean restarts without preserving data, use the --save_datastore false flag:

python -m scripts.start --save_datastore false

Additional server options include performance tuning flags and development mode configurations that optimize the experience for different use cases.

Method 2: Docker Installation

Docker Prerequisites

Docker Installation on Ubuntu 24.04

Install Docker using the official repository for guaranteed compatibility and security updates:

sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

Add Docker’s official GPG key:

sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Configure 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 update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group to run commands without sudo:

sudo usermod -aG docker $USER
newgrp docker

Verify Docker installation:

docker run hello-world

Resource Allocation

Configure Docker with adequate resources for Oppia development. Allocate minimum 6GB RAM for optimal performance, though 8GB provides better experience during intensive operations.

CPU allocation should include at least 2 cores, with 4 cores recommended for faster build times and responsive development environment.

Storage requirements include 50GB free space for Docker images, containers, and development data. Monitor disk usage during development to prevent space-related issues.

Oppia Docker Setup

Repository Preparation

Clone your forked Oppia repository as described in the native installation method:

cd ~/oppia-development
git clone https://github.com/YOUR_USERNAME/oppia.git
cd oppia

Ensure the upstream remote is configured for accessing latest changes:

git remote add upstream https://github.com/oppia/oppia.git

Docker Build Process

Execute the Docker build command to create the Oppia development environment:

make build

This command initiates a comprehensive build process that includes:

• Base image preparation with Ubuntu and system dependencies
• Python environment setup with required packages
• Node.js installation and frontend dependency management
• Application code integration and initial compilation

The initial build requires 15-20 minutes depending on system performance and internet connectivity. Subsequent builds leverage Docker layer caching for significantly faster execution.

Monitor build progress through console output, watching for any error messages that indicate missing dependencies or configuration issues. Address build failures before proceeding to server startup.

Running Oppia with Docker

Development Server Launch

Start the Oppia development environment using Docker:

make run-devserver

This command launches the complete development stack within Docker containers, including:

• Backend Python services
• Frontend development server
• Database services
• File watching and automatic recompilation

The startup process displays initialization progress and service status information. Wait for all services to report ready status before accessing the application.

Server Management

Access the running application through the same URLs as native installation:

• Main application: http://localhost:8181
• Admin console: http://localhost:8000

Stop the development environment gracefully:

docker-compose down

For complete cleanup including volumes and cached data:

docker-compose down -v
make clean

Docker Flags and Advanced Usage

The Oppia Docker setup supports various flags for customizing the development environment:

Save datastore between sessions:

make run-devserver save_datastore=true

Disable host checking for network access:

make run-devserver disable_host_checking=true

Run in production environment mode:

make run-devserver prod_env=true

Enable maintenance mode:

make run-devserver maintenance_mode=true

Generate source maps for debugging:

make run-devserver source_maps=true

Disable automatic restart on file changes:

make run-devserver no_auto_restart=true

These flags can be combined to create custom development configurations that match specific workflow requirements.

Testing and Verification

Running Test Suites

Verify your Oppia installation by executing the comprehensive test suite:

For backend tests:

python -m scripts.run_tests --test_target=backend

For frontend tests:

python -m scripts.run_tests --test_target=frontend

End-to-end testing:

python -m scripts.run_e2e_tests

Code quality and linting checks:

python -m scripts.run_presubmit_checks

Each test suite validates different aspects of the platform, from individual component functionality to complete user workflows. Address any test failures before considering the installation complete.

Functionality Verification

Test core platform features through the web interface:

1. Create a new user account through the registration process
2. Navigate to the exploration creation tools
3. Build a simple interactive lesson with questions and responses
4. Preview the exploration from a learner’s perspective
5. Access administrative functions through the admin console

Performance benchmarking involves monitoring system resource usage during normal operations and identifying potential bottlenecks in development workflows.

Troubleshooting Common Issues

Installation Problems

Permission and Access Issues

Node.js permission problems often occur when packages are installed globally. Resolve by configuring npm to use a user directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Directory ownership corrections may be necessary if sudo was used incorrectly:

sudo chown -R $USER:$USER ~/oppia-development

PATH configuration errors prevent proper tool access. Verify your shell configuration includes all necessary directories:

echo $PATH
which python
which node
which java

Virtual environment activation failures usually indicate direnv configuration issues. Verify the .envrc file exists and contains correct Python version specifications.

Dependency Conflicts

Python version mismatches create compatibility problems. Ensure Python 3.10.16 is active:

python --version
which python

Package installation failures often result from missing system libraries. Install additional development packages:

sudo apt install -y python3-dev libffi-dev libssl-dev

Java version compatibility requires specific versions for optimal performance. Verify Java 11 is active:

java -version
javac -version

System Resource Problems

Insufficient memory errors require increasing available RAM or adding swap space:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Disk space requirements may exceed initial estimates during development. Monitor usage and clean unnecessary files:

df -h
docker system prune -a

Network connectivity issues affect dependency downloads and external service access. Verify internet connectivity and DNS resolution function correctly.

Runtime and Configuration Issues

Server Startup Failures

Port binding conflicts occur when other services use required ports. Identify conflicting processes:

sudo lsof -i :8181
sudo lsof -i :8000

Terminate conflicting services or configure Oppia to use alternative ports through environment variables.

Service initialization errors typically indicate missing dependencies or configuration problems. Review startup logs carefully for specific error messages and stack traces.

Database connection problems may result from incomplete initialization or permission issues. Reset the development database:

python -m scripts.reset_datastore

Development Server Issues

Frontend compilation errors often indicate Node.js or npm configuration problems. Verify installations and clear cache:

npm cache clean --force
rm -rf node_modules
npm install

Backend service crashes require investigation of Python error logs and dependency conflicts. Check for missing packages or version incompatibilities.

Performance degradation causes include insufficient system resources, inefficient code, or configuration problems. Monitor system metrics during operation to identify bottlenecks.

Docker-Specific Problems

Container build failures usually indicate missing dependencies or network issues. Review build logs for specific error messages:

docker build --no-cache .

Resource allocation errors require adjusting Docker settings or system configuration. Increase available memory and CPU limits through Docker preferences.

Volume mounting issues prevent proper file synchronization between host and container. Verify mount points and permissions:

docker volume ls
docker volume inspect oppia_node_modules

Network connectivity problems within containers may require custom network configuration or firewall adjustments.

Performance Optimization and Best Practices

System Performance Tuning

Memory allocation optimization involves configuring appropriate heap sizes and garbage collection settings for Java and Python processes. Monitor memory usage patterns and adjust accordingly:

export JAVA_OPTS="-Xmx2g -XX:+UseG1GC"

Disk I/O improvements include using SSD storage, optimizing file system settings, and implementing proper caching strategies for development artifacts and dependencies.

Network configuration tweaks enhance dependency download speeds and external service access. Consider using local package mirrors and CDN configurations when available.

Development workflow optimization focuses on reducing build times, improving code compilation speed, and streamlining testing processes through parallel execution and incremental builds.

Security Considerations

Local development security requires protecting sensitive data, limiting network exposure, and maintaining secure configuration practices throughout the development lifecycle.

Network exposure limitations involve configuring firewalls, using secure protocols, and restricting access to development services from external networks.

Data privacy in development includes proper handling of user data, secure storage of credentials, and compliance with privacy regulations even in development environments.

Secure configuration practices encompass using environment variables for sensitive settings, implementing proper access controls, and maintaining security updates for all system components.

Advanced Configuration Options

Development Workflow Customization

IDE integration options include configuring popular development environments like Visual Studio Code, PyCharm, and Sublime Text with Oppia-specific settings, extensions, and debugging configurations.

Debugging configuration involves setting up proper breakpoints, logging levels, and development tools for efficient troubleshooting and code analysis during active development work.

Code formatting and linting setup ensures consistent code quality through automated tools like pylint, eslint, and prettier with project-specific configuration files and integration with development workflows.

Version control workflows optimize Git usage through proper branch management, commit message conventions, and integration with continuous integration systems for automated testing and deployment.

Production-Ready Setup Considerations

Environment variable management requires secure handling of configuration settings, database connections, API keys, and other sensitive information through proper secret management systems.

Database configuration options include choosing appropriate database backends, configuring connection pooling, implementing backup strategies, and optimizing query performance for production workloads.

Logging and monitoring setup involves implementing comprehensive logging strategies, monitoring system performance, tracking user interactions, and setting up alerting for critical issues.

Backup and recovery procedures ensure data protection through regular backups, disaster recovery planning, and testing restoration processes to maintain service continuity.

Congratulations! You have successfully installed Oppia. Thanks for using this tutorial for installing Oppia online learning tool on your Ubuntu 24.04 LTS system. For additional or useful information, we recommend you check the official Oppia website.