Open edX is a remarkably stable platform, but if you’re having problems with your instance then hopefully this troubleshooting guide will help. This is a collection of the configuration and maintenance related problems that I routinely encounter, along with the prescriptive measures with which I’ve had the most success.

The cure-all: Restarting the platform

When your Open edX installation is misbehaving and  you’re unsure of your next step, I always like to begin with a reboot. It can’t hurt, and occasionally you’re pleasantly surprised to find your instance in good health immediately afterwards. The commands are as follows:

  • A cold boot (reboots the entire server)
    sudo reboot
  • A warm boot (restarts Open edX)
    # These are the commands for restarting the LMS and CMS beginning with Gingko
    /edx/bin/supervisorctl restart lms
    /edx/bin/supervisorctl restart cms
    # If you're running a previous version of Open edX then use this command instead
    /edx/bin/supervisorctl restart edxapp:
    # This is the command to stop and restart the RabbitMQ Celery workers
    /edx/bin/supervisorctl restart edxapp_worker:

Forgot Open edX admin username or password

This is nothing more than a minor speed bump provided that you still have terminal access via SSH. Open edX relies on a single master user list that is stored in MySQL in the table “edxapp.auth_user”. You have a few options for how to regain administrative access to the LMS and CMS depending on your level of comfort with the different technologies.

  1. Review the row-level contents of the MySQL table edxapp.auth_user. You can login to MySQL from a Linux terminal window using the command line. By default the root password of the local instance of MySQL is left blank. If you’re unable to login as root then Open edX also creates a MySQL user named edxapp, the password of which you’ll find in the master password file that is (hopefully) saved in /home/ubuntu/my-passwords.yml.
    – To login to MySQL from the command line: mysql -u root -p
    – To view all users: select * from auth_user;
    – To logout of MySQL: exit
    Once you find your user name and email address you can use the LMS login screen to request a password reset.
  2. Create a new user with the Django Command Line Interface. If you’re more comfortable working with Django then you can create a completely new superuser account with the following command, substituting “mcdaniel” with your username and “” with your email address:
    sudo su edxapp -s /bin/bash
    /edx/bin/python.edxapp /edx/bin/manage.edxapp lms lmcdaniel staff --staff --superuser --settings=aws

    To change the password execute this line:

    sudo -u www-data /edx/bin/python.edxapp /edx/app/edxapp/edx-platform/ lms --settings aws changepassword mcdaniel
  3. Insert a new user record into the MySQL table “edxapp.auth_user”. If all else fails then you can force a new record into the user table. Take note however that password values are encrypted and thus you cannot simply insert a password value into this table. Instead you’ll need to either use the Django console command from option 2 above, or request a password reset from the LMS login screen. The insert statement will be of the form:
    INSERT edxapp.auth_user (is_superuser, username, first_name, last_name, email, is_staff, is_active) VALUES(1, 'mcdaniel', 'Lawrence', 'McDaniel', '', 1, 1);