How to Install Oppia on CentOS Stream 10 – A step-by-step guide for ed-tech developers

Introduction

In the age of digital learning, interactive educational platforms are becoming ever more important. Oppia is a powerful open-source platform for creating and sharing interactive lessons and explorations. In this tutorial you’ll learn how to install Oppia on CentOS Stream 10 — giving you a self-hosted environment ready for building customised learning experiences.

Whether you’re an ed-tech startup, a learning-and-development team in an enterprise, or a developer experimenting with interactive lesson delivery, this guide covers prerequisites, installation steps, configuration, and a test run. We’ll also cover a few troubleshooting tips you may encounter.

Why Choose CentOS Stream 10 + Oppia?

• CentOS Stream 10 is the “rolling-preview” of the next major RHEL version. It gives you relatively stable but up-to-date foundations for server deployments.
• Oppia brings interactive, branching / explorational learning to the web. Hosting it yourself gives you full control over customisation, branding, and data.
• Combining them means you get a robust Linux server environment with a rich interactive learning platform under your own management.

Pre-installation Checklist

Before you begin, ensure you have:

• A server or VM running CentOS Stream 10 with root (or sudo) access.
• Minimum recommended resources — Oppia can be resource-intensive when running with many users, so aim for 4 GB RAM (8 GB or more preferred) + SSD.
• A non-root user with sudo privileges for day-to-day work.
• Basic packages: git, curl, unzip, python3, and a modern Java runtime (depending on Oppia version) installed.

Step 1: System Preparation on CentOS Stream 10

Open a terminal and run the following commands:

sudo dnf update -y
sudo dnf install -y git curl unzip python3 python3-venv java-11-openjdk-devel

Enable any additional tools you might need later:

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

You may also want to disable SELinux or set it to permissive mode temporarily to simplify initial setup (though for production you’ll want proper policy). For example:

sudo setenforce 0
sudo sed -i 's/^SELINUX=.*/SELINUX=permissive/' /etc/selinux/config

Step 2: Clone the Oppia Repository

Create a directory to host your Oppia installation:

mkdir ~/oppia-deploy
cd ~/oppia-deploy
git clone https://github.com/oppia/oppia.git
cd oppia

If you’d rather fork first and work via your own GitHub account, you can do so — the upstream instructions recommend adding an upstream remote. ([GitHub][1])

Step 3: Set Up Python Virtual Environment & Dependencies

Inside the oppia folder:

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools

Then install Oppia’s requirements:

pip install -r requirements.txt

Depending on version, Oppia may require additional system libraries (e.g., libffi, zlib-devel, openssl-devel). If you hit errors installing via pip, install the missing dev packages via dnf.

Step 4: Configure & Initialise Oppia

Within the oppia directory run:

python3 -m scripts.start

This script sets up the local dev server, downloads required dependencies (such as Google App Engine SDK), and fires up the service. ([GitHub][1])
Once running, by default you should be able to open your browser to http://localhost:8181 and see the Oppia splash page. On a server you may want to configure a domain and reverse-proxy via Nginx.

Step 5: Configure Nginx for Production Access

Assuming you have a domain like learning.mycompany.com, here’s a simple Nginx server block example:

server {
    listen 80;
    server_name learning.mycompany.com;

    location / {
        proxy_pass http://127.0.0.1:8181;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Then enable HTTPS (via Certbot / Let’s Encrypt) and restart Nginx:

sudo certbot --nginx -d learning.mycompany.com
sudo systemctl reload nginx

The NginX installation on CentOS 8 can be found on “How To Install NginX on CentOS 8” article.

Step 6: Post-Setup Checks & Loading Demo Content

• Visit https://learning.mycompany.com (or your configured URL) and confirm you see Oppia’s interface.
• Log in as an admin. In the admin panel load the demo explorations (virtual lessons) to test.
• Test creation of a new exploration: simple interactive lesson, multiple choice question, branching logic.
• Monitor logs: e.g., journalctl -u nginx and within the Oppia folder logs produced by the scripts.start process.

Troubleshooting Tips

• If you see “Failed to start server on port 8181”, check for port conflicts: sudo lsof -i :8181 and kill any blocking process.
• If HTTPS termination fails or loads slowly, ensure SELinux isn’t blocking Nginx: temporarily disable (setenforce 0) to test, then create correct policies.
• If dependencies fail to build (e.g., _bz2 or sqlite3 Python modules missing), install dev libs (zlib-devel, sqlite-devel) and rebuild the Python venv.
• Insufficient memory (less than ~4 GB) may cause processes (Elasticsearch, AppEngine/SDK) to crash — upgrade if necessary.

Performance & Production Considerations

• In production, you should not rely solely on the scripts.start dev server. Consider deploying Oppia under a WSGI server (Gunicorn, uWSGI) behind Nginx.
• Enable caching (Redis or Memcached) for frontend assets.
• Use a robust database backend (PostgreSQL or MySQL), rather than SQLite.
• Set up automatic backups of your data and assets.
• Monitor resource usage (CPU, RAM, disk I/O) especially if you plan to support many simultaneous learners.

Conclusion

You now have a fully functional installation of Oppia running on CentOS Stream 10. From here you can customise the platform, brand it, integrate with your LMS/SSO system, and create rich interactive lessons. This self-hosted setup gives you full control and flexibility. If you run into issues, consult the official Oppia Wiki & Troubleshooting pages.

For other open-source Learning Management System (LMS), we can choose Moodle. The Moodle installation guidance can be found on How to Install Moodle 4.4.3 on Ubuntu 24.04 : Step-by-Step Guide article.