MediaWiki-Vagrant

This page is a translated version of the page MediaWiki-Vagrant and the translation is 25% complete.

Outdated translations are marked like this.

布莱恩戴维斯（Bryan Davis）在维基媒体国际会议的采访中解释了MediaWiki Vagrant是什么

由Bryan Davis和Dan Duvall撰写的MediaWiki-Vagrant上的TechTalk

MediaWiki-Vagrant是一个轻便的MediaWiki开发环境。它包含了一系列Vagrant和VirtualBox 的配置脚本，目的是使运行MediaWiki虚拟机的创建自动化。由于配置是面向易于开发而不是安全，MediaWiki-Vagrant不建议公开访问维基。

用MediaWiki-Vagrant创建的虚拟机使得它易于学习，修改和完善MediaWiki的代码：有用的调试信息显示的是默认的，各种开发人员工具都是专门用来检查和与MediaWiki代码进行交互的，包括一个强大的调试器和交互式解释器。最重要的是，因为配置是自动化的，并且包含在虚拟环境中，所以出错的东西很容易恢复。

系统需求

CPU: 64位（x86）处理器
系统: Linux、macOS或者Windows
内存: 系统至少需要4GB的RAM，最好是8GB或更多，以便同时运行主机操作系统和虚拟机，不要尝试在只有2GB的RAM上运行，它最终会失败。
磁盘: 对于复杂的安装，至少需要10-12 GB的主驱动器空间（Linux上的/home分区，Windows上的C盘）。请特别注意：默认情况下，虚拟机磁盘镜像将储存在您的主目录下。
网络: 具有足够的带宽和活动的网络连接以下载Debian Linux更新和MediaWiki源代码。
时间: 20分钟至2小时，视情况而定，例如您遇到任何麻烦。

快速入门

（如果要从USB发行版安装MediaWiki-Vagrant，请按照README中的步骤而不是前五个步骤进行操作。）

获取Git
（仅限Linux）安装NFS（如果尚未安装）。
- 在Ubuntu中，使用sudo apt-get install nfs-kernel-server。
- Fedora通常安装NFS，如果没有运行sudo dnf install nfs-utils。
获取VirtualBox^[1]
获取最新版本Vagrant. Note that Vagrant v2.3.7 is the last version licensed under a free license.^[2]

