MediaWiki-Vagrant



MediaWiki-Vagrant is a portable MediaWiki development environment. It consists of a set of configuration scripts for Vagrant and VirtualBox that automate the creation of a virtual machine that runs MediaWiki.

The virtual machine that MediaWiki-Vagrant creates makes it easy to learn about, modify, and improve MediaWiki's code: useful debugging information is displayed by default, and various developer tools are set up specifically for inspecting and interacting with MediaWiki code, including a powerful debugger and an interactive interpreter. Best of all, because the configuration is automated and contained in a virtual environment, mistakes are easy to undo.

Installation
Vagrant and VirtualBox are both prerequisite. Both are free and open-source and available on Mac, Windows, and GNU/Linux.

If you do not want your virtual machines stored under your user home directory, start VirtualBox and change it in the preferences. Moving existing virtual machines later is complicated. You may want to set the environment variable VAGRANT_HOME to the directory where you are going to keep your virtual boxes. If you don't, the Windows version will use drive C: for temporary stuff.
 * 1) Download and install VirtualBox.
 * 1) Download and install the latest version of Vagrant from vagrantup.com (v1.2.2 or higher).
 * 1) Download a copy of mediawiki-vagrant:
 * - Either -
 * Download one of the individual files:
 * tar.gz from GitHub
 * zip from GitHub
 * tar.gz from Gerrit
 * Extract the zip file or tarball to a directory of your choice.
 * Up a terminal or a command-prompt, and set your working directory to to the location of the extracted files.
 * - Or -
 * From a terminal or a command-prompt use Git:
 * Change your working directory to the git-cloned directory.
 * 1) From there, run  to provision and boot the virtual machine.

You'll now have to wait a bit, as Vagrant needs to retrieve the base image from Canonical, retrieve some additional packages, and install and configure each of them in turn. Our Vagrant configuration relies on Puppet to provision and configure software. See /Initial run/ for what an initial run should look like (the output you see may differ slightly).

Caution about download size
If your internet connection is slow or if you're doing this in a large group, you might want to change the source of the image file to something close by. Edit the file named  in your vagrant directory and change the config.vm.box_url variable to whatever URL is appropriate - a webserver on a local IP address with a copy of the file works particularly well.

Alternatively if you have the .box file you can do the following to make vagrant not download it again, due to the fact that a .box file is just a TAR file in disguise:

Windows

 * Go to the directory
 * Create the two nested directories
 * Extract the .box file to this new directory. The .box file is just a TAR file. If you don't have a tool to extract TAR files you can get a tar.exe here.
 * Create a text file with the line  and save it as

Usage
If it all worked, you should be able to browse to http://localhost:8080/ and see the main page of your MediaWiki instance.

To access a command shell on your virtual environment, run  from the root mediawiki-vagrant directory or any of its subdirectories. (Vagrant knows which instance you are referring to by searching for a file named 'Vagrantfile' in the current directory and its parent directories.)

From there, run  to interactively evaluate PHP code in a MediaWiki context, or   to get an authenticated SQL shell on your wiki's database.

The password for vagrant ssh and Admin user of the wiki is 'vagrant'.

/Customizing explains how to configure your vagrant box to do more.

Setting up access to gerrit
This is only a potentially incomplete gross sketch, needing review. Assuming: On a terminal or command shell go to the directory, where your vagrantfile is located, and type: You should get a shell on th virual machine. You should be prompted for your passphrase. enter it.
 * You have an account in gerrit.
 * Your public key is known to gerrit.
 * Your private key is stored in ~/.ssh/id_rsa in the virtual machine.
 * vagrant ssh
 * 
 * git remote add gerrit ssh://your-username@gerrit.wikimedia.org:29418/mediawiki/core.git
 * ssh-agent bash</tt>
 * ssh-add</tt>

MediaWiki debugging using Xdebug and an IDE in your host
The MediaWiki-Vagrant box loads Xdebug, a PHP extension for debugging and profiling. Here are the steps to use it:

Start and ssh to your MW-Vagrant box if you haven't done so already:

Look at the Xdebug configuration:

