This is the main edX platform which consists of LMS and Studio.
See code.edx.org for other parts of the edX code base.
The following instructions will help you to download and setup a virtual machine with a minimal amount of steps, using Vagrant. It is recommended for a first installation, as it will save you from many of the common pitfalls of the installation process.
- Make sure you have plenty of available disk space, >5GB
- Install Git: http://git-scm.com/downloads
- Install VirtualBox: https://www.virtualbox.org/wiki/Download_Old_Builds_4_2 (you need version 4.2.12, as later/earlier versions might not work well with Vagrant)
- Install Vagrant: http://www.vagrantup.com/ (Vagrant 1.2.2 or later)
- Open a terminal
- Download the project:
git clone git://github.com/edx/edx-platform.git - Enter the project directory:
cd edx-platform/ - (Windows only) Run the commands to deal with line endings and symlinks under Windows
- Start:
vagrant up
The last step might require your host machine's administrator password to setup NFS.
Afterwards, it will download an image, install all the dependencies and configure the VM. It will take a while, go grab a coffee.
Once completed, hopefully you should see a "Success!" message indicating that the installation went fine. (If not, refer to the troubleshooting section.)
Note: by default, the VM will get the IP 192.168.20.40. If you need to use a
different IP, you can edit the file Vagrantfile. If you have already started the
VM with vagrant up, see "Stopping and restarting the VM" below to take the change
into account.
Once the installation is finished, to log into the virtual machine:
$ vagrant ssh
Note: This won't work from Windows, install install PuTTY from http://www.chiark.greenend.org.uk/%7Esgtatham/putty/download.html instead. Then connect to 127.0.0.1, port 2222, using vagrant/vagrant as a user/password.
Once inside the VM, you can start Studio and LMS with the following commands
(from the /opt/edx/edx-platform folder):
Learning management system (LMS):
$ rake lms[cms.dev,0.0.0.0:8000]
Studio:
$ rake cms[dev,0.0.0.0:8001]
Once started, open the following URLs in your browser:
- Learning management system (LMS): http://192.168.20.40:8000/
- Studio (CMS): http://192.168.20.40:8001/
You can develop by editing the files directly in the edx-platform/ directory you
downloaded before, you don't need to connect to the VM to edit them (the VM uses
those files to run edX, mirroring the folder in /opt/edx/edx-platform).
You may also want to create a super-user with:
$ rake django-admin["createsuperuser"]
Also note that if you register a new user through the web interface, the activiation email will be posted to your VM's terminal window (search for lines similar to):
Subject: Your account for edX Studio
From: registration@edx.org
and find the activation URL for the account you've created.
See the Frequently Asked Questions for more usage tips.
To stop the VM (from your edx-platform/ directory):
$ vagrant halt
To restart:
$ vagrant up
or, to start without attempting to update the dependencies:
$ vagrant up --no-provision
If anything doesn't work as expected, see the troubleshooting section.
Note: The following installation instructions are for advanced users & developers who are familiar with setting up Python, Ruby & node.js virtual environments. Even if you know what you are doing, edX has a large code base with multiple dependencies, so you might still want to use the method described above the first time, as Vagrant helps avoiding issues due to the different environments.
There is a scripts/create-dev-env.sh that will attempt to set up a development
environment.
If you want to better understand what the script is doing, keep reading.
This code assumes that it is checked out in a directory that has three sibling
directories: data (used for XML course data), db (used to hold a
sqlite database), and log (used to hold logs). If you
clone the repository into a directory called edx inside of a directory
called dev, here's an example of how the directory hierarchy should look:
* dev
\
* data
* db
* log
* edx
\
README.md
You'll need to be sure that you have Python 2.7, Ruby 1.9.3, and NodeJS (latest stable) installed on your system. Some of these you can install using your system's package manager: homebrew for Mac, apt for Debian-based systems (including Ubuntu), rpm or yum for Red Hat based systems (including CentOS).
If your system's package manager gives you the wrong version of a language
runtime, then you'll need to use a versioning tool to install the correct version.
Usually, you'll need to do this for Ruby: you can use
rbenv or rvm, but
typically rbenv is simpler. For Python, you can use
pythonz,
and for Node, you can use nvm.
Often, different projects will have conflicting dependencies: for example, two projects depending on two different, incompatible versions of a library. Clearly, you can't have both versions installed and used on your machine simultaneously. Virtual environments were created to solve this problem: by installing libraries into an isolated environment, only projects that live inside the environment will be able to see and use those libraries. Got incompatible dependencies? Use different virtual environments, and your problem is solved.
Remember, each language has a different implementation. Python has
virtualenv, Ruby has
bundler, and Node's virtual environment support
is built into npm, its library management tool.
For each language, decide if you want to use a virtual environment, or if you
want to install all the language dependencies globally (and risk conflicts).
I suggest you start with installing things globally until and unless things
break; you can always switch over to a virtual environment later on.
The Python libraries we use are listed in requirements.txt. The Ruby libraries
we use are listed in Gemfile. The Node libraries we use are listed in
packages.json. Python has a library installer called
pip, Ruby has a library installer called
gem (or bundle if you're using a virtual
environment), and Node has a library installer called
npm.
Once you've got your languages and virtual environments set up, install
the libraries like so:
$ pip install -r requirements/edx/pre.txt
$ pip install -r requirements/edx/base.txt
$ pip install -r requirements/edx/post.txt
$ bundle install
$ npm install
You can also use rake to get all of the prerequisites (or to update)
them if they've changed
$ rake install_prereqs
You'll also need to install MongoDB, since our
application uses it in addition to sqlite. You can install it through your
system package manager, and I suggest that you configure it to start
automatically when you boot up your system, so that you never have to worry
about it again. For Mac, use
launchd
(running brew info mongodb will give you some commands you can copy-paste.)
For Linux, you can use upstart, chkconfig,
or any other process management tool.
We use rake to execute common tasks in our
project. The rake tasks are defined in the rakefile, or you can run rake -T
to view a summary.
Before you run your project, you need to create a sqlite database, create
tables in that database, run database migrations, and populate templates for
CMS templates. Fortunately, rake will do all of this for you! Just run:
$ rake django-admin[syncdb]
$ rake django-admin[migrate]
$ rake cms:update_templates
If you are running these commands using the zsh shell,
zsh will assume that you are doing
shell globbing, search for
a file in your directory named django-adminsyncdb or django-adminmigrate,
and fail. To fix this, just surround the argument with quotation marks, so that
you're running rake "django-admin[syncdb]".
edX has two components: Studio, the course authoring system; and the LMS (learning management system) used by students. These two systems communicate through the MongoDB database, which stores course information.
To run Studio, run:
$ rake cms
To run the LMS, run:
$ rake lms[cms.dev]
Studio runs on port 8001, while LMS runs on port 8000, so you can run both of
these commands simultaneously, using two different terminal windows. To view
Studio, visit 127.0.0.1:8001 in your web browser; to view the LMS, visit
127.0.0.1:8000.
There's also an older version of the LMS that saves its information in XML files
in the data directory, instead of in Mongo. To run this older version, run:
$ rake lms
The code in this repository is licensed under version 3 of the AGPL unless otherwise noted.
Please see LICENSE.txt for details.
High-level documentation of the code is located in the doc subdirectory. Start
with overview.md to get an introduction to the architecture of the system.
Contributions are very welcome. The easiest way is to fork this repo, and then make a pull request from your fork. The first time you make a pull request, you may be asked to sign a Contributor Agreement.
Please do not report security issues in public. Please email security@edx.org
You can discuss this code on the edx-code Google Group or in the
edx-code IRC channel on Freenode.