Get up and running quickly with edX services.

If you are seeking info on the Vagrant-based devstack, please see https://openedx.atlassian.net/wiki/display/OpenOPS/Running+Devstack. This project is meant to replace the traditional Vagrant-based devstack with a multi-container approach driven by Docker Compose. It is still in the alpha/beta testing phase. Support for this project is limited at the moment, so it may take a while to respond to issues.

You should run any Make targets described below on your local machine, not from within a VM.

All of the services can be run by following the steps below. Note that since we are running many containers, you should configure Docker with a sufficient amount of resources. Our testing found that configuring Docker for Mac with a minimum of 2 CPUs and 4GB of memory works well.

1. The Docker Compose file mounts a host volume for each service's executing code. The host directory is defaults to be a sibling of this directory. For example, if this repo is cloned to ~/workspace/devstack, host volumes will be expected in ~/workspace/course-discovery, ~/workspace/credentials, etc. These repos can be cloned with the command below.

   make dev.clone

   You may customize where the local repositories are found by setting the DEVSTACK_WORKSPACE environment variable.

2. Run the provision command, if you haven't already, to configure the various services with superusers (for development without the auth service) and tenants (for multi-tenancy).

   The username and password for the superusers are both "edx". You can access the services directly via Django admin at the /admin/ path, or login via single sign-on at /login/.

   Provision

   make dev.provision

3. Start the services. This command will mount the repositories under the DEVSTACK_WORKSPACE directory.

   Note: it may take up to 60 seconds for the LMS to start

   Start

   make dev.up

After the services have started, if you need shell access to one of the services, run make <service>-shell. For example to access the Catalog/Course Discovery Service, you can run:

make discovery-shell

To see logs from containers running in detached mode, you can either use "Kitematic" (available from the "Docker for Mac" menu), or by running the following:

make logs

To reset your environment and start provisioning from scratch, you can run:

make destroy

The provisioning script creates a Django superuser for every service.

Email: [email protected]
Username: edx
Password: edx

The LMS also includes demo accounts. The passwords for each of these accounts is edx.

Each service is accessible at localhost on a specific port. The table below provides links to the homepage of each service. Since some services are not meant to be user-facing, the "homepage" may be the API root.

Sometimes you may need to restart a particular application server. To do so, simply use the docker-compose restart command:

docker-compose restart <service>

<service> should be replaced with one of the following:

• credentials
• discovery
• lms
• studio

Docker Compose files useful for integrating with the edx.org marketing site are available. This will NOT be useful to those outside of edX. For details on getting things up and running, see https://openedx.atlassian.net/wiki/display/ENG/Marketing+Site.

We are still working on automated image builds, but generally try to push new images every 3-7 days. If you want to build the images on your own, the Dockerfiles are available in the edx/configuration repo.

NOTES

1. edxapp is the only service whose changes have been merged to the master branch.
2. edxapp uses the latest tag. All other services use the devstack tag.

git checkout master
git pull
docker build -f docker/build/edxapp/Dockerfile . -t edxops/edxapp:latest

git checkout clintonb/docker-devstack-idas
git pull
docker build -f docker/build/discovery/Dockerfile . -t edxops/discovery:devstack

The build commands above will use your local configuration, but pull application code from the master branch of the application's repository. If you would like to use code from another branch/tag/hash, modify the *_VERSION variable that lives in the ansible_overrides.yml file beside the Dockerfile.

For example, if you wanted to build tag release-2017-03-03 for the Course Discovery Service, you would modify DISCOVERY_VERSION (COMMON_GIT_PATH for use another remote) in docker/build/discovery/ansible_overrides.yml.

If you are having trouble with your containers there are a few steps you can take to try to resolve.

Make sure you have the latest code and Docker images. Run make pull in the devstack directory to pull the latest Docker images. We infrequently make changes to the Docker Compose configuration and provisioning scripts. Run git pull in the devstack directory to pull the latest configuration and scripts. The images are built from the master branches of the application repositories. Make sure you are using the latest code from the master branches, or have rebased your branches on master.

Sometimes containers end up in strange states and need to be rebuilt. Run make down to remove all containers and networks. This will NOT remove your data volumes.

If you want to completely start over, run make destroy. This will remove all containers, networks, AND data volumes.