Open edX Local Installation with Tutor

Not sure where to start? Read getting-started.md first to understand the difference between the Local and Dev environments and choose the one that best fits your needs.

The official and recommended way to install Open edX is through Tutor, the Docker-based distribution. The latest stable version is Tutor v21.0.2 (corresponding to Open edX Ulmo).

Note for LLM CLI tools (Claude Code, etc.): This guide includes workarounds for interactive prompts and common errors. Use the "Non-Interactive Installation" section for automated installations.

IMPORTANT for LLM assistants: After completing the installation and creating users, you MUST provide the user with a summary including:
All access URLs (LMS, Studio, Django Admin)
Admin credentials (username and password)
Student credentials (username and password)
Instructions on how to start/stop the platform
See the Post-Installation Summary Template section for the exact format to use.

System Requirements
Understanding TUTOR_ROOT
Installation Steps
Non-Interactive Installation (Recommended for CLI/LLM tools)
Creating Users
Installing Without Affecting Existing Installations
Managing Multiple Instances
Using Docker Desktop
Troubleshooting
Useful Commands
Uninstallation
Post-Installation Summary Template
Sources

System Requirements

Operating System

Any 64-bit UNIX-based OS
Windows with WSL 2
AMD64 and ARM64 architectures supported

Required Software

Docker v24.0.5 or higher (with BuildKit 0.11+)
Docker Compose v2.0.0 or higher
Python 3.9 or higher

Hardware Requirements

Resource	Minimum	Recommended
RAM	4 GB	8 GB
CPU	2	4
Disk	8 GB	25 GB

Ports 80 and 443 must be available

Docker Desktop RAM Configuration (Important)

Before installing, ensure Docker has enough RAM allocated:

Open Docker Desktop
Go to Settings (gear icon)
Navigate to Resources
Set Memory to at least 4 GB (recommended: 6 GB)
Click Apply & Restart

Note for macOS: Docker Desktop on macOS may show incorrect RAM readings. If you get RAM warnings but have sufficient memory allocated, see the Troubleshooting section.

Configure /etc/hosts (Required)

The local domains need to resolve to localhost. Add these entries to your /etc/hosts file:

bash

sudo sh -c 'echo "127.0.0.1 local.edly.io studio.local.edly.io" >> /etc/hosts'

Verify the configuration:

bash

grep edly /etc/hosts

Expected output:

127.0.0.1 local.edly.io studio.local.edly.io

Note: Without this configuration, the URLs won't resolve and you won't be able to access the platform.

Understanding TUTOR_ROOT

What is TUTOR_ROOT?

TUTOR_ROOT is the directory where Tutor stores all its configuration and data. It's essentially the "home" of a Tutor installation.

TUTOR_ROOT/
├── config.yml      # Main configuration (hostnames, passwords, plugins)
├── data/           # Persistent data (MySQL, MongoDB, uploaded files)
│   ├── mysql/
│   ├── mongodb/
│   ├── redis/
│   ├── lms/
│   ├── cms/
│   └── ...
└── env/            # Generated environment files

Default Locations

OS	Default TUTOR_ROOT
Linux	`~/.local/share/tutor`
macOS	`~/Library/Application Support/tutor`
Windows (WSL)	`~/.local/share/tutor`

Why is this important?

Different TUTOR_ROOT = Different installation
Each TUTOR_ROOT has its own configuration, data, and Docker containers
This allows running multiple isolated Open edX instances on the same machine

Installation Steps

Step 1: Install Docker

Make sure Docker is installed and running:

bash

docker --version
docker compose version

Step 2: Create a Dedicated Directory

bash

mkdir -p ~/tutor-local
cd ~/tutor-local

Step 3: Create a Python Virtual Environment

bash

python3 -m venv .venv
source .venv/bin/activate

Step 4: Install Dependencies (Ubuntu/Debian)

bash

sudo apt install python3 python3-pip libyaml-dev

Note for macOS: Dependencies are typically already available. Skip this step.

Step 5: Install Tutor

bash

pip install -U pip
pip install "tutor[full]"

Step 6: Set TUTOR_ROOT (Important for Isolation)

bash

export TUTOR_ROOT=~/tutor-local

Step 7: Launch Open edX

bash

tutor local launch

This command will:

