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.
At the end, you'll earn the badge:
Note
If you have problems using vagrant, check Troubleshooting below
Install VirtualBox 4.x from http://www.virtualbox.org/
Note
(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.
- Fork the project. (See GitHub and Webdev Bootcamp)
Clone your fork of Kuma and update submodules:
git clone git@github.com:<your_username>/kuma.git cd kuma git submodule update --init --recursive
Copy a
vagrantconfig_local.yaml
file 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).:
vagrant up
Note
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 Troubleshooting.
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:
vagrant ssh
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 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, send a screenshot of your browser to luke dot crouch at gmail dot com.
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
Some site features are controlled using django-waffle. You control these features in the waffle admin.
Some site features are controlled using constance. You control these features in the constance config admin panel.
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
- Change
KUMASCRIPT_TIMEOUT
to 600 - Click "Save" at the bottom
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.
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 <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
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:
vagrant provision
In some rare occasions you might need to run this multiple times. If you see the same error over and over, 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.
If that doesn't help you can disable nfs by setting the nfs flag in the vagrantconfig_local.yaml file you just created.
nfs: false
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 nfs: false
.
If you have other problems during vagrant up
, please ask for more help.
- You should occasionally re-run the Puppet setup, especially after updating code with major changes. This will ensure that the VM environment stays up to date with configuration changes and installation of additional services.
On the Host:
vagrant provision
Inside the VM:
sudo puppet apply /home/vagrant/src/puppet/manifests/dev-vagrant.pp
If you have more problems using vagrant, please:
- Paste errors to pastebin
- email dev-mdn@lists.mozilla.org.
- After you email dev-mdn, you can also ask in IRC