The following settings work pretty well (see Yurik's virtual box on Windows 7 article for more information):

zend_extension=/usr/lib/php5/20090626/xdebug.so xdebug.idekey=default xdebug.remote_autostart=1 xdebug.remote_connect_back=1 xdebug.remote_enable=1 xdebug.remote_handler=dbgp xdebug.remote_mode=req xdebug.remote_port=9000

Next, configure your IDE. The following explanation assumes you use PhpStorm.

In PhpStorm, go to File > Open Directory. Choose the mediawiki directory that is contained within your Mediawiki-Vagrant installation. If you are prompted to add files or about Git roots, just cancel those warnings unless you feel comfortable with those settings.

Now that you've created a PhpStorm project by adding the mediawiki directory, to see the basic debug settings, go to PhpStorm > Preferences > (under Project Settings) PHP > Debug. These defaults should work well with the xdebug.ini file above. But more configuration is necessary to make everything work.

Go to PhpStorm > Preferences > PHP (under Project Settings) > Servers. Click the plus (+) button to add a server. Set the Name field to something like vagrant local. Set the Host field to localhost, the Port field to 8080, and the leave the Debugger dropdwon at a value of Xdebug. Next, click the Use path mappings (select if the server is remote or symlinks are used) checkbox. On the lefthand side you will see your filesystem as expressed by the File/Directory header, and on the righthand side you can click to map the remote (virtual machine) absolute filesystem with your own (host) filesystem path. Here, you want to ensure that your own (host) filesystem path for the mediawiki directory is mapped to the remote (virtual machine) filesystem path of /vagrant/mediawiki for the Absolute path on the server. Now, click OK.

Next, in PhpStorm, go to Run > Edit Configurations. Click the plus (+) symbol to add a PHP Web Application debug configuration. In the Name field type a descriptive name such as ff and vagrant (e.g., if you're using Firefox). In the Server section, choose the vagrant local server configuration you just defined from the dropdown list. In the Start URL field type a relative path such as /wiki/Main_Page (or if you are a mobile developer and have enabled the MobileFrontend extension, /wiki/Main_Page?useformat=mobile). Choose whatever Browser you want to use from the dropdown list. Click OK.

Next, back in your SSH session on the virtual machine, restart Apache to make your xdebug.ini settings take effect:

You may get a warning that Apache bound itself to a port because it couldn't find additional configuration settings. Not a problem.

Now, back in PhpStorm, go to Run > Debug. When prompted. choose the PHP Web Application debug configuration you set earlier.

A browser should launch and the page should be rendered. Not that exciting!

Go back into PhpStorm, and open the file mediawiki/index.php. Add a breakpoint by clicking in the gutter at the lefthand side of the $mediawiki->run; method invocation. You should see a little red orb appear.

Now go to Run > Debug again, and choose the PHP Web Application debug configuration you set earlier. Notice how your Debugger window in PhpStorm paused execution of script and showed you some information about variables that have been set up to the point where you set the breakpoint. You can click the green Resume Program button at the lefthand side of the debugger window to let the script keep running. And if you set other breakpoints in other pieces of code within the project, script execution will pause again. You can also try using the blue Step Into button if you want to see the code execution play out call-by-call. This is a great way to learn how MediaWiki code actually works. Eventually, you'll start adding code to your own files or tweaking existing files and setting breakpoints to make sure variables are set the way you expected at actual runtime.

To learn more about PhpStorm debugging, visit the PhpStorm Debug help page.

LocalSettings.php
The settings directory, which is accessible from the base MediaWiki-Vagrant directory on your host, as well as /vagrant/settings/ within the virtual machine's file system, is the best place to add files for extending LocalSettings.php. Just add one file per logical LocalSettings.php enhancement.

Puppet failures
If Puppet fails to configure your machine,

This error may be caused by run-time failure to connect to Ubuntu package repositories or Gerrit. In such cases, you can simply trigger another Puppet run by running. If this doesn't work, you can try running  to trigger recreation of the virtual machine instance.

If your problem persists, please file a bug, and (if possible) attach a copy the output of the failed run.

Vagrant / VirtualBox failures
In general, Vagrant and VirtualBox get along quite well. Once in a blue moon, a VM crash in a way that causes Vagrant to lose the ability to manage the machine or inspect its status. If this should happen, you can usually fix things by running VirtualBox's management console and rebooting the machine there.

Some users may see an error:

VT-x features locked or unavailable in MSR. (VERR_VMX_MSR_LOCKED_OR_DISABLED). Result Code: NS_ERROR_FAILURE (0x80004005)

upon trying to bring up the MediaWiki VM.

Click settings, accept the recommended change, and discover that the VM image is 40G in size and a FAT filesystem only supports files up to 16G in size. VirtualBox suggests a filesystem such as ext3 with sufficient size for image files.

Connection failures
If you try to connect to http://localhost:8080 and you can't connect:
 * Is your Vagrant VM up and running?
 * Do you have any other proxies setup on port 8080?
 * Are there any other browser add-ons, plugins, or proxies wired up that could interfere with connections to localhost?
 * Do you have the Xdebug settings in place, but no tool to intercept the Xdebug connect back calls for PHP scripts?
 * Have you tried...
 * From within a  session,  ?
 * From your host a  and  ?
 * Stashing any file changes you've made in the code and running the pristine code?