Prompt you with configuration questions (site name, domain, etc.)
Generate configuration files
Download Docker images
Provision Docker containers
Deploy a complete Open edX platform

Step 8: Access the Platform

Once completed, access:

LMS: http://local.edly.io (or the domain you configured)
Studio: http://studio.local.edly.io

Non-Interactive Installation (Recommended for CLI/LLM tools)

The tutor local launch command is interactive and may fail when run from CLI tools or scripts. Use these steps instead:

Step 1: Set up environment

bash

# Create and enter directory
mkdir -p ~/tutor-local
cd ~/tutor-local

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install Tutor
pip install -U pip
pip install "tutor[full]"

# Set TUTOR_ROOT
export TUTOR_ROOT=~/tutor-local

Step 2: Configure Tutor (non-interactive)

bash

tutor config save \
  --set LMS_HOST=local.edly.io \
  --set CMS_HOST=studio.local.edly.io \
  --set ENABLE_HTTPS=false \
  --set PLATFORM_NAME="Open edX Local"

Step 3: Enable plugins

bash

tutor plugins enable mfe
tutor config save

Step 4: Start containers

bash

tutor local start -d

Step 5: Initialize the platform

This step creates databases, runs migrations, and sets up the platform. It may take several minutes.

bash

tutor local do init

Step 6: Verify installation

bash

# Check all containers are running
docker ps --format "table {{.Names}}\t{{.Status}}" | grep tutor_local

Expected output:

tutor_local-lms-1           Up X minutes
tutor_local-cms-1           Up X minutes
tutor_local-mfe-1           Up X minutes
tutor_local-mysql-1         Up X minutes
tutor_local-mongodb-1       Up X minutes
tutor_local-redis-1         Up X minutes
tutor_local-caddy-1         Up X minutes
...

Step 7: Verify URLs are accessible

bash

# Check LMS is responding
curl -s -o /dev/null -w "%{http_code}" http://local.edly.io

# Check Studio is responding
curl -s -o /dev/null -w "%{http_code}" http://studio.local.edly.io

Expected output: 200 or 302 (redirect to login).

If you get 000 or connection errors:

Verify /etc/hosts is configured correctly
Check container logs: tutor local logs -f lms
Try restarting: tutor local restart

Creating Users

After installation, you need to create users to access the platform.

Create an Admin User (Staff/Superuser)

bash

tutor local do createuser --staff --superuser admin admin@example.com -p admin123

This creates:

Username: admin
Email: admin@example.com
Password: admin123
Permissions: Staff + Superuser (full admin access)

Create a Student User

bash

tutor local do createuser student student@example.com -p student123

This creates:

Username: student
Email: student@example.com
Password: student123
Permissions: Regular user (student)

Access URLs

User Type	Login URL
Admin	http://local.edly.io/admin
Student	http://local.edly.io/login
Studio (Admin only)	http://studio.local.edly.io

Installing Without Affecting Existing Installations

If you already have a Tutor installation (dev or local) and want to install a new instance without affecting it, follow these steps:

1. Stop the existing instance first (to free ports)

bash

# Navigate to your existing installation and stop it
tutor dev stop   # or tutor local stop

2. Create a completely separate directory

bash

mkdir -p ~/tutor-new-instance
cd ~/tutor-new-instance

3. Create a new virtual environment

bash

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install "tutor[full]"

4. Set a different TUTOR_ROOT

bash

export TUTOR_ROOT=~/tutor-new-instance

5. Launch the new instance

Use either the interactive or non-interactive method from above.

What stays isolated?

Resource	Instance 1	Instance 2
Configuration	`TUTOR_ROOT_1/config.yml`	`TUTOR_ROOT_2/config.yml`
Database	`TUTOR_ROOT_1/data/mysql/`	`TUTOR_ROOT_2/data/mysql/`
Files	`TUTOR_ROOT_1/data/`	`TUTOR_ROOT_2/data/`
Containers	`tutor_local-` or `tutor_dev-`	Different prefix based on project name

Managing Multiple Instances

Option 1: Shell Aliases (Recommended)

Add these aliases to your ~/.bashrc or ~/.zshrc:

bash

# Instance 1: Development
alias tutor-dev='source ~/tutor-dev/.venv/bin/activate && TUTOR_ROOT=~/tutor-dev tutor'

