How To Install Oppia on Fedora 43

Educational technology continues to transform how we learn and teach. Oppia stands out as a powerful open-source platform that enables educators to create interactive learning experiences. This comprehensive guide walks you through installing Oppia on Fedora 43, from initial system preparation to running your first development server.

Oppia is an online learning tool designed to simulate one-on-one tutoring through interactive explorations. Built with Python, Angular, and Google App Engine, it empowers educators to create engaging lessons without extensive programming knowledge. While the platform is available at oppia.org, installing it locally gives you complete control over customization, development, and testing new features.

This tutorial targets Fedora 43 users who want to set up a local Oppia development environment. Whether you’re an educator looking to customize lessons, a developer contributing to the project, or a system administrator deploying educational platforms, you’ll find detailed instructions here. The entire installation process takes approximately 90 to 120 minutes, depending on your internet connection and system specifications.

Fedora 43 provides an excellent foundation for hosting Oppia thanks to its cutting-edge package repositories, strong security features, and robust development tools. The distribution’s DNF package manager simplifies dependency installation, while SELinux adds an extra security layer for production deployments.

Understanding Oppia

Before diving into installation, understanding what Oppia offers helps you make informed decisions about hosting and configuration.

What is Oppia?

Oppia is a free, open-source learning platform that creates interactive educational experiences. Unlike traditional e-learning systems that present static content, Oppia uses conversational interfaces to guide learners through material adaptively. The platform responds to student answers, provides targeted feedback, and adjusts difficulty based on individual progress.

The technology stack combines several powerful frameworks. Python handles backend logic and server operations. Angular powers the responsive frontend interface. Google App Engine provides scalable cloud infrastructure for the hosted version. Redis manages caching and session data, while Elasticsearch enables fast content search across explorations.

Educators use Oppia for diverse subjects including mathematics, science, languages, and programming. The platform excels at creating branching learning paths where student responses determine subsequent questions. This adaptive approach mimics skilled tutors who adjust teaching strategies based on learner comprehension.

Self-hosting Oppia offers significant advantages over using the public instance. You gain complete control over user data and privacy. Custom modifications become possible without waiting for upstream approval. Testing new features happens in isolated environments before production deployment. Organizations with specific compliance requirements can audit and modify the codebase as needed.

Prerequisites and System Requirements

Proper planning prevents installation headaches. Review these requirements carefully before proceeding.

Hardware Requirements

Your system needs adequate resources to run Oppia smoothly. The minimum RAM requirement is 4 GB, though 6 GB or more delivers better performance, especially during initial compilation and when running tests. Development work with multiple services running simultaneously benefits from additional memory.

Processor specifications matter for compilation speed. A multi-core processor running at 2 GHz or higher handles build tasks efficiently. Modern AMD or Intel processors with four or more cores provide optimal performance during dependency compilation and test execution.

Storage capacity should exceed 20 GB of free disk space. The Oppia repository itself occupies approximately 179 MB, but third-party dependencies, Python packages, Node modules, and development tools quickly consume several gigabytes. Elasticsearch indices and log files grow over time, so allocating extra space prevents future issues.

Network connectivity affects initial setup duration. A stable, reasonably fast internet connection downloads dependencies and libraries efficiently. The first run downloads hundreds of megabytes of third-party code, so metered connections should monitor bandwidth usage.

Software Requirements

Fedora 43 should be fully updated before beginning installation. Recent system updates ensure compatibility with modern development tools and security patches.

Python version requirements are specific. Oppia requires Python 3.10.16 for proper operation. Newer or older versions may cause compatibility issues with dependencies. Using pyenv to manage Python versions prevents conflicts with system Python installations.

Java Development Kit installation is mandatory. OpenJDK 11 or higher provides the runtime environment for Google Cloud Platform components used by Oppia. Fedora’s package repositories include compatible OpenJDK versions.

Git version control manages source code and updates. The latest Git version from Fedora repositories works perfectly. Additional tools including curl for downloading files, unzip for extracting archives, and Google Chrome for running automated tests complete the software prerequisites.

User Permissions

Administrative access through sudo is necessary for installing system packages. Several installation steps require root privileges to modify system configurations, install global packages, and configure network settings. Standard user accounts need sudo group membership to execute these commands.

