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.2.x from http://www.virtualbox.org/
(Windows) After installing VirtualBox you need to set
Install vagrant >= 1.7 using the installer from vagrantup.com
Install Ansible 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
Fork the project. (See GitHub)
Clone your fork of Kuma and update submodules:
git clone email@example.com:<your_username>/kuma.git cd kuma git submodule update --init --recursive
Start the VM and install everything. (approx. 15 minutes on a fast net connection).:
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:
Finished catalog run in .... seconds
If the above process fails with an error, check Errors.
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
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.
Sign up/in with Persona
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 mysql -ukuma -pkuma kuma -e "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 the wiki
By default, the wiki is disabled with a :doc:`feature toggle <feature-toggles>`. 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.
#. As the admin user you just created, visit the waffle section of the admin site.
- Click "Add flag".
- Enter "kumaediting" for the Name.
- Set "Everyone" to "Yes"
- Click "Save".
You can now 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
(Advanced) Enable KumaScript
- Sign in as the admin user
- Visit the constance config admin panel
- Click "Save" at the bottom
KumaScript is now enabled. You will also need 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 get a .json file to load in your local django admin interface as described in `this bugzilla comment`_.
(Advanced) Enable GitHub Auth
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/
As the admin user, 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
Now you can sign in with GitHub at https://developer-local.allizom.org/
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 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:
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 :ref:`more help <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 manage.py migrate
If you get an error, please ask for :ref:`more help <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. On Windows NFS won't be used ever by the way.
If that doesn't help you can disable NFS by setting the
configration value in a
.env file. See the :ref:`Vagrant configuration
<vagrant-config>` options for more info.
If you have other problems during
vagrant up, please check