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.

Quick start
  Get VirtualBox  Get Vagrant Get the code and create your machine:  $ git clone https://gerrit.wikimedia.org/r/mediawiki/vagrant $ cd vagrant $ vagrant up  When Vagrant is done configuring your machine, browse to http://127.0.0.1:8080/ to find your MediaWiki instance. The admin password is  command-line tool provides several subcommands for controlling your virtual machine. You've already used one:, which turns on the virtual machine. Like most  subcommands, you need to run it from the MediaWiki-Vagrant directory or one of its children. When you first run it, Vagrant will fetch a system image and the requisite software for running MediaWiki. This takes around 10-15 minutes on a broadband connection, but it only needs to happen once. When you run  in the future, it'll simply boot up the machine.

starts an interactive login shell on the virtual machine. It'll log you in as the user ; root access is available to via , which is passwordless. Because the virtual machine is entirely sandboxed within your computer, it is configured for convenience, not security. As a rule, whenever you encounter a password prompt, the password is.

When you log in, you should see a colorful MediaWiki banner, and you may be prompted to update the version of VirtualBox Guest Additions. Updating will improve the performance and reliability of your machine, so go ahead and do it, by running.

The command  will start an interactive PHP interpreter with MediaWiki's codebase already loaded. You can type in some code, hit 'enter', and the code will be evaluated immediately. If you start a line with '=', its computed value will be pretty-printed.

The  folder corresponds to the MediaWiki-Vagrant folder on your host machine, and its contents is shared. MediaWiki's code is installed to. This allows you to use your normal editor environment on your host machine to edit the MediaWiki code that runs on your virtual machine.

Log out of your virtual machine by typing  or by hitting. Now that you're back in a standard command prompt, you can run  to shut down the virtual machine and   to bring it back up. will delete the virtual machine's files; this command is useful if you want to return your instance to a pristine state. (You'll need to follow up with  to provision a fresh instance.)

You can follow the logs Apache with this code :

MediaWiki configuration
As an alternative to managing all MediaWiki settings in a single, large LocalSettings.php file, consider grouping your configurations by component or theme, and creating a separate PHP file in  for each group. This makes it quite easy to keep your settings organized, to temporarily disable specific configurations, and to share settings with others. MediaWiki will automatically load any PHP files in  in lexical order. You can control the order in which your configurations are set by adopting the habit of adding a two-digit prefix to each file name.

For example:

 settings.d/   ├── 10-RunFirst.php ├── 20-SomeExtension.php └── 99-RunLast.php

Note that the settings files in  are automatically created and destroyed in response to your Puppet configuration. Don't put your custom settings there, because Puppet will erase or override them. Keep your custom settings files in  instead.

Advanced usage
MediaWiki-Vagrant uses Puppet to configure MediaWiki on the virtual machine. Puppet is a configuration management tool that works by providing a domain-specific language for expressing software configurations in a declarative fashion. Files containing Puppet code are called 'manifests'. When Puppet runs, it interprets the manifests you feed it and configures the machine accordingly. MediaWiki-Vagrant's Puppet code is located in the, which Puppet creates the first time it runs, lists the set of optional roles that ship with MediaWiki-Vagrant. These include:


 * Scribunto with LuaSandbox
 * ParserFunctions
 * VisualEditor (including a full Parsoid instance)
 * Selenium browser testing
 * User Metrics API
 * MobileFrontend
 * Remote debugging support via Xdebug
 * GettingStarted
 * GuidedTour
 * Echo
 * EventLogging

To enable a role, edit the file  in your vagrant directory on the host and uncomment the role you wish to enable (remove the leading # symbol, leave the -). Then run  to trigger a Puppet re-run.

To remove a role, run  and   to re-create a fresh virtual machine with the roles you need.

MediaWiki-Vagrant and your project
MediaWiki-Vagrant's Puppet codebase contains abstractions that make it easy to automate the configuration of MediaWiki extensions and related software. If you are a developer working on a software project that relates to MediaWiki, you are encouraged to submit a patch with a Puppet role for your project. Adding a Vagrant role for your project makes it easy for other developers to check out your work. Using a managed virtual machine as a development sandbox for your project reduces the chance of "works-on-my-machine" errors that often result from geographically remote developers working in incompatible environments.

The virtual machine provisioned by MediaWiki-Vagrant resembles Wikimedia's production environment in key respects, and it uses the same tool—Puppet—that Wikimedia's technical operations team uses to manage production servers and Wikimedia Labs instances. This can help you write software that will meet the technical requirements for deployment on Wikimedia's production cluster.

The easiest way to get started with custom roles is to look at how existing roles are implemented in. These roles depend on Puppet modules in. The Puppet code is generally well-documented and contains examples that demonstrate its proper usage.

Next steps
 /Installation details /Troubleshooting /Customizing</li> /Advance usage</li> </ul>

Links

 * Project page on Ohloh
 * MediaWiki-Vagrant on GitHub