Understanding why administrative privileges are needed helps with security planning. System package installation modifies shared libraries. Port binding below 1024 requires elevated permissions, though Oppia uses port 8181 by default. Firewall modifications allow external access to the development server.

Pre-Installation Preparation

Preparing your Fedora 43 system correctly prevents common installation issues.

Step 1: Update Fedora 43 System

Begin by updating all installed packages to their latest versions. Open a terminal and execute:

sudo dnf update -y

This command refreshes package metadata, identifies available updates, and installs them automatically. The process might take several minutes depending on how recently you last updated the system. Kernel updates require a system reboot to take effect.

System updates matter for several reasons. Security patches close vulnerabilities that could compromise your development environment. Bug fixes in system libraries prevent obscure compilation errors. Updated development tools support modern programming language features used by Oppia’s codebase.

After updates complete, reboot if kernel updates were installed:

sudo reboot

Step 2: Install Base Development Tools

Fedora groups common development utilities into convenient package collections. Install the Development Tools group:

sudo dnf groupinstall "Development Tools" -y

This group includes gcc, g++, make, and other essential build utilities. These tools compile source code dependencies during Oppia’s first run. Without them, installation fails with cryptic error messages about missing compilers.

Essential build dependencies for Python compilation include several development libraries:

sudo dnf install gcc make zlib-devel bzip2-devel readline-devel sqlite-devel openssl-devel libffi-devel -y

Each library serves specific purposes. The zlib library handles compression. Bzip2 supports archive extraction. Readline provides interactive command-line editing. SQLite powers lightweight database operations. OpenSSL enables secure communications. LibFFI facilitates foreign function interfaces.

Step 3: Verify System Compatibility

Check your current Python version to understand what’s already installed:

python3 --version

Fedora 43 typically ships with Python 3.11 or 3.12. Since Oppia requires Python 3.10.16 specifically, you’ll install this version through pyenv later without affecting the system Python installation.

Verify available disk space using the df command:

df -h /

Look for the root filesystem usage. Ensure at least 20 GB remains free for Oppia installation, dependencies, and working space.

Confirm your system architecture:

uname -m

The output should show x86_64 for standard Intel and AMD processors. Oppia supports standard 64-bit architectures without issues.

Installing Required Dependencies

Oppia relies on numerous external tools and libraries. Installing them systematically prevents dependency errors.

Step 1: Install Core Utilities

Core utilities handle downloading, version control, and file extraction. Install them with a single command:

sudo dnf install curl git unzip -y

Curl downloads files from URLs, essential for fetching libraries and scripts. Git manages source code, tracks changes, and syncs with the upstream Oppia repository. Unzip extracts compressed archives containing third-party dependencies.

These utilities integrate deeply with Oppia’s installation scripts. The start.py script uses curl to fetch third-party libraries automatically. Git manages version control and facilitates contributing changes back to the project. Unzip unpacks downloaded archives into appropriate directories.

Step 2: Install Java Development Kit

Java powers several Oppia components including the Google Cloud Platform development server. Install OpenJDK 11:

sudo dnf install java-11-openjdk java-11-openjdk-devel -y

The java-11-openjdk package provides the Java runtime environment. The java-11-openjdk-devel package includes development tools and headers needed for building Java applications.

Verify the installation succeeded:

java -version

The output should display OpenJDK version 11.x.x. If multiple Java versions exist on your system, set Java 11 as the default:

sudo alternatives --config java

Select the entry corresponding to OpenJDK 11 from the displayed list. This command updates the system-wide Java symlinks to point at your chosen version.

Setting the JAVA_HOME environment variable helps applications locate Java:

echo 'export JAVA_HOME=/usr/lib/jvm/java-11-openjdk' >> ~/.bashrc
source ~/.bashrc

This configuration persists across terminal sessions and system reboots.

Step 3: Install Python Build Dependencies

Building Python from source requires numerous development libraries. Install them comprehensively:

sudo dnf install gcc make zlib-devel bzip2-devel readline-devel sqlite-devel openssl-devel libffi-devel xz-devel tk-devel -y

Each library enables specific Python functionality. Missing any library causes compilation failures or disables Python features. The xz-devel package handles LZMA compression. Tk-devel supports graphical user interface development, though Oppia doesn’t require it for core functionality.