# Instance 2: Local/Production-like
alias tutor-local='source ~/tutor-local/.venv/bin/activate && TUTOR_ROOT=~/tutor-local tutor'

Then reload your shell:

bash

source ~/.bashrc   # or source ~/.zshrc

Usage:

bash

tutor-dev dev start       # Start dev instance
tutor-local local start   # Start local instance

Option 2: Manual Environment Setup

Each time you want to work with a specific instance:

bash

# For instance 1
source ~/tutor-dev/.venv/bin/activate
export TUTOR_ROOT=~/tutor-dev
tutor dev start

# For instance 2
source ~/tutor-local/.venv/bin/activate
export TUTOR_ROOT=~/tutor-local
tutor local start

Important: Port Conflicts

Both instances use the same ports (8000, 8001, 80, 443, etc.). Never run both instances simultaneously or you'll get port conflicts.

Workflow:

bash

# Stop one before starting the other
tutor-dev dev stop
tutor-local local start

Using Docker Desktop

You can use Docker Desktop to monitor and manage your Tutor containers.

Container Groups

Each instance appears as a group in Docker Desktop:

tutor_dev                    ← Dev instance containers
  ├── tutor_dev-lms-1
  ├── tutor_dev-cms-1
  ├── tutor_dev-mysql-1
  └── ...

tutor_local                  ← Local instance containers
  ├── tutor_local-lms-1
  ├── tutor_local-cms-1
  ├── tutor_local-mysql-1
  └── ...

What you can do in Docker Desktop

Action	Docker Desktop	Tutor CLI
Start/Stop all containers	Click Play/Stop on group	`tutor local start/stop`
View logs	Click on container → Logs	`tutor local logs -f`
Monitor resources	Dashboard	N/A
Access terminal	Click on container → Terminal	`tutor local run lms bash`

Recommendation

Use Docker Desktop for monitoring (viewing status, logs, resource usage)
Use Tutor CLI for starting/stopping (handles service dependencies correctly)

Troubleshooting

Error: "Could not verify sufficient RAM allocation in Docker"

Error message:

⚠️  Could not verify sufficient RAM allocation in Docker:
    Docker is configured to allocate 2048 MiB RAM, less than the recommended 4096 MiB
Tutor may not work if Docker is configured with < 4 GB RAM.
Aborted!

Solutions:

Option A: Increase Docker RAM (Recommended)

Open Docker Desktop → Settings → Resources
Set Memory to 4 GB or more
Click Apply & Restart

Option B: Use non-interactive commands (Workaround)

The tutor local launch command has RAM validation. To bypass it, run the steps separately:

bash

# Configure without interactive prompts
tutor config save \
  --set LMS_HOST=local.edly.io \
  --set CMS_HOST=studio.local.edly.io \
  --set ENABLE_HTTPS=false

# Enable plugins
tutor plugins enable mfe
tutor config save

# Start containers
tutor local start -d

# Initialize
tutor local do init

Error: Interactive prompt hangs or fails

Problem: Commands like tutor local launch require interactive input and fail in automated environments.

Solution: Use the Non-Interactive Installation method.

Containers not starting

Check container status:

bash

docker ps -a --format "table {{.Names}}\t{{.Status}}" | grep tutor

Check logs:

bash

tutor local logs -f lms
tutor local logs -f cms

Restart all services:

bash

tutor local stop
tutor local start -d

Port already in use

Error: Bind for 0.0.0.0:80 failed: port is already allocated

Solution:

Check what's using the port: lsof -i :80

Stop the conflicting service or stop other Tutor instances:

bash

tutor dev stop    # If dev instance is running
tutor local stop  # If another local instance is running

Database connection issues after restart

Solution: Wait a few seconds for MySQL to fully start, then restart LMS/CMS:

bash

tutor local restart lms cms

MySQL authentication error after init

Error message:

django.db.utils.OperationalError: (1045, "Access denied for user 'openedx'@'...' (using password: YES)")

Cause: Sometimes the MySQL credentials aren't synced properly after the initial setup.

Solution: Stop and restart all services:

bash

tutor local stop
tutor local start -d

Wait a few seconds for MySQL to fully initialize, then verify with:

bash

curl -s -o /dev/null -w "%{http_code}" http://local.edly.io

