How to install openEDx v20 with tutor on windows OS with WSL2

Site Operators Site Operations Help
,
1

the main problem that make tutor not work is permission problem on the mysql docker - here is a guide the summary my expirence ( thank you claude.ai on the help )

# Complete Installation Guide - Open edX with Tutor v20 on Windows OS with WSL2

## Step 1: Initial Launch
bash
tutor dev launch

Step 2: Stop Services and Fix MySQL Permissions

:warning: Why is this step necessary?

MySQL in Docker runs with User ID 999, but in WSL2 the files are created with your user’s permissions. This causes MySQL to fail when accessing its data files. This fix changes the ownership of the data directory to UID 999 so MySQL can work properly.

Stop all services

tutor dev stop

Fix MySQL Permissions

# Stop MySQL
tutor dev stop mysql

# Display MySQL data directory location
echo "MySQL data directory: $(tutor config printroot)/data/mysql"

# Fix permissions (MySQL requires UID 999)
sudo chown -R 999:999 $(tutor config printroot)/data/mysql

# Verify the change
ls -la $(tutor config printroot)/data/mysql

Step 3: Restart MySQL and Initialize

# Restart MySQL
tutor dev start mysql -d

# Wait for initialization
sleep 60

# Check logs
tutor dev logs mysql --tail 30

# Attempt MySQL initialization
tutor dev do init --limit=mysql

Step 4: Relaunch and Start Core Services

# Relaunch
tutor dev launch

# Stop all services
tutor dev stop

# Start core services first
tutor dev start mysql mongodb redis meilisearch -d

# Wait for services to initialize
sleep 60

# Check that all services are running
docker ps | grep tutor_dev

Step 5: Initialize Services and Start Application

# Run full initialization
tutor dev do init

# Start application services
tutor dev start lms cms redis mfe -d

Important Note:

The initialization process must be run twice after the long installation

Step 6: Add Security Certificate for Studio

# Configure CSRF trusted origins
tutor config save --set "CSRF_TRUSTED_ORIGINS=http://apps.local.openedx.io:1999,http://local.openedx.io"

# Restart application services
tutor dev start lms cms mfe -d

Installation Flow Summary:

  1. :white_check_mark: Initial launch

  2. :white_check_mark: Fix MySQL permissions (critical for WSL2!)

  3. :white_check_mark: Initialize MySQL

  4. :white_check_mark: Start core services

  5. :white_check_mark: Full initialization (twice!)

  6. :white_check_mark: Security configuration

  7. :white_check_mark: Final startup

Additional Useful Commands:

# Check status of all services
docker ps | grep tutor_dev

# View logs for a specific service
tutor dev logs <service-name> --tail 50

# Stop all services
tutor dev stop

# Start all services
tutor dev start -d

This guide addresses the common MySQL permission issues that occur when running Open edX Tutor on Windows with WSL2. The key fix in Step 2 resolves the UID mismatch between the Docker container and the WSL2 filesystem.