These dependencies enable pyenv to compile Python 3.10.16 from source code. Source compilation takes longer than installing binary packages but ensures exact version matches and optimal system integration.

Step 4: Install Google Chrome

Chrome is necessary for running Oppia’s frontend tests. The test suite uses Chrome’s automation interface to verify user interface functionality.

Add Google’s RPM repository:

sudo dnf install fedora-workstation-repositories -y
sudo dnf config-manager --set-enabled google-chrome

Install Chrome:

sudo dnf install google-chrome-stable -y

Chrome installs to /opt/google/chrome/ by default. Test execution scripts detect Chrome automatically when it’s installed in standard locations.

Setting Up Python Environment

Managing multiple Python versions requires specialized tools. Pyenv provides robust version management without interfering with system Python.

Installing pyenv

Pyenv lets you install and switch between Python versions effortlessly. Clone the pyenv repository:

git clone https://github.com/pyenv/pyenv.git ~/.pyenv

This command downloads pyenv into your home directory’s .pyenv folder. The hidden directory doesn’t clutter your regular file listings.

Configure your shell to use pyenv by adding it to your PATH:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

These lines modify your bash configuration file. The PYENV_ROOT variable defines pyenv’s installation location. PATH modifications let you run pyenv commands from any directory. The init commands enable pyenv’s shell integration for automatic Python version switching.

Reload your shell configuration:

source ~/.bashrc

Verify pyenv installation:

pyenv --version

Installing Python 3.10.16

With pyenv configured, install the specific Python version Oppia requires:

pyenv install 3.10.16

This command downloads Python 3.10.16 source code and compiles it. Compilation typically takes 5 to 15 minutes depending on processor speed. You’ll see progress messages as various Python components build.

The compilation process creates an optimized Python installation in ~/.pyenv/versions/3.10.16/. Multiple Python versions coexist peacefully without conflicts.

Verify successful installation:

pyenv versions

The output lists all installed Python versions. The asterisk marks your currently active version.

Creating Virtual Environment

Virtual environments isolate project dependencies from system-wide packages. Create a dedicated environment for Oppia:

pyenv virtualenv 3.10.16 oppia

This command creates a virtual environment named “oppia” based on Python 3.10.16. The environment gets stored in ~/.pyenv/versions/oppia/.

Activate the virtual environment:

pyenv activate oppia

Your command prompt changes to indicate the active environment, typically showing “(oppia)” before your username.

For automatic activation when entering the Oppia directory, install direnv:

sudo dnf install direnv -y
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

Direnv automatically loads environment-specific settings when you change directories, streamlining development workflows.

Installing Python Dependencies

Several Python packages must be pre-installed before running Oppia:

pip install --upgrade pip
pip install pyyaml setuptools coverage configparser

PyYAML parses YAML configuration files used throughout Oppia. Setuptools provides packaging and distribution utilities. Coverage measures code coverage during testing. Configparser handles legacy configuration file formats.

Upgrading pip first ensures you’re using the latest package manager version with bug fixes and security improvements.

Cloning and Configuring Oppia

With prerequisites satisfied, obtain the Oppia source code and prepare it for running.

Creating Project Directory

Organize your development projects systematically. Create a dedicated folder:

mkdir -p ~/opensource
cd ~/opensource

The -p flag creates parent directories automatically if they don’t exist. This folder will contain Oppia and potentially other open-source projects you contribute to.

Using a dedicated projects directory separates development work from personal files, simplifying backups and version control management.

Forking Oppia Repository

Forking creates your own copy of the Oppia repository on GitHub. This is essential for contributing changes back to the project.

Click the “Fork” button in the upper-right corner. GitHub creates a complete copy of the repository under your account. The fork maintains a connection to the original repository, facilitating updates and pull requests.

Forking enables you to experiment freely without affecting the main project. Your changes stay in your fork until you submit pull requests for review.

Cloning the Repository

Clone your forked repository to your local machine. Replace YOUR_USERNAME with your actual GitHub username:

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

Git downloads the complete repository including all history, branches, and tags. The initial clone downloads approximately 179 MB of data. Progress messages show download speed and completion percentage.

Add the upstream repository as a remote:

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

This connection lets you pull updates from the main Oppia project, keeping your fork synchronized with upstream changes.

