The Open edX community can share knowledge and improvements more easily when most people use the same stable, consistent version of the Open edX codebase. To that end, edX is creating a series of named releases for Open edX, which are distinct from the weekly deployments to edx.org and have a longer release cycle (on the order of several months between each release). These named releases will be tested both by edX and by the Open edX community, and with each subsequent named release we will include instructions for how to upgrade from the previous named release.

Current Named Releases

named-release/aspen

Note that "release candidates" are not final yet, which is why they do not have a release date in this table. We encourage the Open edX community to test release candidates for several days and report any issues, so that they can be fixed before the new release is declared. In git, release candidates are branches, while releases are tags.

Download Via BitTorrent

In order to install devstack or fullstack, you must download a box file, which is basically a pre-packaged server that Vagrant unpacks onto your computer. The box files for Open edX are rather large (roughly 3GB), and some people with slow or unreliable internet connections have reported difficultly downloading the entire file: their internet connection breaks before the entire file is downloaded, which results in a useless, corrupted file. To solve this problem, we're publishing these box files via BitTorrent, which is a file sharing protocol that allows people to download files in a peer-to-peer fashion. One of the benefits of BitTorrent is that files downloads can easily be paused and resumed, and if the internet connection breaks, no data is lost or corrupted: the download will resume right where it left off as soon as the computer reconnects to the internet. Devstack and fullstack use different boxes, so there are different BitTorrent download links for each.

Once you've downloaded the entire box file, you must import it into Vagrant, so that Vagrant knows that it doesn't need to re-download the file. To do this, run:

$ vagrant box add /path/to/downloaded/file.box --name $RELEASE-$STACK-$VERSION

The name that you pass to the --name flag should be the same name in the Vagrantfile, and it will generally look something like birch-devstack. Check the Vagrantfile to see exactly what name you need. Once you've downloaded the box file and imported it correctly, you can move on to the standard installation instructions, and Vagrant will automatically know to use the downloaded file rather than trying to download it again. (If Vagrant does try to download the file again, you imported it incorrectly. Check the Vagrantfile to be sure you specified the proper name.)

Installing a Named Release

To set up a devstack or fullstack VM using a named release, simply set the OPENEDX_RELEASE environment variable to the release's git tag before running vagrant up. To install a named release without using Vagrant, simply check out the release's git tag in each git repository before running Open edX as you normally would. See the named releases documentation in the configuration repo for more information and specific instructions.

Updating a Named Release

To migrate from Aspen to Birch, we've provided a migration script to help you out. It's designed to be run on the server where the Open edX software is running. If you are using a Vagrant VM, you need to run this script when you are already inside the Vagrant VM. To download and run the migration script, do the following:

$ wget https://raw.githubusercontent.com/edx/configuration/master/util/vagrant/migrate.sh -O
$ chmod a+x migrate.sh
$ ./migrate.sh

The script also accepts certain arguments to change how it works – run ./migrate.sh -h to see a help message.

Note that Birch depends on MySQL 5.6 and MongoDB 2.6.4, while Aspen uses MySQL 5.5 and MongoDB 2.4.7. It is highly recommended that you upgrade your databases yourself, before running the migration script. If you don't, the script will attempt to upgrade your databases for you, and you run the risk of corrupting all your data if something goes wrong.

Security Updates

If security vulnerabilities or other serious problems (such as data loss) are discovered in the most recent named release, edX will release a new version of that named release that includes the fix. We will not make patches of any named releases before the most recent one. We are still working on the details of how often to update a named release. We will publicly announce the security issue, and encourage the Open edX community to update their installations to close the vulnerability. If you have found a security vulnerability in the Open edX codebase, please report it by sending an email to security@edx.org. Please do not post the vulnerability to the public mailing lists.

Feedback

If you find a problem in the release candidate, please report them on the mailing list (openedx-ops for operations problem, edx-code for other problems), or even better, create issues in JIRA.  We are very interested to hear from the community about what you value in named releases. Please let us know what you would like to see in future named releases.  Discussion on the mailing list is always welcome, of course!