Kuma via Vagrant¶
Core developers run Kuma in a Vagrant-managed virtual machine so we can run the entire MDN stack. (Django, KumaScript, Search, Celery, etc.) If you’re on Mac OS X or Linux and looking for a quick way to get started, you should try these instructions.
If you have problems getting vagrant up, check Errors below.
Install and run everything¶
Install VirtualBox 4.x from http://www.virtualbox.org/
(Windows) After installing VirtualBox you need to set PATH=C:\Program Files\Oracle\VirtualBox\VBoxManage.exe;
Install vagrant >= 1.6 using the installer from vagrantup.com
Install the vagrant-vbguest plugin.
(OSX) If you have not previously run xCode and agreed to the terms of service you will have to do that first.
Clone your fork of Kuma and update submodules:
git clone firstname.lastname@example.org:<your_username>/kuma.git cd kuma git submodule update --init --recursive
vagrantconfig_local.yamlfile for your VM:
cp vagrantconfig_local.yaml-dist vagrantconfig_local.yaml
Start the VM and install everything. (approx. 30 min on a fast net connection).:
VirtualBox creates VMs in your system drive. Kuma’s VM is 3GB. 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:
=> default: notice: Finished catalog run in .... seconds
If the above process fails with an error, check Errors.
Add the hostnames to the end of your hosts file with this shell command:
echo '192.168.10.55 developer-local.allizom.org mdn-local.mozillademos.org' | sudo tee -a /etc/hosts
Log into the VM with ssh:
foremaninside the VM to start all site services:
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 20:32:59 stylus.1 | started with pid 2247 ...
Visit https://mdn-local.mozillademos.org and add an exception for the security certificate if prompted
Visit the homepage at https://developer-local.allizom.org
You’ve installed Kuma! If you want the badge ...
Create an admin user¶
You will want to make yourself an admin user to enable important site features.
Sign up/in with Persona
After you sign in, SSH into the vm and make yourself an admin:
vagrant ssh mysql -uroot kuma UPDATE auth_user set is_staff = 1, is_active=1, is_superuser = 1 WHERE username = 'YOUR_USERNAME';
You should see:
Query OK, 1 row affected (0.01 sec) Rows matched: 1 Changed: 1 Warnings: 0
Enable Important Site Features¶
You’ll need to use feature toggles to enable some basic features.
To enable GitHub authentication ...
- Application name: MDN (<username>)
- Homepage url: https://developer-local.allizom.org/docs/MDN/Contribute/Howto/Create_an_MDN_account
- Application description: My own GitHub app for MDN!
- Authorization callback URL: https://developer-local.allizom.org/users/github/login/callback/
Add a django-allauth social app for GitHub:
- Provider: GitHub
- Name: developer-local.allizom.org
- Client id: <your GitHub App Client ID>
- Secret key: <your GitHub App Client Secret>
- Sites: example.com -> Chosen sites
GitHub auth is also (temporarily) behind a waffle flag. So, add a waffle
github_login and set “Everyone” to “Yes”.
Now you can sign in with GitHub at https://developer-local.allizom.org
The central feature of MDN is wiki editing. We use a waffle flag called
kumaediting to control edits to the wiki. So we can effectively put the
site into “read-only” and/or “write-by-staff-only” modes.
To enable wiki editing on your MDN vm, add a waffle flag called
kumaediting and set “Everyone” to “Yes”.
To enable KumaScript (Kuma’s template system):
- Sign in
- Visit the constance config admin panel
- Click “Save” at the bottom
KumaScript is now enabled. You will also want to import the KumaScript auto-loaded modules. You can simply copy & paste them from the production site to your local site at the same slugs. Or you can email the email@example.com list to get a .json file to load in your local django admin interface as described in this comment.
You can visit https://developer-local.allizom.org/docs/new to create new wiki pages as needed.
Many core MDN contributors create a personal
User:<username> page as a testing sandbox.
Developing with Vagrant¶
Edit files as usual on your host machine; the current directory is
mounted via NFS at
/home/vagrant/src within the VM. Updates should be
reflected without any action on your part.
See development for tips not specific to vagrant.
Useful vagrant sub-commands:
vagrant ssh # Connect to the VM via ssh vagrant suspend # Sleep the VM, saving state vagrant halt # Shutdown the VM vagrant up # Boot up the VM vagrant destroy # Destroy the VM
Errors during vagrant up¶
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 on the vm. We
provision the vm with puppet manifests in the puppet/manifests directory.
Sometimes we put puppet declarations in the wrong order. Which means some errors can be fixed by simply provisioning the vm again:
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 firstname.lastname@example.org and we’ll see if we can fix it.
If you see the same error over and over, please ask for more help.
If you see errors like:
try to manually run database migrations in the vm. To do so:
vagrant ssh python manage.py migrate
If you get an error, please ask for more help.
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.
If that doesn’t help you can disable nfs by setting the nfs flag in the vagrantconfig_local.yaml file you just created.
Note: If you decide to run
nfs: false, the system will be a lot slower.
There is also the potential of running into weird issues with puppet,
since the current puppet configurations do not currently support
If you have other problems during
vagrant up, please check