Setting Local Python Version

Configure pyenv to use the Oppia virtual environment in this directory:

pyenv local oppia

This creates a .python-version file containing “oppia”. Whenever you enter this directory, pyenv automatically activates the correct Python environment.

Verify the correct Python version is active:

python --version

The output should display Python 3.10.16, confirming proper environment configuration.

Running Oppia Development Server

The first server run downloads numerous dependencies and configures the development environment.

First-Time Startup

Launch Oppia’s development server:

python -m scripts.start

This command initiates Oppia’s startup script. The first run takes significantly longer than subsequent starts because it downloads third-party libraries, compiles assets, and configures services.

What Happens During First Run

Watch progress messages as Oppia sets up your environment. The script downloads Node.js and npm for JavaScript dependency management. Elasticsearch installs for search functionality. Redis sets up for caching and session management. Webpack compiles frontend assets into optimized bundles.

Hundreds of megabytes of third-party libraries download during this phase. Fast internet connections complete this in 10-15 minutes. Slower connections may require 30-45 minutes.

The script creates necessary directories, generates configuration files, and initializes database schemas. Progress indicators show which component is currently installing.

If errors occur during first run, they typically relate to missing system dependencies or network issues. Review error messages carefully—they usually identify the specific problem.

Accessing Oppia Interface

Once startup completes, you’ll see a message indicating the server is running. Open your web browser and navigate to:

http://localhost:8181

The Oppia welcome page appears, featuring a login interface and exploration gallery. Create an admin account by clicking the signup button and completing the registration form.

Chrome and Firefox both work well with Oppia. Avoid older browsers that lack modern JavaScript support.

The development server runs continuously until you stop it with Ctrl+C. Keep the terminal window open while using Oppia.

Post-Installation Configuration

Fine-tune your installation for optimal operation.

Verifying Installation

Test basic functionality by creating a simple exploration. Click “Create” in the navigation menu and follow the prompts to build a short interactive lesson.

Verify all services started correctly by checking the startup logs. Look for messages confirming Elasticsearch, Redis, and the development server all launched successfully.

Run a quick backend test to confirm the installation:

python -m scripts.run_backend_tests

This executes a subset of backend tests. All tests should pass on a fresh installation. Failures indicate missing dependencies or configuration issues.

Firewall Configuration

Allow external access to Oppia’s development server by configuring Fedora’s firewall. Add a rule for port 8181:

sudo firewall-cmd --permanent --add-port=8181/tcp
sudo firewall-cmd --reload

The –permanent flag makes the rule persist across reboots. The –reload command activates the new configuration immediately.

External access enables testing from mobile devices or other computers on your network. For production deployments, configure proper HTTPS and authentication instead of opening ports directly.

Setting Up Auto-Start (Optional)

For persistent Oppia instances, create a systemd service. Create a service file:

sudo nano /etc/systemd/system/oppia.service

Add this configuration:

[Unit]
Description=Oppia Development Server
After=network.target

[Service]
Type=simple
User=YOUR_USERNAME
WorkingDirectory=/home/YOUR_USERNAME/opensource/oppia
ExecStart=/home/YOUR_USERNAME/.pyenv/versions/oppia/bin/python -m scripts.start
Restart=on-failure

[Install]
WantedBy=multi-user.target

Replace YOUR_USERNAME with your actual username. Enable and start the service:

sudo systemctl enable oppia.service
sudo systemctl start oppia.service

Check service status:

sudo systemctl status oppia.service

This configuration automatically starts Oppia when the system boots.

Common Installation Issues and Troubleshooting

Even with careful preparation, issues sometimes arise. These solutions address the most frequent problems.

Port Already in Use Errors

If port 8181 is occupied, Oppia won’t start. Identify the conflicting process:

sudo lsof -i :8181

This lists processes using port 8181. Kill the conflicting process or change Oppia’s default port in the configuration.

Memory Issues

Insufficient RAM causes random failures and slow performance. Monitor memory usage:

free -h

If available memory drops below 500 MB, consider adding swap space:

sudo dd if=/dev/zero of=/swapfile bs=1G count=4
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

This creates a 4 GB swap file. Make it permanent by adding this line to /etc/fstab:

/swapfile swap swap defaults 0 0

