Deploying Open edX

Introduction

Open edX is the open-source learning management system (LMS) that powers edX.org and thousands of other online learning platforms worldwide. Originally developed by MIT and Harvard, Open edX provides a comprehensive platform for creating and delivering online courses with features like video lectures, interactive assessments, discussion forums, and verified certificates.

As one of the most mature and feature-rich open-source LMS platforms available, Open edX handles everything from small internal training programs to massive open online courses (MOOCs) with thousands of learners. The platform is highly customizable and has been adopted by universities, corporations, and governments globally.

Key highlights of Open edX:

• Course Authoring: Visual course builder with drag-and-drop components
• Video Lectures: Integrated video player with transcripts and captions
• Assessment Tools: Multiple question types, auto-grading, and manual grading
• Discussion Forums: Threaded discussions with voting and moderation
• Certificates: Customizable course completion certificates
• Mobile Apps: Native iOS and Android apps for learners
• Analytics: Comprehensive learning analytics and dashboards
• LTI Support: Integrate external learning tools
• Multi-tenancy: Host multiple organizations on one instance
• 100% Open Source: AGPL licensed with extensive community

This guide walks through deploying Open edX on Klutch.sh using Tutor, the official Docker-based deployment method, and configuring your learning platform.

Why Deploy Open edX on Klutch.sh

Deploying Open edX on Klutch.sh provides several advantages for online learning:

Simplified Deployment: Klutch.sh handles infrastructure while Tutor simplifies Open edX deployment complexity.

Data Ownership: Keep learner data and course content on your own infrastructure.

Persistent Storage: Attach volumes for courses, user data, and media that persist securely.

HTTPS by Default: Automatic SSL certificates for secure learning experiences.

Scalable Resources: Scale from small pilots to large deployments by adjusting resources.

Custom Domains: Use your institution’s domain for a branded learning experience.

Prerequisites

Before deploying Open edX on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Significant resources (minimum 8GB RAM recommended for production)
• A custom domain for your learning platform
• SMTP server for email notifications
• Basic familiarity with Docker and containerized applications

Understanding Open edX Architecture

Open edX is a complex, multi-service application:

LMS (Learning Management System): The learner-facing application for taking courses.

CMS (Studio): The course authoring tool for creating and managing content.

MySQL Database: Stores user data, enrollments, grades, and course structure.

MongoDB: Stores course content, assets, and discussion forum data.

Elasticsearch: Powers search functionality across courses and content.

Redis: Caching and session storage for improved performance.

Celery Workers: Background task processing for emails, grading, and analytics.

Caddy/Nginx: Web server and reverse proxy.

Preparing Your Repository

Create a GitHub repository with your Open edX configuration using Tutor.

Repository Structure

openedx-deploy/
├── Dockerfile
├── config/
│   └── config.yml
├── scripts/
│   └── init.sh
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for Open edX with Tutor:

FROM python:3.9-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    curl \
    git \
    docker.io \
    docker-compose \
    && rm -rf /var/lib/apt/lists/*

# Install Tutor
RUN pip install tutor

# Create working directory
WORKDIR /openedx

# Copy configuration
COPY config/ /openedx/config/
COPY scripts/ /openedx/scripts/
RUN chmod +x /openedx/scripts/*.sh

# Initialize Tutor environment
RUN tutor config save --set LMS_HOST=localhost --set CMS_HOST=studio.localhost

# Expose ports
EXPOSE 80 443

# Start script
CMD ["/openedx/scripts/init.sh"]

Creating Configuration

Create config/config.yml with your Open edX settings:

# Open edX Tutor configuration

# Platform settings
PLATFORM_NAME: "Your Learning Platform"
CONTACT_EMAIL: admin@example.com

# Domain settings (override via environment variables)
LMS_HOST: learn.example.com
CMS_HOST: studio.example.com

# Email settings
SMTP_HOST: smtp.example.com
SMTP_PORT: 587
SMTP_USE_TLS: true
SMTP_USERNAME: your-smtp-user
SMTP_PASSWORD: your-smtp-password

# Feature flags
ENABLE_HTTPS: true
ENABLE_WEB_PROXY: true

# Resource limits
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
OPENEDX_MYSQL_PASSWORD: ${OPENEDX_MYSQL_PASSWORD}
SECRET_KEY: ${SECRET_KEY}

Creating Initialization Script

Create scripts/init.sh:

#!/bin/bash
set -e

echo "Initializing Open edX..."

# Apply configuration from environment variables
tutor config save \
    --set LMS_HOST=${LMS_HOST:-localhost} \
    --set CMS_HOST=${CMS_HOST:-studio.localhost} \
    --set PLATFORM_NAME="${PLATFORM_NAME:-Open edX}" \
    --set CONTACT_EMAIL=${CONTACT_EMAIL:-admin@localhost}

# Start Open edX services
tutor local start -d

# Wait for services to be ready
sleep 30

# Run database migrations if needed
tutor local run lms ./manage.py lms migrate
tutor local run cms ./manage.py cms migrate

# Keep container running
tail -f /dev/null

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
.DS_Store

Deploying Open edX on Klutch.sh

Follow these steps to deploy your Open edX instance:

Generate Secure Keys

Generate required secrets:

# Secret key
openssl rand -base64 32

# MySQL passwords
openssl rand -base64 24

Configure Your Domain

Plan your domain structure:

• learn.example.com - LMS (learner access)
• studio.example.com - CMS (course authoring)

Push Your Repository to GitHub

Initialize and push your configuration:

git init
git add .
git commit -m "Initial Open edX configuration"
git remote add origin https://github.com/yourusername/openedx-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project for your learning platform.

Create a New App

Create a new app within your project and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 80

Set Environment Variables

Configure the following environment variables:

Variable	Value
LMS_HOST	learn.example.com
CMS_HOST	studio.example.com
PLATFORM_NAME	Your Learning Platform
CONTACT_EMAIL	admin@example.com
SECRET_KEY	Your generated secret key
MYSQL_ROOT_PASSWORD	Your MySQL root password
OPENEDX_MYSQL_PASSWORD	Your MySQL user password
SMTP_HOST	Your SMTP server
SMTP_USERNAME	SMTP username
SMTP_PASSWORD	SMTP password

Allocate Sufficient Resources

Open edX requires significant resources:

• CPU: 4+ cores recommended
• Memory: 8GB minimum, 16GB recommended
• Storage: 50GB+ for data

Attach Persistent Volumes

Add persistent volumes for Open edX:

Mount Path	Recommended Size	Purpose
/openedx/data	100 GB	MySQL and MongoDB data
/openedx/media	50 GB	Course media and uploads
/openedx/config	1 GB	Tutor configuration

Configure Custom Domains

Add both domains in Klutch.sh:

1. Add learn.example.com for LMS
2. Add studio.example.com for CMS

Configure DNS A records for both domains.

Deploy Your Application

Click Deploy to build and start Open edX.

Create Admin Account

After deployment, create the admin account:

tutor local run lms ./manage.py lms createsuperuser

Access Your Platform

Navigate to your LMS domain to access the learning platform.

Initial Setup and Configuration

Accessing Studio

Access Studio (CMS) at your CMS domain to create courses:

1. Log in with your superuser account
2. Create a new course
3. Configure course settings
4. Add content modules

Creating Your First Course

Create courses in Studio:

1. Click “New Course”
2. Enter course name, organization, and number
3. Set course dates and enrollment options
4. Add sections, subsections, and units

Course Structure

Open edX courses follow a hierarchy:

Course
├── Section (Week 1)
│   ├── Subsection (Lesson 1)
│   │   ├── Unit (Video Lecture)
│   │   ├── Unit (Reading)
│   │   └── Unit (Quiz)
│   └── Subsection (Lesson 2)
└── Section (Week 2)

Adding Content

Add various content types:

• Video: Upload or embed videos with transcripts
• HTML: Rich text content and formatted materials
• Problems: Multiple choice, coding, and other assessments
• Discussions: Forum topics for learner interaction

Managing Learners

User Registration

Configure registration options:

1. Go to LMS admin panel
2. Configure registration settings
3. Set email verification requirements
4. Configure allowed email domains (if needed)

Enrollment Management

Manage course enrollments:

• Self-enrollment: Learners enroll themselves
• Manual enrollment: Admin adds learners
• Bulk enrollment: CSV upload for many learners

User Roles

Assign roles to users:

Role	Description
Student	Take courses and submit work
Course Staff	View learner data for specific courses
Course Admin	Manage course content and settings
Global Staff	Manage all courses
Superuser	Full platform administration

Assessments and Grading

Question Types

Open edX supports various assessment types:

• Multiple choice (single and multi-select)
• Dropdown selection
• Numerical input
• Text input
• Code submission
• File upload
• Peer assessment

Grading Configuration

Configure grading policies:

1. Set grade cutoffs (A, B, C, etc.)
2. Configure assignment weights
3. Set up late submission policies
4. Enable/disable grade passback

Certificates

Create course completion certificates:

1. Design certificate template
2. Configure certificate requirements
3. Enable web certificates
4. Optionally enable verified certificates

Discussion Forums

Forum Configuration

Set up discussions:

1. Enable discussions in course settings
2. Create discussion topics
3. Configure moderation settings
4. Set up cohorts for targeted discussions

Moderation

Moderate discussions effectively:

• Pin important posts
• Close threads when resolved
• Flag and remove inappropriate content
• Assign moderator roles

Analytics and Reporting

Learner Analytics

Track learner progress:

• Enrollment statistics
• Completion rates
• Assessment performance
• Video engagement

Course Insights

Access Insights dashboard:

1. View engagement metrics
2. Analyze assessment results
3. Monitor discussion activity
4. Track certificate generation

Data Export

Export data for analysis:

• Grade reports (CSV)
• Learner profiles
• Assessment responses
• Discussion data

Customization

Theming

Customize the platform appearance:

# Create custom theme
tutor config save --set COMPREHENSIVE_THEME_DIR=/openedx/themes/custom

Theme elements:

• Logo and branding
• Color scheme
• Header and footer
• Email templates

Plugins

Extend functionality with Tutor plugins:

# Install plugin
pip install tutor-mfe

# Enable plugin
tutor plugins enable mfe

Popular plugins:

• MFE: Micro-frontends for modern UI
• Notes: Learner note-taking
• Discovery: Course discovery service

Production Best Practices

Performance Optimization

• Caching: Ensure Redis is properly configured
• CDN: Use a CDN for static assets
• Database: Optimize MySQL and MongoDB
• Workers: Scale Celery workers for background tasks

Security Recommendations

• HTTPS Only: Enforce HTTPS for all connections
• Strong Passwords: Require strong user passwords
• Regular Updates: Keep Open edX updated
• Backup Secrets: Securely store all credentials

Backup Strategy

Regular backups should include:

1. MySQL database
2. MongoDB database
3. Course media and uploads
4. Tutor configuration

Monitoring

Monitor critical metrics:

• Server resource usage
• Database performance
• Celery queue length
• Error rates

Troubleshooting Common Issues

Services Not Starting

Symptoms: Open edX services fail to start.

Solutions:

• Check resource allocation
• Verify database connectivity
• Review Tutor logs
• Ensure all dependencies are available

Course Content Issues

Symptoms: Courses not loading or displaying incorrectly.

Solutions:

• Check MongoDB connectivity
• Verify asset storage
• Review CMS logs
• Clear caches

Email Not Sending

Symptoms: Learners not receiving emails.

Solutions:

• Verify SMTP configuration
• Check Celery worker status
• Review email queue
• Test SMTP connectivity

Performance Problems

Symptoms: Slow page loads or timeouts.

Solutions:

• Increase resource allocation
• Optimize database queries
• Enable caching
• Scale workers

Additional Resources

• Open edX Documentation
• Open edX GitHub
• Tutor Documentation
• Open edX Community Forums
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Open edX on Klutch.sh gives you access to a world-class learning management system that powers education for millions of learners globally. The combination of Open edX’s comprehensive features and Klutch.sh’s container management means you can deliver professional online courses without managing complex infrastructure.

With course authoring tools, video integration, assessments, discussions, and certificates, Open edX handles everything from small training programs to large-scale online education. Whether you’re a university offering MOOCs, a company providing employee training, or an organization sharing knowledge, Open edX on Klutch.sh provides the foundation for impactful online learning.