Clone code into your current directory (don't clone into a folder in WSL)^[3]

$ git clone --recursive https://gerrit.wikimedia.org/r/mediawiki/vagrant

Enter vagrant directory to run vagrant commands in:
```
$ cd vagrant
```
Run setup script to setup vagrant before starting the machine:
Linux/macOS:
```
$ ./setup.sh
```
Windows:
```
$ .\setup.bat
```
出现提示时，输入Gerrit用户名（推荐），或按↵ Enter。

如果要使用发布分支而不是最新版本，可以使用vagrant hiera mediawiki::branch REL1_27立即指定它
Start the virtual machine:
```
$ vagrant up
```
Doing this for the first time might ask for your password as setting up directory sharing via NFS requires sysadmin rights. You can avoid that by setting the appropriate sudo permissions, as described here.

Pay attention to the console output to make sure that there are no errors. If you bump into errors, the #Troubleshooting startup section may be helpful.
当Vagrant完成配置您的计算机后，執行指令vagrant open或浏览到$url以查找您的MediaWiki实例。可以用用户Admin和密码vagrant登录。
启用额外的MediaWiki功能，例如:
To see a list of features (vagrant roles) you can enable, run:
```
$ vagrant roles list
```
To enable a feature, for example the VisualEditor , run:
```
$ vagrant roles enable visualeditor
```
To apply the roles you've enabled to your wiki, run:
```
$ vagrant provision
```

如果使用默认的VirtualBox提供程序且機器上的虚拟CPU数超过32，vagrant up将失败。使用vagrant config vagrant_cores <核心数量>来分配少于32个核心给虚拟机。

在第一个vagrant up完成之前可能需要一个小时或更长时间。

Windows Subsystem for Linux (WSL)

如果在Windows 10上使用与WSL Linux兼容的shell：使用vagrant.exe而不是vagrant运行命令。运行vagrant.exe config --required而不是./setup.bat，这在Linux bash shell中不起作用。

运行Vagrant的帐户可能需要“创建符号链接”权限（以管理员身份运行的简单方法）。

启动故障排除

如果您的问题在此没有回答，建议在IRC询问，频道位于#wikimedia-tech ^在线。

有时您可以通过运行vagrant destroy; vagrant up来修复损坏的安装（例如，“没有wiki被找到……”，这将重建虚拟机而不会重复耗费最多时间部分安装过程。

任何主机

您可以尝试安装Linux发行版提供的VirtualBox和Vagrant版本。如果你正在运行最近的Debian或Ubuntu，请尝试sudo apt-get install virtualbox vagrant来安装VirtualBox和Vagrant的软件包。

如果您从vagrant up收到错误，请安装最新版本的VirtualBox和Vagrant。

如果您遇到错误消息，如“无法打开文件$CLONED_REPOSITORY/trusty-cloud”，请尝试以下命令： vagrant up --provider=virtualbox
如果你有任何木偶错误你可能需要初始化木偶子模块，在vagrant目录运行git submodule update --init
- Error: Puppet::Parser::AST::Resource failed with error ArgumentError: Could not find declared class
使用http://127.0.0.1:8080/info.php检查Apache/PHP是否已启动并正在运行。

您可能希望将终端中vagrant up的初始运行输出与sample进行比较。初始设置可能需要很长时间，如果它似乎挂在某处但没有错误，只需给它一段时间。

如果您收到有关您的VirtualBox Guest Additions版本错误的警告，您可以尝试安装vagrant-vbguest插件，该插件会自动更新它们。

Vagrant很少丢失与您的VM配对。此主题讨论了解决它的一些方法（例如将旧的VM硬盘附加到新的配置文件）

确保vagrant/mediawiki存储库是最新的：

$ cd vagrant/mediawiki
$ git pull

确认你在BIOS启用了虚拟化技术。有时该设置在安全设置中。
确保您的语言编码设置为UTF-8。如果你得到“US-ASCII中的无效字节序列”，请尝试（重新）将LANG和LC_ALL环境变量设置为合适的值。例如：

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

如果您删除了任何旧VM，您将看到一条错误消息，如"...path contains non-directory or non-existent components..."，vagrant up将无法完成。如果您使用的是NFS（在非Windows主机操作系统上），您应该可以通过删除/etc/exports来解决此问题：输入sudo rm -i /etc/exports Vagrant将在您下次运行时重新创建/etc/exports文件

MediaWiki-Vagrant不会在不支持VT-X的主机上运行，因为它指定了64位客户机（虚拟机）。 MediaWiki-Vagrant需要在64位虚拟机上运行，部分原因是它使用维基媒体基金会生产中使用的deb软件包，这些软件包仅为amd64架构而构建。

Windows相关

如果您在Windows上并且“客户机器进入无效状态”-“关机”，请尝试下载4.3.15版本的VirtualBox（在Windows上存在4.3.14的已知问题）。如果这没有帮助，请确保在BIOS中启用硬件虚拟化技术（VT-x或AMD-V）。硬件虚拟化是必需的。它不是可选的性能增强（有些笔记本电脑需要你移除电源线和电池30秒[1]）。
VirtualBox不兼容于微软公司的Hyper-V。 如果你启用了Hyper-V，如果您已安装Visual Studio，则可能是默认值，尝试在VirtualBox中启动虚拟机时会遇到上述错误。有三种可能性：
- 在命令提示符下运行bcdedit / set hypervisorlaunchtype off关闭Hyper-V并重新启动。要重新启用Hyper-V，请将其设置为“自动”而不是“关闭”
- 通过“控制面板”中的“添加/删除Windows功能”禁用Hyper-V并重新启动。这将使VirtualBox正常工作，但会阻止您使用任何Hyper-V VM，例如Windows Phone模拟器。
- 或者，使用Hypeer-V进行Vagrant而不是VirtualBox。这可能不稳定。

Mac相关

NFS错误为避免NFS错误，安装时确保防火墙接受连接：Apple>系统偏好设置>安全和隐私>防火墙>防火墙选项。您需要取消选中“阻止所有传入连接”并可能还要检查“启用隐藏模式”以接受以下内容：netbiosd、nfsd、rpc.lockd、rpc.rquotad、rpcbind和VBoxHeadless。请注意，在一对vagrant up期间，您可能需要重新启动计算机并将状态更改为“允许传入连接”。安装后，您可以重新检查“阻止所有传入连接”和“启用隐藏模式”，因为防火墙规则已更新。

You will need to UNcheck "Block all incoming connections" and probably also UNcheck "Enable stealth mode" in order to accept the following: netbiosd, nfsd, rpc.lockd, rpc.rquotad, rpcbind, VBoxHeadless. Note, you may need to restart your computer and change the status to "Allow incoming connections" during a couple vagrant ups. After installation, you may be able to re-check "Block all incoming connections and "Enable stealth mode" now that the firewall rules have been updated.

- 或者你可以用 vagrant config nfs_shares off 关闭NFS共享。

Debian 和 Ubuntu

MediaWiki-Vagrant 使用 NFS 与主机 (你的电脑)共享某些文件夹。您需要设置计算机作为一台“NFS 服务器”。在Debian上，sudo apt-get install nfs-kernel-server将起作用，您可能还需要modprobe nfsv3。 请注意，如果没有/etc/exports中的条目，Debian的NFS服务器将无法启动。 如果sudo rpcinfo -p没有显示NFS服务正在运行，那么很可能会发生这种情况。将您的主目录添加为/etc/exports中的最后一行，然后/etc/init.d/nfs-kernel-server restart通常足以让您获得过了这个鸡蛋问题。

MediaWiki-Vagrant使用的NFS共享无法从加密目录运行，如果您在Ubuntu上运行并使用加密的主目录，则可能是这种情况。要运行MediaWiki-Vagrant，您可以：

- 在运行vagrant up之前，将MediaWiki-Vagrant目录移动到未加密的卷（例如/opt）

- 或者，您可以通过vagrant config nfs_shares off关闭NFS共享

NFS设置似乎有时会卡住（初始vagrant up挂起“挂载NFS共享文件夹”）。在主机上重新启动NFS守护程序会有所帮助（见#5802）。

Restarting the NFS daemon on the host helps. (See #5802.)

如果您收到端口转发错误，说明端口正在使用中，您可能需要打开虚拟机，完全删除虚拟机，然后重试。
vagrant up may tell you that "The executable 'bsdtar' Vagrant is trying to run was not found in the PATH variable." You can fix this on Ubuntu with sudo apt install libarchive-tools.
On Ubuntu with Secure Boot enabled, you will have a difficult time installing VirtualBox. Your machine may give you guff when you run /sbin/vboxconfig. If it does, you can rectify the situation by signing the associated kernel module. Step-by-step instructions can be found in this askubuntu post.

Fedora

如果网络10.11.12.13不可用运行vagrant up后，通过sudo setenforce 0禁用SELinux或修复SELinux设置。

如果你得到这个Vagrant管理的机器的提供商报告它还没有为SSH做好准备。运行vagrant roles enable mediawiki --provision之后，请确保显式设置提供程序，例如通过vagrant destroy后跟vagrant up --provider=virtualbox

如果你得到mount.nfs：mount到NFS服务器10.11.12.13：download-directory/vagrant'失败：RPC错误：无法接收，运行vagrant config nfs_shares

基本用法

在宿主机上的vagrant命令行工具提供了多种控制您虚拟机的子命令。您已经用过一个vagrant up，用于开启虚拟机。与其他子命令相同，您需要在MediaWiki-Vagrant目录或其子目录运行。您第一次运行时，Vagrant会获取一个系统镜像并安装运行MediaWiki的依赖项。这可能会花费1-2个小时，具体取决于CPU和宽带连接速率，但是这只需要进行一次。当您之后运行vagrant up，它会直接开启虚拟机。 You've already used one: vagrant up, which turns on the virtual machine. Like most vagrant 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 set up requisite software for running MediaWiki. This can take 1–2 hours of CPU and wall clock time on a broadband connection, but it only needs to happen once. When you run vagrant up in the future, it will simply boot up the machine.

vagrant ssh在虚拟机上启动一个交互的登录shell。它会使用vagrant用户为您登录；root权限可通过sudo获得，没有额外密码。因为此虚拟机在您电脑中是完全沙盒化的，为了便利性而配置，而非安全性。通常，您遇到需要密码的提示时，请输入vagrant。 It'll log you in as the user vagrant; root access is available to via sudo, 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 vagrant.

When you log in, you should see a colorful MediaWiki banner and a few reminders of useful commands.

The command phpsh 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. Type ? for quick help or help start for additional instructions.

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

更新

使用vagrant git-update可以使您的git存储库，外部库和数据库架构保持最新。此命令等同于运行 This command is equivalent to running

core中的git pull以及所有扩展和皮肤目录

composer update以确保最新的Composer托管库可用

最后运行update.php脚本。

您还应偶尔（或在需要新功能时）更新MediaWiki-Vagrant本身，vagrant git-update不包括在内。运行：

git pull

...在您的MediaWiki-Vagrant根目录中。这将在您运行时生效：

vagrant provision

您可以在您執行git pull後立即或稍後執行該指令。

警告： 如果您手动从git更新，您可能还需要运行composer update来下载MediaWiki所需的外部库。您可以运行checkComposerLockUpToDate.php脚本以查看是否需要composer update。

Some projects have NPM dependencies, often for development usage only, that are not installed by Composer. These may be approximately identified with find -not $ -name node_modules -prune $ -name package.json and manually installed as needed after an update by executing npm install in each directory wanted.

Log out of your virtual machine by typing logout or by pressing Ctrl+D. Now that you're back in a standard command prompt, you can run vagrant halt to shut down the virtual machine and vagrant up to bring it back up. vagrant destroy 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 vagrant up to provision a fresh instance.)

使用任务

MediaWiki-Vagrant sets up a basic MediaWiki instance by default, but it also knows how to configure a range of complementary software, including some popular MediaWiki extensions and their dependencies. These optional software stacks are collectively known as 'roles', and MediaWiki-Vagrant offers an easy and powerful command-line interface for managing them.

$ vagrant roles list # Display a list of available roles. $ vagrant roles enable role # Turn on role for this machine. $ vagrant roles disable role # Turn off role for this machine. $ vagrant provision # After you are done enabling and/or disabling roles, run this to make the change take effect.

Watch a short screencast demonstrating how to use roles. Roles has more information about some roles.

If you add many roles, you may need to increase memory available to the Vagrant VM. In particular, setting up the "browsertests" role involves compiling the ffi ruby Gem which is a memory-hungry task; if it fails try freeing some memory in the VM or increasing its memory allocation (bug 53864).

See the section Authoring roles below if you're interested in adding roles to MediaWiki-Vagrant.

Troubleshooting specific roles

中央认证

There are some roles that require special attention, centralauth role does not run db migrations automatically via puppet and requires running those by hand. If you get errors on provisioning this role try to run this script on the extension and see the errors it outputs:

mwscript extensions/CentralAuth/maintenance/migrateAccount.php --username 'Admin' --auto

Once you get a more concrete error you probably need to know what migration you need to run from the ones here:

extensions/CentralAuth/db_patches

维基数据

A simple vagrant roles enable wikidata && vagrant provision would fail. Here is a complete set of commands to make the Wikidata role up and running.

$ vagrant up
$ vagrant git-update
$ vagrant ssh
$ sudo apt-get update && sudo apt-get upgrade
$ composer selfupdate --update-keys
$ composer config --global process-timeout 9600
$ exit
$ vagrant roles enable wikidata
$ vagrant provision

Note that the first provision may complain, thus looking like a failure. However, if you run a second provision, you will see that everything goes fine.

You may then point your browser to http://wikidata.wiki.local.wmftest.net:8080/. To create a new wikidata item load http://wikidata.wiki.local.wmftest.net:8080/wiki/Special:NewItem and to create a new property navigate to http://wikidata.wiki.local.wmftest.net:8080/wiki/Special:NewProperty

How to import a Wikidata dump

The Vagrant command import-dump, which imports an XML file into MediaWiki, does not handle wikis other than the default one (see phab:T183274#3893785). You need to run the importDump.php script inside the Vagrant box.

Here is the procedure to import XML dumps.

$ mkdir wikidata_dumps
$ cd wikidata_dumps

download the pages-articles chunks. For instance:

$ wget https://dumps.wikimedia.org/wikidatawiki/latest/wikidatawiki-latest-pages-articles10.xml-p5264684p6341661.bz2

enable the import of Wikibase entities (see phab:T72898#1588002). Append the following line to your LocalSettings.php:

$wgWBRepoSettings[ 'allowEntityImport' ] = true;

the following BASH script can help you monitor the process. You can paste it in a import_wikidata.sh file. Note that the highlighted line calls the actual import script:

#!/usr/bin/env bash

chunks=$(find wikidata_dumps -type f)
for chunk in $chunks
do
    now=$(date)
    echo "$now: started import of $chunk" >> wd_import.log
    echo "-------------------------------------------" >> wd_import.log
    bzcat $chunk | mwscript importDump.php --wiki=wikidatawiki --uploads --debug --report 10000 2>>wd_import.log
    now=$(date)
    echo "-------------------------------------------" >> wd_import.log
    echo "$now: completed import of $chunk" >> wd_import.log
    echo "===========================================" >> wd_import.log
done

log into the Vagrant box and run the script. Debug messages should show up there:

$ vagrant ssh
$ cd /vagrant
$ sudo chmod +x import_wikidata.sh
$ ./import_wikidata.sh

you can follow the progress log from outside the Vagrant box:

$ tail -f wd_import.log

高级配置

Speeding up MediaWiki on Windows

MediaWiki out-of-the-box will likely run slow (page loads take 5+ seconds). This is because the virtual machine uses a shared file system that retrieves the files very slowly. Enabling NFS on Windows by installing the Vagrant WinNFSd plugin with vagrant plugin install vagrant-winnfsd, enabling NFS shares with vagrant config nfs_shares true, and restarting the machine with vagrant reload should significantly speed up page load times. You should make sure that the plugin is installed every time you run the machine as well.^[4] You can further speed it up by enabling nfs_cache, however, be warned that your wiki may run into weird errors because some files may not be updated completely when using the cache.

You can also speed up Mediawiki by using smb_shares. Make sure not to enable it at the same time as nfs_shares. Enable it with vagrant config smb_shares yes and run vagrant reload in an shell run as an administrator. If you don't run it as an administrator, you will be warned with an error when vagrant goes up and when you go to the wiki address, you will see a Wiki not found. When prompted, type in the username of your account (the name of your home user directory) and password (your Microsoft account password if your account is not a local account with a normal password).

本地MediaWiki核心拷贝

Sometimes you may want to start over from scratch by removing the entire vagrant directory or cleaning out the vagrant/mediawiki directory. In order to speed up the vagrant provisioning process, you may want to consider keeping a local, updated clone of the MediaWiki core that you copy into vagrant/mediawiki.

for example, assuming you are cloning MediaWiki repos into ~/projects/mediawiki/:

# clone and store a clean copy of MediaWiki core in ~/projects/mediawiki/core
cd ~/projects/mediawiki/
git clone ssh://<your-gerrit-username>@gerrit.wikimedia.org:29418/mediawiki/core

# clone a clean copy of vagrant in ~/projects/mediawiki/vagrant
cd ~/projects/mediawiki
git clone ssh://<your-gerrit-username>@gerrit.wikimedia.org:29418/mediawiki/vagrant

# create the mediawiki subdirectory if it doesn't exist
cd ~/projects/mediawiki/vagrant
mkdir ~/projects/mediawiki/vagrant/mediawiki

# copy the clean MediaWiki core to the clean vagrant/mediawiki directory
cp -r ~/projects/mediawiki/core/ ~/projects/mediawiki/vagrant/mediawiki

Update cloned repos

Update the cloned repos as often as possible/necessary.

cd ~/projects/mediawiki/core
git pull

cd ~/projects/mediawiki/vagrant
git pull
git submodule update --init --recursive

Or to update all cloned repos:

vagrant git-update

Vagrant reload

If you change configuration (e.g. vagrant_ram, your VM/MediaWiki website freezes, or you experience a problem, vagrant reload may resolve it. This will restart your guest. Some roles also require reloading, which should happen automatically.

When to enable roles

Enable roles only once you've successfully run your first vagrant up.

Note that vagrant destroy will not reset the enabled roles. Be sure to disable all roles after running vagrant destroy, then run vagrant up. Then you can re-enable any roles and run vagrant provision.

Vagrant behind proxy

If you are behind a proxy, Vagrant might throw some errors. 您可以安装vagrant-proxyconf。 It’s a plugin that allows your virtual machine to use specified proxies. This is a quick set up guide. For a detailed documentation you may check here.

安装插件：

vagrant plugin install vagrant-proxyconf

To configure proxy settings for all pieces of software on all vagrant VMs, add the following lines to your $VAGRANT_HOME/Vagrantfile (default ~/.vagrant.d/Vagrantfile).

Vagrant.configure("2") do |config|
  if Vagrant.has_plugin?("vagrant-proxyconf")
    config.proxy.http     = "http://192.168.0.2:3128/"
    config.proxy.https    = "http://192.168.0.2:3128/"
    config.proxy.no_proxy = "localhost,127.0.0.1,.example.com"
  end
  # ... other stuff
end

Replace the addresses with the IP and port number of your proxy server. Use the config.proxy.no_proxy option to list out all the sites/domains for which you might want to bypass proxy. For example,

config.proxy.no_proxy = "localhost,127.0.0.1,.example.com,.someinternaldomain.com"

Now when you run a vagrant up, there shouldn’t be any warnings.

To disable the plugin, set config.proxy.enabled to false or empty string (""). You can also disable it for specific applications. For example,

config.proxy.enabled         # → all applications enabled(default)
config.proxy.enabled = true  # → all applications enabled
config.proxy.enabled = { svn: false, docker: false }
                             # → specific applications disabled
config.proxy.enabled = ""    # → all applications disabled
config.proxy.enabled = false # → all applications disabled

MediaWiki-Vagrant prep

You may want to consider using a shell script such as mw-vagrant-prep to prepare a directory for a MediaWiki-Vagrant install.

调试

Vagrant

You can debug MediaWiki-Vagrant itself (e.g. the errors that happen during vagrant up) with VAGRANT_LOG:

VAGRANT_LOG=debug vagrant up

准备

You can debug the provisioning process by running

PUPPET_DEBUG=1 vagrant provision

PHP

You can debug PHP with Xdebug. Debugging in PHP is different from other client-side debugging. Your IDE listens for incoming connections, and when you access the server with a browser, a special header instructs PHP to connect to your IDE. For lack of better documentation, see the (old and overly verbose) MediaWiki-Vagrant/Advanced usage#MediaWiki debugging using Xdebug and an IDE in your host for further information.

Chrome

For Chrome users, you should get XDebug Helper, and optionally Clear Cache, HTTP headers, and Mod Headers.

Configure clear cache to automatically reload after clearing, and set up keyboard shortcuts (e.g. Ctrl+R for clear&reload, Ctrl+⇧ Shift+D to switch XDebugger on/off)

Firefox

Firefox users should check out easy Xdebug.

Install and configure an xdebug-compatible IDE on your machine (Eclipse, PhpStorm, Emacs, etc.)

In IDE, start listening for the incoming debug connection

In IDE, set break point at the spot that interests you

Enable XDebug in the browser and navigate to your vagrant installation ( http://127.0.0.1:8080/... )

CLI

For maintenance scripts and other code executed from CLI, you can use the xdebug_on and xdebug_off shell commands to enable/disable debugging.

日志文件

The MediaWiki logs can be found in /vagrant/logs. There are log files for Apache in /var/log/apache2/, but it seems they are not written to. The MySQL query log can be obtained by issuing SET GLOBAL general_log = 'ON'; in a client and then looking at /var/lib/mysql/*.log.

运行并调试测试单元

To run the PHPUnit tests for ALL extensions:

$ vagrant ssh
$ sudo -u www-data env PHPUNIT_WIKI=wiki PHPUNIT_LOGS=0 composer --working-dir=/vagrant/mediawiki phpunit

To run unit tests for a single extension:

$ sudo -u www-data env PHPUNIT_WIKI=wiki PHPUNIT_LOGS=0 composer --working-dir=/vagrant/mediawiki composer phpunit /vagrant/mediawiki/extensions/ExtensionName/tests/phpunit/

Some tests may require running as the proper user to create lock files and such, hence this command runs as the "user" www-data that handles web requests.

For building coverage reports, see Manual:PHP unit testing/Code coverage#MediaWiki-Vagrant.

Debugging phpunit tests is a little more complex. This method is a bit hacky, but can be used until debugging remote interpreter improves (e.g. in phpStorm 8 EAP). This workaround lets you run MediaWiki unit tests from the browser.

Download phpunit.phar file to the root of your vagrant directory.

Create a php file unittest.php in the root of the mediawiki directory.

Do not commit this file to the repository. Paste the following code into it:

unittest.php

<html><body><pre>
<?php
error_reporting(E_ALL);
ini_set('display_errors', 1);
require_once 'includes/WebStart.php';
$_SERVER[ 'argv' ] = array(
	'--configuration', '/vagrant/mediawiki/tests/phpunit/suite.xml',
	'/vagrant/mediawiki/extensions/JsonConfig/tests/phpunit/JCObjContentTest.php',
);
require_once '/vagrant/mediawiki/tests/TestsAutoLoader.php';
require_once '/vagrant/phpunit.phar';
PHPUnit_TextUI_Command::main(false);

在上面的文件中将参数argv更改为测试文件的名称

Apache maps the root of the MediaWiki directory to /w.

So navigate to http://127.0.0.1:8080/w/unittest.php to run this file

Follow #Debugging instructions to attach your debugger

运行浏览器测试

对于 JavaScript 单元测试 (QUnit)，请参阅 Manual:JavaScript unit testing 。

For browser end-to-end tests (Selenium), see Quality Assurance/Browser testing/Running tests#Running VisualEditor browser tests via Vagrant

推送更改

If you're using MediaWiki-Vagrant for development you'll probably want to push some commits to MediaWiki core or an extension's repository using git review. By default, all remotes point to the https:// URLs. To avoid overriding this on a case by case basis, run:

$ git config --global url."ssh://<username>@gerrit.wikimedia.org:29418/".insteadOf "https://gerrit.wikimedia.org/r/"

You also need to have your ssh keys in ~/.ssh.

Gerrit

To submit changes, use cd to navigate to your extensions folder. Then follow the instructions on submitting a patch via gerrit.

Troubleshooting

检查PHP版本和设置: http://127.0.0.1:8080/info.php

Edit LocalSettings.php?: First, check that there is no role (vagrant list-roles) that already does what you need.

If not, create a file in settings.d/ directory. See README and 00-debug.php-example file.

Update MediaWiki code?: The easiest is to use vagrant git-update from the host.

Or, to just update the code without dependencies, you can use regular git fetch, pull, etc. commands in vagrant/mediawiki and vagrant/mediawiki/extensions/SomeExtension directories. You can run these commands on the virtual machine, but the file access will be faster on the host machine. MediaWiki-Vagrant pulls code from git master when you initially set up and/or add a role, but doesn't automatically update code after that.

Run MediaWiki PHP interpreter: ssh to vagrant and run mwscript eval.php.

You might need to run it with sudo

Run MediaWiki SQL interpreter: ssh to vagrant and run mwscript sql.php.

You might need to run it with sudo

Update virtual machine software packages?: vagrant provision does not update system packages in the VM.

When you connect with vagrant ssh the login message will inform that you:
NN packages can be updated.
NN updates are security updates.
In vagrant ssh:

to update all packages, enter sudo apt-get update && sudo apt-get upgrade

for "automatic installation of security (and other) upgrades", similar to Cloud VPS instances, enter sudo unattended-upgrade

to update to the same packages that are on production WMF servers... TODO

Customize Vagrant: You should never need to change Vagrantfile directly.

There are several aspects of vagrant you can customize:

Core settings (git user, ports, ram, ip, port forwarding) can be customized via .settings.yaml file.

See vagrant config --help and vagrant forward-port --help for instructions. So for example you may run vagrant forward-port 1234 80 to enable port forwarding from host:1234 to guest:80.

Perform additional steps after Vagrantfile load by creating a file called Vagrantfile-extra.rb and placing it in the same folder as Vagrantfile - it will be automatically loaded.

In case of conflict, values in the 'extra' file will supersede values in this file. See example in support/ directory.

添加自定义Puppet代码？

This is ideal if you want to work on your own MediaWiki site locally and let the MediaWiki-Vagrant install your dependencies for you.

It's ideal if you have your own fork. There is a distinction between a role and this use case. Roles are meant to be installed in any order and without breaking. If your fork needs different calls and get in trouble with roles, create your own class and call what you need, including roles.

To do so, place your custom puppet code in puppet/modules/local/manifests/myown.pp with your own class, like so:

class local::myown {
    include ::role::svg
}

To apply your class, add it to the "classes" key in puppet/hieradata/local.yaml. You can create the file if it doesn't exist.

classes:
  - local::myown

Then run vagrant provision to apply the change via Puppet.

Update MediaWiki-Vagrant itself?: (For example, to use new roles.) In a terminal, change to the vagrant directory on the host computer and enter a regular git command such as git pull --ff-only.

You will typically want to run vagrant provision after updating to apply any new puppet changes to your virtual machine.

Run GUI applications on the virtual machine?: If you have an X server installed, SSH into the virtual machine using ssh -- -X to enable X forwarding.

(Mac users should update to the latest version of XQuartz.)

As an alternative, you can run the virtual machine in GUI mode, which allows you to interact with the VM as though it had a physical display.

To enable GUI mode, create a file called Vagrantfile-extra.rb in the root repository folder, with this as its content:

Vagrant.configure('2') do |config|
    config.vm.provider :virtualbox do |vb|
        vb.gui = true
    end
end

Save the file and run vagrant halt followed by vagrant up.

The virtual machine's display will appear in a window on your desktop.

Adjust the resources allocated to the VM?: If you'd like to allocate more or less CPU / RAM to the VM, see vagrant config --help for instructions.

Alternatively, you can do it by creating Vagrantfile-extra.rb (see support/ dir for an example):

Vagrant.configure('2') do |config|
    config.vm.provider :virtualbox do |vb|
        # See http://www.virtualbox.org/manual/ch08.html for additional options.
        vb.customize ['modifyvm', :id, '--memory', '768']
        vb.customize ['modifyvm', :id, '--cpus', '2']
    end
end

Change the editor used for git commit messages?

git config --global core.editor "vim"

Setup a custom hostname?

Go to Horizon, choose Web Proxies, and enter a DNS hostname, say <hostname>

View your new wiki at "http://<hostname>/wiki/"

Make the custom hostname point to homepage of my vagrant role instead of wiki homepage?

Create a local.yaml file in the /vagrant/puppet/hieradata directory. In it, add:

<rolename>::vhost_name:<hostname>
role::mediawiki::hostname: localhost

运行vagrant provision。

Run a branch of MediaWiki other than master?: Set the mediawiki::branch key in puppet/hieradata/local.yaml.

You can create the file if it doesn't exist.

mediawiki::branch: "wmf/1.24/wmf18"

This change has to be made BEFORE running vagrant up for the first time. If you decide you want to do it later, make the change, destroy your current VM with vagrant destroy -f, delete your existing mediawiki checkout and finally build a new VM with vagrant up.

Vagrant is designed to run with the master branch, and may not work perfectly, or at all with older versions of core and/or extensions^[5].

For the MediaWiki 1.35 release branch, it requires some modification to adjust PHP version requirements that are currently not met. See Topic:W05qhsn58ztktod8 for instructions.

高级用法

MediaWiki设置

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 settings.d/ 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 settings.d/ 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.

例如：

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

Note that the settings files in settings.d/puppet-managed 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 settings.d/ instead.

Vagrant flags

vagrant config --list display a list of all current Vagrant flags.

After the initial ./setup.sh, in your vagrant directory, you can then set one of the vagrant flags that appears in the config list, e.g. vagrant config nfs_shares no

Job queue

If you're testing something that needs to churn the job queue, you may need to increase the number of job runners. Currently this is not available through LocalSettings.php, but must be set in the config file for the job runner.

Open puppet/modules/mediawiki/templates/jobrunner.json.erb

Change the value for the runners key from 1 to the desired value (say, 4)

Re-provision with vagrant --provision

Beware this will be a difference from the git master in your code

See instructions above for adjusting CPU core count appropriately (highly recommended for CPU-bound task such as video transcoding).

Additional storage space

By default, there is relatively little free space on the root partition within the VM. If you plan to test uploading and processing of large image and video files, this may be insufficient.

Manual steps:

Shut down the VM (vagrant halt)

Open VirtualBox Manager

Select the VM and go into Settings

- Under Storage, select "Controller: SATA" and click the "Add hard disk" icon.

- Select the default disk image type.

- Name the disk 'VagrantImageSpace' or similar, and give it enough space (say, 80GB) -- by default the file will start small and expand to actual usage, so give as much space as you might need

- Close out the dialogs and restart the VM (vagrant up)

Run vagrant ssh to get a shell inside the terminal

- Run sudo fdisk /dev/sdb to set up new partitions...

- Type n, p, 1, and hit (enter) twice for default size

- Type w to save the partition table

Run sudo mke2fs /dev/sdb1 to create the filesystem

Run sudo vi /etc/fstab to edit the mounts list

- Add line at end: /dev/sdb1 /srv/images ext4 errors=remount-ro 0 2

- save out

Run sudo mount /srv/images to mount the filesystem

Run sudo chown www-data:www-data /srv/images to set the file permissions

Exit the shell exit

Reboot the VM (vagrant halt; vagrant up)

程序编写任务

The virtual machine created 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 Cloud VPS instances. Puppet is a configuration management tool that provides 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. A Vagrant role is a set of Puppet manifests.

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 easiest way to get started with custom roles is to look at how existing roles are implemented in puppet/modules/role/manifests/*.pp. These roles depend on Puppet modules in puppet/modules (usually, foo::bar { ... } translates to a call to puppet/modules/foo/manifests/bar.pp) and use files and templates from the other puppet/modules/role/*/rolename/ directories. The Puppet code is generally well-documented and contains examples that demonstrate its proper usage.

Some of the more useful puppet modules are:

mediawiki::extension - install and configure an extension (example)
mediawiki::import::text - create a documentation or test page on the wiki (example: declaration, page)
mediawiki::import::dump - import a wiki dump (example)
require_package - install a system package (example)
exec - execute a shell command (example)

在云VPS上设置实例

You can use MediaWiki-Vagrant in Cloud VPS to install MediaWiki on a Wikimedia Cloud VPS instance and enable MediaWiki-Vagrant roles in it.

错误

If you spot a bug in MediaWiki-Vagrant, please report it. First, make sure the bug is not a known Vagrant or VirtualBox bug by searching the Vagrant issue tracker on GitHub and the VirtualBox bugtracker. If it is not, go ahead and submit a bug report to Wikimedia Phabricator. Clearly describe the issue and include steps to reproduce, whenever possible.

链接

Project page on Ohloh

MediaWiki-Vagrant on GitHub

Issue tracker on Phabricator
Watch 2014-11-25 Tech talk on "What is New With MediaWiki Vagrant".
Bash commands needed for quick start on Ubuntu
OS upgrade

注释

↑ 如果您使用Fedora，请不要遵循Oracle的指示。相反，启用RPMfusion存储库（例如通过Apper的配置），然后运行sudo dnf install VirtualBox VirtualBox-kmodsrc akmod-VirtualBox kmod-VirtualBox（注意：区分大小写，有时版本敏感！如果找不到包，请在Apper中搜索）。或者你也可以按照这个指导做。您可能会收到有关内核过时的错误消息。如果这样做，请安装akmods-VirtualBox，然后运行sudo akmods以确保模块构建。
↑ On Fedora, you can run sudo dnf install vagrant.
↑ https://github.com/hashicorp/vagrant/issues/10576#issuecomment-452793401
↑ https://peshmerge.io/how-to-speed-up-vagrant-on-windows-10-using-nfs/
↑ Vagrant dependent on MediaWiki 1.21+

[fedora-1] 如果您使用Fedora，请不要遵循Oracle的指示。相反，启用RPMfusion存储库（例如通过Apper的配置），然后运行sudo dnf install VirtualBox VirtualBox-kmodsrc akmod-VirtualBox kmod-VirtualBox（注意：区分大小写，有时版本敏感！如果找不到包，请在Apper中搜索）。或者你也可以按照这个指导做。您可能会收到有关内核过时的错误消息。如果这样做，请安装akmods-VirtualBox，然后运行sudo akmods以确保模块构建。

[2] On Fedora, you can run sudo dnf install vagrant.

[3] ttps://github.com/hashicorp/vagrant/issues/10576#issuecomment-452793401

[4] ttps://peshmerge.io/how-to-speed-up-vagrant-on-windows-10-using-nfs/

[5] Vagrant dependent on MediaWiki 1.21+

[1]

[2]

[3]

[4]

[5]