Python/Java Version Conflicts

Multiple Python or Java versions cause mysterious errors. Verify active versions:

python --version
java -version

If wrong versions appear, reconfigure alternatives:

sudo alternatives --config python3
sudo alternatives --config java

Select the correct versions from the presented lists.

“No module named builtins” Error

This Python 2/3 compatibility error requires installing the future package:

pip install future

Restart the development server after installation.

Failed to Start Server Errors

Timeout issues during startup sometimes occur on slower systems. Increase timeout values in scripts/common.py. Look for timeout configuration variables and increase them by 50%.

If Elasticsearch fails to start, launch it manually:

python -m scripts.start_elasticsearch

Check error messages for clues about the failure cause.

Redis server issues on ARM architectures require architecture-specific builds. Check the troubleshooting wiki for platform-specific solutions.

Testing Your Oppia Installation

Comprehensive testing ensures everything works correctly.

Running Backend Tests

Execute the backend test suite:

python -m scripts.run_backend_tests

Tests verify Python code functionality, database operations, and API endpoints. The full suite takes 10-20 minutes to complete.

Coverage reports show which code paths tests execute. High coverage indicates thorough testing.

Running Frontend Tests

Frontend tests verify user interface components:

python -m scripts.run_frontend_tests

These tests use Chrome to simulate user interactions. The browser launches automatically during test execution.

Common test failures often relate to timing issues or missing dependencies. Rerunning failed tests sometimes resolves transient failures.

Loading Demo Explorations

Explore sample content to understand Oppia’s capabilities. The exploration gallery includes mathematics lessons, language learning modules, and programming tutorials.

Create a custom exploration to test content authoring. The editor provides drag-and-drop interfaces for building interactive lessons.

Best Practices and Optimization

Optimize your installation for better performance and security.

Performance Tuning for Fedora 43

Allocate resources appropriately. Increase memory limits for Node.js processes if you experience out-of-memory errors during compilation.

Enable compiler optimizations for faster builds. Set environment variables:

export MAKEFLAGS="-j$(nproc)"

This parallelizes compilation across all CPU cores, significantly reducing build times.

Database performance improves with proper indexing. Elasticsearch benefits from adequate heap memory—allocate at least 2 GB for production use.

Security Hardening

Development environments still need security. Keep system packages updated regularly. Enable automatic security updates:

sudo dnf install dnf-automatic -y
sudo systemctl enable --now dnf-automatic.timer

Restrict file permissions on sensitive directories. Ensure only your user account can read configuration files containing credentials.

Network security matters even for local development. Use firewall rules to restrict access to trusted IP addresses only.

Backup Strategies

Protect your work with regular backups. Back up the entire oppia directory including customizations and user-created content.

Database backups preserve exploration data. Export explorations regularly through the admin interface.

Version control protects code changes. Commit frequently to Git and push to remote repositories.

Backup frequency depends on usage. Daily backups suit active development. Weekly backups suffice for occasional use.

Updating and Maintaining Oppia

Keep your installation current with upstream changes.

Keeping Oppia Updated

Pull latest changes from the upstream repository:

git fetch upstream
git checkout develop
git merge upstream/develop

This synchronizes your local repository with upstream changes. The develop branch contains the latest development work.

After updating code, reinstall dependencies:

python -m scripts.install_third_party_libs

Database migrations sometimes accompany updates. Run migration scripts when prompted.

Monitoring System Health

Log files contain valuable troubleshooting information. Check logs in the oppia directory under logs/. Review error logs when issues arise.

Common warning messages about deprecated APIs or slow queries indicate areas needing attention. Address warnings before they become errors.

Performance monitoring tools identify bottlenecks. Monitor CPU usage, memory consumption, and disk I/O during heavy usage periods.

Alternative Installation Methods

Docker provides a different installation approach worth considering.

Docker Installation

Docker containers package Oppia with all dependencies in an isolated environment. This approach simplifies installation but requires Docker expertise.

Docker installation requires 6 GB or more RAM due to container overhead. The Oppia Docker image includes all services pre-configured.

Install Docker on Fedora 43:

sudo dnf install docker -y
sudo systemctl enable --now docker

Pull the Oppia Docker image and run it following instructions in the official Oppia wiki.

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