Multiple isolated devstacks on the same host


You can have multiple isolated Devstacks provisioned on a single computer now. This was the result of a big PR, so let us know if bugs arise that seem to be related. If you are blocked by such a bug, check out the juniper.master branch of edx/devstack, which currently does not include this change.


The Change

Hi folks. @ztraboo and I recently collaborated on a change to allow having multiple Devstack instances provisioned on the same host computer. Each instance has an isolated set of databases. This could, for example, be used to quickly switch between versions of Open edX without hitting as many issues with migrations, data integrity, etc.

Unfortunately, this does not currently support running Devstacks simultaneously, because we hard-code host port numbers all over the place, and as far as I know, two running containers cannot share the same host port.

How to Use It

First, bring down any running containers:

make dev.down

Then, edit the file in the root of the edx/devstack repo, creating if it does not exist. Change the Devstack project name by adding the following line:


For example:


By default, COMPOSE_PROJECT_NAME is defined as devstack, which is what it has been set to so far.

Now, provisionion and run Devstack like you would normally:

make dev.provision  # Warning: takes 1hr+
make dev.up.<services>

Finally, you can switch between your Devstack projects by doing the following:

  1. Bring down containers.
  2. Edit the project name in
  3. Bring up containers.


Many of you may use the OPENEDX_RELEASE environment variable to specify the version of services that are checked out during Devstack provisioning.

If you set OPENEDX_RELEASE and do not specify COMPOSE_PROJECT_NAME, then your Devstack project name will be set as devstack-${OPENEDX_RELEASE}.

As a specific example, if OPENEDX_RELEASE is set in your environment as ironwood.master, then COMPOSE_PROJECT_NAME will default to devstack-ironwood.master instead of devstack.

The implication of this is that you can switch between isolated Devstack databases by changing the value of the OPENEDX_RELEASE environment variable.

Questions & troubleshooting

Are there official docs on this?

For now, these are the docs. Hopefully that will change in time.

This broke my existing Devstack!

Try posting on Discourse or Slack to see if you have the same issue as any others.

If you think you have found a bug, file a CR ticket. If the bug blocks you, you may want to check out the juniper.master version of Devstack, which currently does not include this change.

I’m getting errors related to ports already being used.

Make sure you bring down your devstack before changing the value of COMPOSE_PROJECT_NAME. If you forgot to, change the COMPOSE_PROJECT_NAME back to its original value, run make dev.down, and then try again.

I have custom scripts/compose files that integrate with or extend Devstack. Will those still work?

With the default value of COMPOSE_PROJECT_NAME = devstack, they should still work.

If you choose a different COMPOSE_PROJECT_NAME, your extensions will likely break, because the names of containers change along with the project name.


Additional notes when changing release can be found here.

edxenv bash alias to switch between releases.

direnv to handle environmental changes.


This is awesome! Great work, @ztraboo and @kmccormick!

@nedbat, is it not too late to merge this into the juniper.master devstack? This will make it a lot easier to test Juniper, for some of us.

Congrats on merging this! Please please please document this feature in the devstack’s README prior to making a PR on the juniper.master branch!

1 Like

I recommend using direnv over the edxenv bash script that I created above. It is easy to setup and use plus it can do more. I’ve created several files that I used in my setup here

After direnv is configured I ran these steps to make it work. Thanks to @arbrandes for recommending this directory environment application. Using zsh from Mac OS X Catalina but you may prefer bash command.

ztraboo-macbookpro:devstack.ironwood ztraboo$ zsh
direnv: loading ~/Dev/EducateWorkforce/Repos/open-edx/devstack.ironwood/.envrc                                                                                                                                                                                                                                                                                                         
(venv)ztraboo@ztraboo-macbookpro devstack.ironwood % which python
(venv)ztraboo@ztraboo-macbookpro devstack.ironwood % printenv

Once the environment is setup you can just go to the ./devstack directory and launch make dev.up and your release specific containers will launch.

(venv)ztraboo@ztraboo-macbookpro devstack.ironwood % cd devstack 
(venv)ztraboo@ztraboo-macbookpro devstack % make dev.up
bash -c 'docker-compose -f docker-compose.yml -f docker-compose-host.yml up -d'
Starting edx.devstack-ironwood.master.elasticsearch ... done
Starting edx.devstack-ironwood.master.mysql         ... done
Starting edx.devstack-ironwood.master.memcached     ... done
Starting edx.devstack-ironwood.master.mongo         ... done
Starting edx.devstack-ironwood.master.firefox       ... done
Starting edx.devstack-ironwood.master.devpi         ... done
Starting edx.devstack-ironwood.master.gradebook     ... done
Starting        ... done
Starting edx.devstack-ironwood.master.credentials   ... done
Starting edx.devstack-ironwood.master.ecommerce     ... done
Starting edx.devstack-ironwood.master.discovery     ... done
Starting         ... done
Starting edx.devstack-ironwood.master.lms           ... done
Starting        ... done
Starting edx.devstack-ironwood.master.edx_notes_api ... done
bash ./programs/ cache >/dev/null

Added documentation for both releases here.