Self-Hosting Open edX with Tutor

Open edX started as the platform behind edX — the MOOC provider founded by MIT and Harvard. It powers online courses for universities, corporations, and governments worldwide. Unlike traditional LMS platforms like Moodle, Open edX is built for massive scale: thousands of concurrent learners, video-heavy courses, and sophisticated assessment engines.

Self-hosting Open edX means running the same platform that delivers courses to millions — on your own infrastructure.

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose v2 installed (guide)
Python 3.9+ (for Tutor CLI)
8 GB RAM minimum (4 GB absolute minimum, performance suffers)
25 GB free disk space
Ports 80 and 443 available
A domain name (required for production)

Updated February 2026: Verified with latest Docker images and configurations.

How Open edX Deployment Works

Open edX does not use a standard docker-compose.yml file you write yourself. Instead, it uses Tutor — a Python CLI tool that generates and manages the entire Docker infrastructure.

Tutor handles:

Generating Docker Compose files from templates
Downloading and configuring all required services
Database migrations and initial setup
SSL certificate management via Caddy
Plugin management for extending functionality

Component	Technology	Purpose
LMS	Django/Python	Student-facing course platform
CMS (Studio)	Django/Python	Course authoring interface
MySQL	MariaDB/MySQL	Relational data (users, enrollments)
MongoDB	Document DB	Course content storage
Redis	Cache	Session and Django cache
Caddy	Reverse proxy	HTTPS termination, routing
Celery	Task queue	Background job processing

Installation

Install Tutor

pip install "tutor[full]==21.0.2"

Launch Open edX

tutor local launch

Tutor will prompt you for:

LMS domain (e.g., learn.yourdomain.com)
CMS domain (e.g., studio.yourdomain.com) — defaults to studio. prefix
Admin email and password
Platform name (displayed in the UI)
Contact email (for system notifications)

The launch process takes 5-10 minutes. It pulls Docker images, creates containers, runs database migrations, and starts all services.

Verify Installation

After launch completes:

LMS: https://learn.yourdomain.com
Studio: https://studio.yourdomain.com
Log in with the admin credentials you set during launch

Configuration

Tutor stores configuration in ~/.tutor/config.yml. View current settings:

tutor config printvalue LMS_HOST

Change settings interactively:

tutor config save --interactive

Or set specific values:

tutor config save --set LMS_HOST=learn.yourdomain.com
tutor config save --set PLATFORM_NAME="My Learning Platform"

After any configuration change, apply it:

tutor local launch

Key Configuration Options

Setting	Description	Default
`LMS_HOST`	Student-facing domain	—
`CMS_HOST`	Studio/authoring domain	`studio.{LMS_HOST}`
`PLATFORM_NAME`	Platform display name	”My Open edX”
`CONTACT_EMAIL`	System email address	—
`LANGUAGE_CODE`	Default language	`en`
`ENABLE_HTTPS`	SSL via Caddy	`true`

Email Configuration

tutor config save \
  --set SMTP_HOST=smtp.gmail.com \
  --set SMTP_PORT=587 \
  --set [email protected] \
  --set SMTP_PASSWORD=your-app-password \
  --set SMTP_USE_TLS=true

Advanced Configuration

Tutor Plugins

Extend Open edX with plugins:

# List available plugins
tutor plugins list

# Enable a plugin
tutor plugins enable discovery
tutor local launch

Popular plugins:

discovery — Course discovery and catalog
ecommerce — Paid courses
notes — Student note-taking
forum — Discussion forums (cs_comments_service)

Custom Themes

Build a custom theme:

tutor config save --set ENABLE_HTTPS=true
# Place theme in $(tutor config printroot)/env/build/openedx/themes/
tutor images build openedx
tutor local launch

Viewing Generated Docker Compose

Tutor generates its Docker Compose files at:

cat "$(tutor config printroot)/env/local/docker-compose.yml"

This file is auto-generated — edit it through Tutor configuration, not directly.

Reverse Proxy

Tutor includes Caddy as its built-in reverse proxy with automatic SSL certificate management via Let’s Encrypt. Ports 80 and 443 must be available on the host.

If you already run a reverse proxy (Nginx Proxy Manager, Traefik), disable Caddy and proxy to Tutor’s internal services. See Tutor’s reverse proxy documentation for details.

See Reverse Proxy Setup for general reverse proxy guidance.

Backup

Back up Tutor’s data directory:

# Full backup
tar -czf openedx-backup.tar.gz "$(tutor config printroot)"

Database-specific backup:

# MySQL dump
tutor local exec mysql mysqldump --all-databases > mysql-backup.sql

# MongoDB dump
tutor local exec mongodb mongodump --out /tmp/mongodump

See Backup Strategy for a complete approach.

Troubleshooting

Tutor Launch Hangs on Database Migration

Symptom: tutor local launch stalls during migration step. Fix: Check available RAM — Open edX migrations require at least 4 GB free. Monitor with docker stats. If RAM is exhausted, add swap or increase server resources.

”502 Bad Gateway” After Launch

Symptom: Caddy shows 502 when accessing the LMS domain. Fix: Services may still be starting. Wait 2-3 minutes after launch. Check: tutor local logs --tail 50 lms for errors. Common cause: DNS not pointing to your server.

Studio Gives “Permission Denied” Creating Courses

Symptom: Admin can’t create courses in Studio. Fix: The admin user needs staff + superuser flags: tutor local do createuser --staff --superuser admin [email protected]

”Connection Refused” to MongoDB or MySQL

Symptom: LMS/CMS can’t connect to database containers. Fix: Check container health: docker ps. If database containers are restarting, they may need more disk space. Check docker logs for the specific service.

High Memory Usage

Symptom: Server runs out of RAM, containers get OOM-killed. Fix: Open edX is memory-hungry. Production needs 8 GB RAM. Reduce Celery worker count in tutor config save --set CELERY_WORKERS=1 for small deployments.

Resource Requirements

Resource	Minimum	Recommended
RAM	4 GB	8 GB
CPU	2 cores	4 cores
Disk	8 GB	25 GB+
Containers	7-10	7-10
Bandwidth	Moderate	High (video streaming)

Open edX is the most resource-intensive LMS you can self-host. If you need something lighter, Moodle runs well on 2 GB RAM and Canvas LMS on 4 GB.

Verdict

If you need MOOC-style course delivery with video, assessments, certificates, and thousands of concurrent learners — Open edX is the only open-source option built for that scale. It’s what MIT, Harvard, and major corporations run.

The trade-off is complexity and resource demands. For a small team training 50 employees, Open edX is overkill — use Moodle instead. For a university or training company delivering courses to thousands, Open edX is worth the infrastructure investment.

FAQ

How does Open edX compare to Moodle?

Open edX is built for MOOC-scale delivery (video-heavy courses, thousands of learners). Moodle is built for classroom-style learning (assignments, quizzes, forums, smaller groups). See Moodle vs Open edX for a detailed comparison.

Can I run Open edX on a Raspberry Pi?

No. Open edX requires at least 4 GB RAM and x86_64 architecture. The smallest viable deployment is a 4 GB VPS. For small-scale education, use Moodle which runs on much less.

Do I need to know Python to manage Open edX?

Not for basic administration. Tutor CLI handles deployment and configuration. You’ll need Python knowledge only for custom theme development, plugin creation, or XBlock (custom component) development.