This page describes how to install Open edX software on a single Ubuntu 16.04 64-bit server from scratch. This is for releases Ficus through Juniper.

• For Eucalyptus and earlier, see Native Open edX Ubuntu 12.04 64 bit Installation.
• For Koa, see Koa Native Open edX platform Ubuntu 20.04 64 bit Installation.
• For Lilac, see Lilac Native Open edX Platform Installation.

Server Requirements

The following server requirements will be fine for supporting hundreds of registered students on a single server.

Note: This will run MySQL, Memcache, Mongo, nginx, and all of the Open edX services (LMS, Studio, Forums, ORA, etc) on a single server. In production configurations we recommend that these services run on different servers and that a load balancer be used for redundancy. Setting up production configurations is beyond the scope of this wiki page.

• Ubuntu 16.04 amd64 (oraclejdk required). It may seem like other versions of Ubuntu will be fine, but they are not.  Only 16.04 is known to work.
• Minimum 8GB of memory
• At least one 2.00GHz CPU or EC2 compute unit
• Minimum 25GB of free disk, 50GB recommended for production servers

For hosting in Amazon we recommend an t2.large with at least a 50Gb EBS volume, see https://aws.amazon.com/ec2/pricing. Community Ubuntu AMIs have 8GB on the root directory, make sure to expand it before installing.

Installation instructions

WARNING:

• These instructions will potentially destroy the server they are run on, you should only do them on a freshly installed virtual machine. But if you still want to have a try to re-install the Open edX stack on the same server, please see this article for some issues you may face and how to fix them.

• By default ssh will only allow key based authentication. Please setup key based SSH logins or modify the configuration repo to allow for password based SSH logins before running Ansible.

NOTES:

• If you are running your services behind a proxy, please see here

Prep the server

Launch your Ubuntu 16.04 64-bit server and log in to it as a user that has full sudo privileges.

Update your Ubuntu package sources:

sudo apt-get update -y
sudo apt-get upgrade -y
sudo reboot

Installation

You will run a few scripts to accomplish the installation. Please read the contents of the scripts before running this to ensure you are aware of everything they will do: they are quite extensive. The scripts require that the running user can run commands as root via sudo.

1. Set the OPENEDX_RELEASE variable. You choose the version of software by setting the OPENEDX_RELEASE variable before running the commands. See Open edX Named Releases for the tags you can use.

   export OPENEDX_RELEASE=the-tag/you-want-to-install

2. Create a config.yml file.  This file specifies the hostname (and port, if needed) of the LMS and Studio.   Create a file in the current directory named config.yml, like this: 

   # The host names of LMS and Studio. Don't include the "https://" part:
   EDXAPP_LMS_BASE: "online.myeducation.org"
   EDXAPP_CMS_BASE: "studio.online.myeducation.org"

   Your LMS host and Studio host must either be the same hostname (on different ports), or Studio must be a subdomain of the LMS.  If you need a different configuration, you may need to also set EDXAPP_SESSION_COOKIE_DOMAIN.
    
   NOTE: Open edX and edX are registered trademarks.  You may not use "openedx." or "edx." as subdomains when naming your site. For more details, see the edX Trademark Policy.  Here are some examples of unacceptable domain names:

   • DON'T: openedx.yourdomain.org
   • DON'T: edx.yourdomain.org
   • DON'T: openedxyourdomain.org
   • DON'T: yourdomain-edx.com

3. Bootstrap the Ansible installation: 

   wget https://raw.githubusercontent.com/edx/configuration/$OPENEDX_RELEASE/util/install/ansible-bootstrap.sh -O - | sudo -E bash

4. Randomize passwords.  This step used to be optional, but as of Ironwood, it is required.  If this is to replace an older installation, copy your my-passwords.yml file from that installation.  If this is a new installation: 

   wget https://raw.githubusercontent.com/edx/configuration/$OPENEDX_RELEASE/util/install/generate-passwords.sh -O - | bash

   IMPORTANT: Be sure to save the generated my-passwords.yml in a safe place. If you ever need to access your services directly, you'll need these credentials. More details of password generation and other security measures are here: How to Override Default Configuration Passwords and Verify Exposed Services.
    

5. Install the Open edX software.  This can take some time, perhaps an hour. (Note: for Ginkgo and earlier, this file was called sandbox.sh): 

   wget https://raw.githubusercontent.com/edx/configuration/$OPENEDX_RELEASE/util/install/native.sh -O - | bash

6. You will need to finish configuring your server, for example to set the LMS_ROOT_URL setting, before everything will work properly.

• The Managing Open edX Tips and Tricks page may be useful.

Bad Suggestions (Arbitrary Upgrades)

Some Open edX components are outdated. If you see a message suggesting that you update something manually, don't do it -- something is probably relying on the outdated software remaining at that older version. Specifically:

• Ubuntu may alert you that a newer version of Ubuntu available when you SSH in to your server, and may suggest that you run do-release-upgrade to upgrade to that newer version. Don't do it.
• Pip may alert you that there is a newer version of pip available, and may suggest that you run pip install --upgrade pip to install it. Don't do it.

If you arbitrarily upgrade parts of Open edX software, things will break. Instead, you should submit a pull request to change the line in the Open edX project where that specific version of the software is defined. All pull requests need to be reviewed before they can be merged, and part of the review process will consist of testing the full platform with the updated software, identifying any breakages, and fixing them as part of the pull request.