Useful Commands

Basic Operations

bash

# Check container status
tutor local status

# Stop the platform
tutor local stop

# Start the platform
tutor local start

# Restart the platform
tutor local restart

# View logs (all services)
tutor local logs -f

# View logs (specific service)
tutor local logs -f lms
tutor local logs -f cms

User Management

bash

# Create admin user
tutor local do createuser --staff --superuser admin admin@example.com -p admin123

# Create student user
tutor local do createuser student student@example.com -p student123

# Change user password
tutor local run lms ./manage.py lms shell -c "
from django.contrib.auth import get_user_model
u = get_user_model().objects.get(username='admin')
u.set_password('newpassword')
u.save()
"

Configuration

bash

# Check current TUTOR_ROOT
tutor config printroot

# View a config value
tutor config printvalue LMS_HOST

# List enabled plugins
tutor plugins list

# Enable a plugin
tutor plugins enable <plugin-name>
tutor config save

Container Access

bash

# Run bash in LMS container
tutor local run lms bash

# Run Django shell
tutor local run lms ./manage.py lms shell

# Run a Django management command
tutor local run lms ./manage.py lms <command>

Uninstallation

Remove a specific instance

bash

# Set the TUTOR_ROOT of the instance you want to remove
export TUTOR_ROOT=~/tutor-local

# Stop and remove containers
tutor local dc down --remove-orphans

# Remove all data and configuration
rm -rf ~/tutor-local

Complete cleanup

bash

# Remove containers from all instances
tutor local dc down --remove-orphans
tutor dev dc down --remove-orphans

# Remove configuration and data
rm -rf "$(tutor config printroot)"

# Uninstall Tutor from virtual environment
pip uninstall tutor

# Remove Docker images (optional, frees disk space)
docker rmi $(docker images | grep "openedx" | awk '{print $3}')

Quick Reference

Installation Checklist

[ ] Docker installed and running (v24.0.5+)
[ ] Docker has 4+ GB RAM allocated
[ ] Python 3.9+ installed
[ ] Created dedicated directory for installation
[ ] Created Python virtual environment
[ ] Installed Tutor via pip
[ ] Set TUTOR_ROOT environment variable
[ ] Ran tutor local launch or non-interactive steps
[ ] Created admin user
[ ] Created student user (optional)
[ ] Verified access to LMS and Studio

Default URLs

Service	URL
LMS	http://local.edly.io
Studio	http://studio.local.edly.io
Admin	http://local.edly.io/admin

Post-Installation Summary Template

For LLM assistants: After completing the installation, copy and fill in this template to provide the user with all necessary information:

markdown

## Installation Complete

Your Open edX instance is now running.

### Access URLs

| Service | URL | Description |
|---------|-----|-------------|
| **LMS** | http://local.edly.io | Main learning platform for students |
| **Studio** | http://studio.local.edly.io | Course authoring tool (admin only) |
| **Django Admin** | http://local.edly.io/admin | Backend administration panel |

### User Credentials

#### Administrator
| Field | Value |
|-------|-------|
| Username | admin |
| Password | admin123 |
| Email | admin@example.com |
| Access | LMS, Studio, Django Admin |

#### Student
| Field | Value |
|-------|-------|
| Username | student |
| Password | student123 |
| Email | student@example.com |
| Access | LMS only |

### Managing the Platform

