Table of Contents

Installation via Vagrant

Since 2011, staff developers ran a model of the entire MDN stack in a Vagrant-managed virtual machine. This included backing services like a database, caching server, and search engine, as well as the application services like Django, KumaScript, and Celery.

Vagrant started out closely aligned with production, but over the years the Vagrant environment evolved to make development easier, and the production configuration was maintained by the operations team. For example, Vagrant switched the operating system from CentOS to Ubuntu, and the provisioning system from Puppet to Ansible. The Puppet scripts used to maintain the production infrastructure have evolved, and can not be published or reused for development due to configuration secrets. Both systems work, but it is less likely that the development environment can be used to reproduce production issues, or that the development environment can be used as a testbed for infrastructure changes.

Starting in 2011, Kuma is moving to Docker for development, testing, and deployment. Docker is now the primary development environment, and the Docker setup instructions should be used by new developers.

Until the transition is complete, we cover development with both the Docker and the Vagrant environments. We do not plan to keep feature parity between the environments, and will only fix critical errors in Vagrant provisioning.

There are common issues encountered when provisioning Vagrant, or maintaining a long-lived installation. See the Errors section for tips and tricks, as well as the Troubleshooting page.

Install and run everything

  1. Install VirtualBox >= 5.0.x from


    (Windows) After installing VirtualBox you need to set PATH=C:\\Program Files\\Oracle\\VirtualBox\\VBoxManage.exe;

  2. Install Vagrant >= 1.7 using the installer from

  3. Install Ansible >= 1.9.x on your machine so that Vagrant is able to set up the VM the way we need it.

    See the Ansible Installation docs for which way to use on your computer’s platform.

    The most common platforms:

    Mac OS X:

    brew install ansible

    or if you have a globally installed pip:

    sudo pip install ansible


    $ sudo apt-get install software-properties-common
    $ sudo apt-add-repository ppa:ansible/ansible
    $ sudo apt-get update
    $ sudo apt-get install ansible

    Fedora / RPM-based distribution:

    $ sudo dnf install ansible.noarch

    For previous versions based on yum, use:

    $ sudo yum install ansible.noarch


    Installation on Windows is complicated but we strive to make it easier in the future. Until then see this blog post for how to Run Vagrant with Ansible Provisioning on Windows.

  4. Fork the project. (See GitHub)

  5. Clone your fork of Kuma and update submodules:

    git clone<your_username>/kuma.git
    cd kuma
    git submodule update --init --recursive
  6. Start the VM and install everything. (approx. 15 minutes on a fast net connection):

    vagrant up


    VirtualBox creates VMs in your system drive. Kuma’s VM is approx. 2GB. If it won’t fit on your system drive, you will need to change that directory to another drive.

    At the end, you should see something like:

    PLAY RECAP ********************************************************************
    developer-local            : ok=147  changed=90   unreachable=0    failed=0
    ==> developer-local: Configuring cache buckets...

    If the above process fails with an error, check Errors.

  7. Log into the VM with ssh:

    vagrant ssh
  8. Use foreman inside the VM to start all site services:

    foreman start

    You should see output like:

    20:32:59 web.1        | started with pid 2244
    20:32:59 celery.1     | started with pid 2245
    20:32:59 kumascript.1 | started with pid 2246
  9. Visit and add an exception for the security certificate if prompted.

  10. Visit the homepage at

  11. You’ve installed Kuma!

    Continue reading to create an admin user and enable the wiki.

Create an admin user

You will want to make yourself an admin user to enable important site features.

  1. Sign up/in with Persona.

  2. After you sign in, SSH into the VM and make yourself an admin (exchange << YOUR_USERNAME >> with the username you used when signing up for Persona):

    vagrant ssh
    python ihavepower "<< YOUR_USERNAME >>"

    You should see:


Enable the wiki

By default, the wiki is disabled with a feature toggle. So, you need to create an admin user, sign in, and then use the Django admin site to enable the wiki so you can create pages.

  1. As the admin user you just created, visit the waffle section of the admin site.
  2. Click “Add flag”.
  3. Enter “kumaediting” for the Name.
  4. Set “Everyone” to “Yes”
  5. Click “Save”.

You can now visit to create new wiki pages as needed.

Many core MDN contributors create a personal User:<username> page as a testing sandbox.

(Advanced) Enable KumaScript

By default, KumaScript is also disabled with a feature toggle. To enable KumaScript:

  1. Sign in as the admin user.

  2. Visit the constance config admin panel.

  3. Change KUMASCRIPT_TIMEOUT to 600.

  4. Click “Save” at the bottom.

  5. Import the KumaScript auto-loaded modules:

    vagrant ssh
    python import_kumascript_modules


You must create a user to import kumascript modules.

(Advanced) Enable GitHub Auth

To enable GitHub authentication, register your own OAuth application on GitHub:

As the admin user, add a django-allauth social app for GitHub:

  • Provider: GitHub.
  • Name:
  • Client id: <your GitHub App Client ID>.
  • Secret key: <your GitHub App Client Secret>.
  • Sites: -> Chosen sites.

Now you can sign in with GitHub at

Errors during Installation

vagrant up starts the virtual machine. The first time you run vagrant up it also provisions the VM - i.e., it automatically installs and configures Kuma software in the VM. We provision the VM with Ansible roles in the provisioning directory.

Sometimes we put Ansible roles in the wrong order. Which means some errors can be fixed by simply provisioning the VM again:

vagrant provision

In some rare occasions you might need to run this multiple times. If you find an error that is fixed by running vagrant provision again, please email us the error at and we’ll see if we can fix it.

If you see the same error over and over, please ask for more help.

Django database migrations

If you see errors that have “Django database migrations” in their title try to manually run them in the VM to see more about them. To do so:

vagrant ssh
python migrate

If you get an error, please ask for more help.


On Ubuntu, vagrant up might fail after being unable to mount NFS shared folders. First, make sure you have the nfs-common and nfs-server packages installed and also note that you can’t export anything via NFS inside an encrypted volume or home dir. On Windows NFS won’t be used ever by the way.

If vagrant up works but you get the error IOError: [Errno 37] No locks available, that indicates that the host machine isn’t running rpc.statd or statd. This has been seen to affect Ubuntu >= 15.04 (running systemd). To enable it, run the following commands:

vagrant halt
sudo systemctl start rpc-statd.service
sudo systemctl enable rpc-statd.service
vagrant up

If that doesn’t help you can disable NFS by setting the VAGRANT_NFS configuration value in a .env file. See the Vagrant configuration options for more info.

If you have other problems during vagrant up, please check Troubleshooting.