#### Start the platform
\`\`\`bash
source ~/tutor-local/.venv/bin/activate
export TUTOR_ROOT=~/tutor-local
tutor local start
\`\`\`

#### Stop the platform
\`\`\`bash
source ~/tutor-local/.venv/bin/activate
export TUTOR_ROOT=~/tutor-local
tutor local stop
\`\`\`

#### Or use Docker Desktop
Open Docker Desktop and find the `tutor_local` container group. Use the Play/Stop buttons to control the platform.

### Next Steps
1. Log in to Studio and create your first course
2. Enroll the student user in your course
3. Test the learning experience from the student perspective

Note: Adjust the paths, URLs, and credentials based on the actual values used during installation.

Open edX Local Installation with Tutor ​

Table of Contents ​

System Requirements ​

Operating System ​

Required Software ​

Hardware Requirements ​

Docker Desktop RAM Configuration (Important) ​

Configure /etc/hosts (Required) ​

Understanding TUTOR_ROOT ​

What is TUTOR_ROOT? ​

Default Locations ​

Why is this important? ​

Installation Steps ​

Step 1: Install Docker ​

Step 2: Create a Dedicated Directory ​

Step 3: Create a Python Virtual Environment ​

Step 4: Install Dependencies (Ubuntu/Debian) ​

Step 5: Install Tutor ​

Step 6: Set TUTOR_ROOT (Important for Isolation) ​

Step 7: Launch Open edX ​

Step 8: Access the Platform ​

Non-Interactive Installation (Recommended for CLI/LLM tools) ​

Step 1: Set up environment ​

Step 2: Configure Tutor (non-interactive) ​

Step 3: Enable plugins ​

Step 4: Start containers ​

Step 5: Initialize the platform ​

Step 6: Verify installation ​

Step 7: Verify URLs are accessible ​

Creating Users ​

Create an Admin User (Staff/Superuser) ​

Create a Student User ​

Access URLs ​

Installing Without Affecting Existing Installations ​

1. Stop the existing instance first (to free ports) ​

2. Create a completely separate directory ​

3. Create a new virtual environment ​

4. Set a different TUTOR_ROOT ​

5. Launch the new instance ​

What stays isolated? ​

Managing Multiple Instances ​

Option 1: Shell Aliases (Recommended) ​

Option 2: Manual Environment Setup ​

Important: Port Conflicts ​

Using Docker Desktop ​

Container Groups ​

What you can do in Docker Desktop ​

Recommendation ​

Troubleshooting ​

Error: "Could not verify sufficient RAM allocation in Docker" ​

Option A: Increase Docker RAM (Recommended) ​

Option B: Use non-interactive commands (Workaround) ​

Error: Interactive prompt hangs or fails ​

Containers not starting ​

Port already in use ​

Database connection issues after restart ​

MySQL authentication error after init ​

Useful Commands ​

Basic Operations ​

User Management ​

Configuration ​

Container Access ​

Uninstallation ​

Remove a specific instance ​

Complete cleanup ​

Quick Reference ​

Installation Checklist ​

Default URLs ​

Post-Installation Summary Template ​

Sources ​

Open edX Local Installation with Tutor

Table of Contents

System Requirements

Operating System

Required Software

Hardware Requirements

Docker Desktop RAM Configuration (Important)

Configure /etc/hosts (Required)

Understanding TUTOR_ROOT

What is TUTOR_ROOT?

Default Locations

Why is this important?

Installation Steps

Step 1: Install Docker

Step 2: Create a Dedicated Directory

Step 3: Create a Python Virtual Environment

Step 4: Install Dependencies (Ubuntu/Debian)

Step 5: Install Tutor

Step 6: Set TUTOR_ROOT (Important for Isolation)

Step 7: Launch Open edX

Step 8: Access the Platform

Non-Interactive Installation (Recommended for CLI/LLM tools)

Step 1: Set up environment

Step 2: Configure Tutor (non-interactive)

Step 3: Enable plugins

Step 4: Start containers

Step 5: Initialize the platform

Step 6: Verify installation

Step 7: Verify URLs are accessible

Creating Users

Create an Admin User (Staff/Superuser)

Create a Student User

Access URLs

Installing Without Affecting Existing Installations

1. Stop the existing instance first (to free ports)

2. Create a completely separate directory

3. Create a new virtual environment

4. Set a different TUTOR_ROOT

5. Launch the new instance

What stays isolated?

Managing Multiple Instances

Option 1: Shell Aliases (Recommended)

Option 2: Manual Environment Setup

Important: Port Conflicts

Using Docker Desktop

Container Groups

What you can do in Docker Desktop

Recommendation

Troubleshooting

Error: "Could not verify sufficient RAM allocation in Docker"

Option A: Increase Docker RAM (Recommended)

Option B: Use non-interactive commands (Workaround)

Error: Interactive prompt hangs or fails

Containers not starting

Port already in use

Database connection issues after restart

MySQL authentication error after init

Useful Commands

Basic Operations

User Management

Configuration

Container Access

Uninstallation

Remove a specific instance

Complete cleanup

Quick Reference

Installation Checklist

Default URLs

Post-Installation Summary Template

Sources