Jump to content

MediaWiki-Vagrant

課題管理システム: #MediaWiki-Vagrant
From mediawiki.org
This page is a translated version of the page MediaWiki-Vagrant and the translation is 65% complete.
Languages:
Vagrant の視覚的な概要
Vagrant の視覚的な概要
MediaWiki Vagrant のロゴ
MediaWiki Vagrant のロゴ
ウィキマニアのインタビューで 使われたMediaWiki Vagrant の概念図（Bryan Davis）
TechTalkでMediaWiki-Vagrantを解説するBryan DavisとDan Duvall
TechTalkで使用したMediaWiki-Vagrantの解説スライドより（作成：Bryan Davis、Dan Duvall）

MediaWiki-Vagrant (訳注: 略称 MW-V) は、ポータブルな MediaWiki 開発環境です。MediaWiki が動作する仮想マシンの作成を自動化するVirtualBoxとVagrant（ベイグラント）の一連の設定スクリプトで構成されています。 設定はセキュリティよりも開発しやすさに重点を置いており、MediaWiki-Vagrantは公開のウィキ群での使用が非推奨です。

MediaWiki-Vagrant が作成する仮想マシンは、MediaWiki のコードの学習、変更、改善を簡単にします: 便利なデバッグ情報が既定で表示され、MediaWiki コードの検証や操作に特化したさまざまな開発者向けツールが設定されていて、強力なデバッガーや対話的なインタープリターが含まれています。 なによりもまず、設定が仮想環境上に自動化され組み込まれているため、ミスを犯しても簡単に元の状態に戻せます。

システム要件

CPU
64-bit x86 プロセッサー
OS
Linux、macOS、Windows
メモリ
合計 4 GiB RAM 以上をシステムに搭載、ホストの OS と VM を同時に走らせるには理想的には 8 GiB 以上。2 GiB RAM しか積んでいない場合は障害を避けるため駆動しないこと。
ディスク
プライマリ ドライブに数 GB を開放 (Linux は /home パーティション、Windows は C: ドライブ)。VM ディスク イメージが既定でホーム ディレクトリに保存されることに留意。
ネットワーク
Debian Linux 更新版と MediaWiki ソース コードのダウンロードができる帯域の有効なネットワーク接続
セットアップ所要時間
20分から2時間。条件およびトラブル発生の有無によって変化する。

クイックスタート

(USB ディストリビューションから MediaWiki-Vagrant をインストールしている場合は、最初の5つの手順ではなく README に従ってください。)

  1. Git を入手します
  2. (Linux のみ) NFS がインストールされていない場合はインストールしてください。
    • Ubuntu では sudo apt-get install nfs-kernel-server を使用してください。
    • Fedora には通常 NFS がインストールされていますが、インストールされていない場合は sudo dnf install nfs-utils を実行してください。
  3. VirtualBox を取得します[1]
  4. Vagrant を入手します. Note that Vagrant v2.3.7 is the last version licensed under a free license.[2]
  5. コードをカレント ディレクトリにクローンします (WSL 内のフォルダーにはクローンしないこと)[3] 
    $ git clone --recursive https://gerrit.wikimedia.org/r/mediawiki/vagrant
  6. vagrant のコマンド群を実行するため、vagrant ディレクトリに入ります: 
    $ cd vagrant
  7. マシンを開始する前に、vagrant をセットアップするためにセットアップ スクリプトを実行します:
    Linux/macOS:
    $ ./setup.sh
    Windows:
    $ .\setup.bat
    プロンプトが表示されたら、Gerrit ユーザー名を入力する (推奨) か、または ↵ Enter を押します。
    最新バージョンの代わりにリリース ブランチを使用したい場合は、以下のようにして指定できます vagrant hiera mediawiki::branch REL1_27
  8. 仮想マシンを開始します: 
    $ vagrant up
    初めてこれを行う場合、NFS を介したディレクトリ共有の設定にはシステム管理者権限が必要なため、パスワードの入力を求められることがあります。 適切な sudo 権限を設定することで、こちらに記載されているように、それを回避できます。
    コンソール出力に注意し、エラーがないことを確認してください。 エラーが発生した場合は、#起動時のトラブルシューティング節が役立つかもしれません。
  9. コマンド vagrant open を実行して MediaWiki インスタンスを開きます。 ユーザー名 Admin とパスワード vagrant でログインできます。
  10. 他の MediaWiki 機能や拡張機能を有効にします。
    有効にできる機能 (vagrantロール) の一覧を表示するには、以下を実行します:
    $ vagrant roles list
    機能、例えばビジュアルエディター を有効にするには、以下を実行します:
    $ vagrant roles enable visualeditor
    有効にしたロールをウィキに適用するには、以下を実行します:
    $ vagrant provision
既定の VirtualBox プロバイダーを使用している場合で、かつホスト上の仮想 CPU の数が 32 を超えている場合、vagrant up は失敗します。 vagrant config vagrant_cores <コア数> を使用して、32 未満のコアを VM に割り当てます。
最初の vagrant up が完了するのに1時間以上かかるかもしれません。

Windows Subsystem for Linux (WSL)

Windows 10 で WSL Linux 互換シェルを使用する場合: コマンドを vagrant ではなく vagrant.exe で実行します。Linux bash シェルで動作しない ./setup.bat ではなく、vagrant.exe config --required を実行します。

Vagrant を実行しているアカウントには、おそらく「シンボリックリンクを作成」する権限が必要です (これを実現する簡単な方法は、管理者として実行することです)。

トラブルシューティングのスタートアップ

問題の解決策がこのページで見つからない場合は、チャットルームの、特に#wikimedia-tech 接続チャネルで相談するといいかもしれません。

  • インストールプロセスの最も時間のかかる部分を繰り返さずに仮想マシンを再構築する vagrant destroy; vagrant up を実行することで、破損したインストレーション (例: 「ウィキが見つかりません...」が表示される) を修正できる場合があります。

あらゆるホスト

  • VirtualBox と Vagrant は Linux ディストリビューションの提供するバージョンをインストールしてみます。Debian または Ubuntu の最近の版を稼働する利用者は、sudo apt-get install virtualbox vagrant を試してVirtualBox と Vagrant のパッケージをインストールします。
  • エラーメッセージが vagrant up から送られる場合には、代わりにVirtualBoxとVagrantの最新バージョンをインストールします。
  • エラーメッセージのうち「$CLONED_REPOSITORY/trusty-cloudを開けません」などと表示される場合は、以下のコマンドを試してみます。 vagrant up --provider=virtualbox
  • puppet errors が発生した場合は、puppetモジュール初期化が求められている可能性があり、vagrantディレクトリでgit submodule update --initを実行します
    • Error: Puppet::Parser::AST::Resource failed with error ArgumentError: Could not find declared class
  • Apache/PHPが有効で機能しているかどうか確認するには、http://127.0.0.1:8080/info.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_ALLtryの環境変数の設定（再設定）を適切な値に変えてみます。 例:
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
過去に VM の旧版を削除した場合、エラー メッセージが表示され vagrant up が完了しません。 NFS利用者（Windows以外のホストのOS上で）は/etc/exportsの削除で解決します：sudo rm -i /etc/exportsを入力 vagrant up の次回の実行時に、/etc/exports ファイルが新たに生成されます。
MediaWiki-Vagrantは64ビットのゲスト（仮想マシン）を特定するVT-Xをサポートしないホストでは稼働しません。 MediaWiki-Vagrant の稼働には64-bit仮想マシンが必要であり、amd64アーキテクチャ限定でビルドされたWMF製use deb パッケージ他を使用するからです。

Windows特有

  • Windows利用者で「ゲストマシンが無効になりました」 - 「電源オフ」の状態になった場合、VirtualBoxの4.3.15ビルドのダウンロードを試してください（Windowsでは4.3.14のビルドに既知の問題あり）。それでも解決しない場合はBIOSでハードウェア仮想化技術（VT-xもしくはAMD-V）が有効かどうか確認。ハードウェア仮想化は必須であり、オプションのパフォーマンス強化ではありません。（一部のノートパソコンでは電源ケーブルとバッテリーを30秒間、取り外す必要あり [1]）
  • VirtualBox は、マイクロソフトの Hyper-V と互換性がありません。 Hyper-Vを有効にした場合 – Visual Studio をインストールした環境ではおそらく既定 – VirtualBox の VM をブートしようとすると上記のエラーが発生します。 可能な対処法は3つ:
    • Hyper-Vを終了させるためコマンドプロンプトで「bcdedit /set hypervisorlaunchtype off」を実行後、リブート。 Hyper-Vをオンにするには、「オフ」から「自動」に切り替え
    • コントロール パネルの「Windows の機能を追加・削除」を介して Hyper-V を無効化、再起動する。 この操作で VirtualBox を有効にできるものの、Windows Phone のエミュレータなど Hyper-V VMs はすべて無効になります。
    • または、VirtualBox の代わりに Vagrant Hyper-V provider を使う。 これは不安定の可能性があります。

Mac特有

  • NFS errors NFSエラーの回避には、インストール作業中にファイアウォールで接続を認めるように設定します：Apple > システム設定 > セキュリティとプライバシー > ファイアウォール > ファイアウォールのオプション。 「外部からの接続をブロック」のレ点を外し、さらに「ステルスモードを有効にする」も外すことで以下を可能にします：netbiosd、nfsd、rpc.lockd、rpc.rquotad、rpcbind、VBoxHeadless。 注記＝コンピュータの再起動を求められ、さらに複数の vagrant up でステータスを「外部からの接続を許可」に変更を求められる場合があります。 インストール完了後、ファイアウォールのルールが更新できていれば「全ての外部からの接続をブロック」「ステルスモードを有効にする」にレ点を入れることができるはずです。
    • 代替策としてvagrant config nfs_shares off経由でNFSシェアをオフにできます

Debian および Ubuntu

  • MediaWiki-Vagrant は特定のフォルダーをホストマシン (利用者のコンピューター) と共有するため NFS を使います。 それには利用者のコンピュータをUbuntuの手順の指示などを参照して「NFSサーバ」に設定する必要があります。 Debian上では sudo apt-get install nfs-kernel-server が使えます。こちらも modprobe nfsv3 の処理をします。 注記＝DebianのNFSサーバを始動するには /etc/exports にエントリをします。 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 daemon を再起動すると解決することがあります。 (#5802 を参照してください。)
  • ポート フォワーディングのエラーが発生してポートが使用中というメッセージが出る場合は、VirtualBox を開き仮想マシンを完全に除去してから、再実行します。
  • vagrant up は「The executable 'bsdtar' Vagrant is trying to run was not found in the PATH variable.」と表示されることがあります。 Ubuntu ではこれは sudo apt install libarchive-tools で修正できます。
  • セキュア ブートが有効な Ubuntu では、VirtualBox のインストールは困難です。 /sbin/vboxconfig を実行すると、あなたのマシンはグッとくるかもしれません。 その場合、関連するカーネル モジュールに署名することで状況を改善できます。 ステップ バイ ステップの手順は、こちらの askubuntu 投稿にあります。

Fedora

  • vagrant up を実行後に Network 10.11.12.13 is not available. のように表示された場合、sudo setenforce 0 を介して SELinux を無効にするか、または SELinux セットアップを修正します。
  • vagrant roles enable mediawiki --provision を実行した後に The provider for this Vagrant-managed machine is reporting that it is not yet ready for SSH. のように表示された場合は、プロバイダーを明示的に設定していることを確認してください。例えば、vagrant destroy の後に vagrant up --provider=virtualbox を実行します。
  • mount.nfs: mount to NFS server '10.11.12.13:download-directory/vagrant' failed: RPC Error: Unable to receive のように表示された場合は、vagrant config nfs_shares を実行します。

基本的な使用法

スクリーンショット

ホストマシン上の vagrant コマンドライン ツールは仮想マシンの制御に使うサブコマンドを複数、提供します。 実は既に利用しています。仮想マシンをオンにする vagrant up です。 大部分の vagrant サブコマンドと同様、実行は MediaWiki-Vagrant ディレクトリもしくは その下位ディレクトリから起動する必要があります。 初回の起動では Vagrant がシステムイメージを取得、MediaWiki の駆動に不可欠なソフトウェアを準備します。 処理にはブロードバンド接続で CPU 時間と実測時間で1–2時間かかるものの、実行は 1 回限りです。 その後 vagrant up を起動すると仮想マシンをすぐに起動します。

vagrant ssh は仮想マシン上にインタラクティブなログインシェルを起動します。 ユーザー vagrant としてログインされます。root アクセスはパスワードなしで sudo を介して利用可能です。 仮想マシンはユーザのコンピュータ上で完全にサンドボックス化されており、環境設定はセキュリティではなく使いやすさ主体です。 原則としてパスワードを求められたら vagrant と入力します。

ログインすると色鮮やかなMediaWikiのバナーの他、便利なコマンドのヒントが表示されます。

コマンドの phpsh は既に読み込まれた MediaWiki のコードベースとともに対話的な PHP インタプリターを開始します。 コードを入力して「Enter」キーを押すとコードは直後に評価されます。 行頭に等号「=」を入力すると処理結果はプリティプリントで出力されます。 ? と入力すると簡潔なヘルプを、help start で補足的な指示を表示します。

/vagrant フォルダーは利用者のホストマシン上の MediaWiki-Vagrant フォルダーに対応し、内容を共有します。 MediaWikiの コードのインストール先は /vagrant/mediawiki です。 そのため仮想マシンのMediaWikiコードの編集は、ホストマシン上の通常のエディタ環境を利用できます。

更新

gitリポジトリや外部ライブラリ、データベースのスキーマを最新に保つには、vagrant git-update を使います。 このコマンドは次の処理に相当します。

  1. core とすべての拡張機能や外装のディレクトリで git pull を走らせる。
  2. composer update を走らせ、最新の Composer で管理するライブラリを使用できるようにする
  3. さらに update.php スクリプトを走らせる。

また機会を見て（もしくは近い将来の必要に応じて）vagrant git-update に含まれないMediaWiki-Vagrant自体を更新する必要があります。実行する内容は以下のとおり。 

git pull

… MediaWiki-Vagrant ルート ディレクトリで実行します。これは、以下を実行すると反映されます: 

vagrant provision

そのコマンドを実行できるのは、git pull を実行した直後、または一定時間経過後です。

警告 警告: git を利用して手動で更新する場合、同時に composer update を実行し、MediaWikiで必須とされる外部ライブラリをダウンロードする必要があります。 composer update が必要かどうか判断するには、checkComposerLockUpToDate.php スクリプトを実行します。
プロジェクトによっては、Composer ではインストールされない NPM の依存関係がある場合があります (多くは開発用のみ)。これらは find -not \( -name node_modules -prune \) -name package.json でおおよそ特定でき、更新後に各ディレクトリで npm install を実行することで、必要に応じて手動でインストールできます。

仮想マシンからログアウトするには logout と入力するか Ctrl+D のキーを押します。 すると標準のコマンド プロンプトに戻り、vagrant halt を実行して仮想マシンをシャットダウンしたり、vagrant up で起動したりできます。 vagrant destroy を実行すると、仮想マシンのファイルが削除されます。このコマンドはインスタンスを元の状態に戻したい場合に役立ちます。 (新たなインスタンスとして整えるには続いて vagrant up を実行します。)

ロールの利用

MediaWiki-Vagrant は既定で基本的な MediaWiki インスタンスをセットアップしますが、いくつかの人気のある MediaWiki 拡張機能とその依存関係を含む一連の補完的なソフトウェアを構成する方法も網羅しています。 これらの選択可能なソフトウェア スタックを総合して「ロール」(roles: 役割) と呼ばれ、MediaWiki-Vagrant はそれらを管理するための簡単で強力なコマンドライン インターフェイスを提供します。

$ vagrant roles list # 利用できるロールの一覧。 $ vagrant roles enable ロール # このマシン上で ロール をオンにする。 $ vagrant roles disable ロール # このマシン上で ロール をオフにする。 $ vagrant provision # ロールの有効/無効の切り替えが完了したら、変更を反映するため起動する。

短編の screencast でロールの使い方を実演しています。 ロールのページでその他の詳細情報を紹介します。

追加するロールが多い場合は、Vagrant VM に割り当てるメモリを増やす必要がある場合があります。 特に「browsertests」(ブラウザー テスト) ロールのセットアップには ffi ruby Gem のコンパイルというメモリを消費するタスクが含まれます。失敗した場合は VM 内のメモリの解放またはメモリ割り当ての増加をしてみてください (バグ 53864)。

MediaWiki-Vagrantにロールを増やす方法に興味があれば、下記の「ロールのオーサリング」の節を参照してください。

特定のロールのトラブル解決

centralauth (中央管理認証)

特に注意が必要なロールがあります。centralauth ロールは puppet経由で自動的にデータベース移行を実行しないため、手動で実行する必要があります。このロールのプロビジョニングでエラーが発生した場合は、このスクリプトを拡張機能で実行し、出力されるエラーを確認してください: 

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

より具体的なエラーが出たら、おそらく以下にあるものからどのような移行を実行する必要があるかを知る必要があります: 

extensions/CentralAuth/db_patches

wikidata (ウィキデータ)

単純な vagrant roles enable wikidata && vagrant provision は失敗します。 ここでは、ウィキデータのロールを稼働させるためのコマンド一式を紹介します。 

$ 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

1 回目のプロビジョニングでは文句を言われ、失敗したように見える場合があることにご注意ください。しかし、2 回目のプロビジョニングを実行すると、すべてがうまくいくことが分かります。

その後、ブラウザーで http://wikidata.wiki.local.wmftest.net:8080/ にアクセスできます。新しいウィキデータ項目を作成するために　http://wikidata.wiki.local.wmftest.net:8080/wiki/Special:NewItem　を読み込み、新しいプロパティを作成するために http://wikidata.wiki.local.wmftest.net:8080/wiki/Special:NewProperty に遷移します

ウィキデータ ダンプを取り込む方法

Vagrant コマンド import-dump は、XML ファイルを MediaWiki にインポートする際、既定以外のウィキには対応していません (phab:T183274#3893785 を参照)。 importDump.php スクリプトを Vagrant ボックス内 で実行する必要があります。

以下は、XML ダンプをインポートする手順です: 

$ mkdir wikidata_dumps
$ cd wikidata_dumps
  • pages-articles チャンクをダウンロードします。例:
$ wget https://dumps.wikimedia.org/wikidatawiki/latest/wikidatawiki-latest-pages-articles10.xml-p5264684p6341661.bz2
  • ウィキベース エンティティのインポートを有効にします (phab:T72898#1588002 を参照)。以下の行を LocalSettings.php に追加してください:
$wgWBRepoSettings[ 'allowEntityImport' ] = true;
  • 次の BASH スクリプトは、プロセスを監視するのに役立ちます。これを import_wikidata.sh ファイルに貼り付けてください。強調表示された行が実際のインポート スクリプトを呼び出します:
#!/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
  • Vagrant ボックスにログインし、スクリプトを実行します。デバッグ メッセージが表示されるはずです:
$ vagrant ssh
$ cd /vagrant
$ sudo chmod +x import_wikidata.sh
$ ./import_wikidata.sh
  • Vagrant ボックス外から進行状況のログを確認できます:
$ tail -f wd_import.log

追加的な提案

Windows 上で MediaWiki を高速化

MediaWiki は、既定の設定ではおそらく動作が遅くなります (ページ読み込みに5秒以上かかる)。 これは、仮想マシンが非常に遅くファイルを取得する共有ファイル システムを使用しているためです。 Vagrant WinNFSd プラグインを vagrant plugin install vagrant-winnfsd でインストールして NFS を有効にし、vagrant config nfs_shares true で NFS 共有を有効化し、vagrant reload でマシンを再起動することで、ページの読み込み速度が大幅に向上します。 マシンを起動するたびにプラグインがインストールされていることを確認する必要があります。[4] さらに、nfs_cache を有効にすることで、速度を向上させられます。ただし、キャッシュを使用すると一部のファイルが完全に更新されず、ウィキが予期しないエラーに遭遇する可能性があるため、注意が必要です。

また、smb_shares を使用することで、MediaWiki の速度を向上させることもできます。 nfs_shares と同時にこれを有効にしないように注意してください。 vagrant config smb_shares yes を有効にし、管理者としてシェルを実行して vagrant reload を実行してください。 管理者として実行しない場合、vagrant が起動するときにエラーで警告され、ウィキのアドレスにアクセスすると Wiki not found が表示されます。 プロンプトが表示されたら、アカウントのユーザー名 (ホーム ユーザー ディレクトリの名前) とパスワード (アカウントが通常のローカル アカウントではない場合は Microsoft アカウントのパスワード) を入力してください。

ローカルにMediaWikiコアを複写

場合によっては、vagrant ディレクトリ全体を削除したり、vagrant/mediawiki ディレクトリをクリーンアップして、最初からやり直すことが必要になることがあります。 Vagrant のプロビジョニング プロセスを高速化するために、ローカルで更新された MediaWiki コアのクローンを保持し、それを vagrant/mediawiki にコピーすることを検討してください。

例えば、~/projects/mediawiki/ に MediaWiki リポジトリをクローンするとします: 

# MediaWiki コアのクリーン コピーを ~/projects/mediawiki/core 内に複製して格納
cd ~/projects/mediawiki/
git clone ssh://<your-gerrit-username>@gerrit.wikimedia.org:29418/mediawiki/core

# vagrant のクリーンな複製を ~/projects/mediawiki/vagrant に作成
cd ~/projects/mediawiki
git clone ssh://<your-gerrit-username>@gerrit.wikimedia.org:29418/mediawiki/vagrant

# mediawiki 下位ディレクトリが存在しない場合は作成
cd ~/projects/mediawiki/vagrant
mkdir ~/projects/mediawiki/vagrant/mediawiki

# クリーンな MediaWiki コアをクリーンな vagrant/mediawiki ディレクトリにコピー
cp -r ~/projects/mediawiki/core/ ~/projects/mediawiki/vagrant/mediawiki

クローンしたリポジトリの更新

複製されたリポジトリをできるだけ頻繁に/必要に応じて更新します。 

cd ~/projects/mediawiki/core
git pull

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

または、複製されたリポジトリをすべて更新するには: 

vagrant git-update

Vagrantの再読み込み

設定を変更した場合 (例: vagrant_ram、VM/MediaWiki サイトがフリーズしたり、問題が発生した場合)、vagrant reload を実行すると解決するかもしれません。 これによりゲストが再起動されます。 一部のロールは再読み込みが必要で、自動的に行われるはずです。

ロールを有効にするタイミング

最初の vagrant up が正常に実行されるまで、ロールを有効にしないでください。

vagrant destroy は有効なロールをリセットしないことに注意してください。 vagrant destroy を実行した後は、すべてのロールを無効にしてから vagrant up を実行してください。 その後、任意のロールを再度有効にして vagrant provision を実行できます。

proxyの背後のVagrant

プロキシの背後にいる場合、Vagrant はエラーを出すかもしれません。 vagrant-proxyconf をインストールすることもできます。 仮想マシンが特定のプロキシを使用できるようにするプラグインです。 これは簡単なセットアップ ガイドです。 詳細な説明文書についてはこちらを確認してください。

プラグインをインストールします: 

vagrant plugin install vagrant-proxyconf

すべての vagrant 仮想マシン上のすべてのソフトウェアのプロキシ設定を変更するには、$VAGRANT_HOME/Vagrantfile (既定では ~/.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
  # ... 省略
end

アドレスをプロキシ サーバーの IP アドレスとポート番号に置換してください。 config.proxy.no_proxy オプションを使用して、プロキシをバイパスしたいすべてのサイト/ドメインを列挙します。例えば、 

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

この状態で vagrant up を実行すると、警告が表示されないはずです。

プラグインを無効にするには、config.proxy.enabled を false または空の文字列 ("") を設定します。 特定のアプリケーションに対しても無効にできます。例: 

config.proxy.enabled         # → すべてのアプリケーションが有効 (既定)
config.proxy.enabled = true  # → すべてのアプリケーションが有効
config.proxy.enabled = { svn: false, docker: false }
                             # → 特定のアプリケーションが無効
config.proxy.enabled = ""    # → すべてのアプリケーションが無効
config.proxy.enabled = false # → すべてのアプリケーションが無効

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

プロビジョニング

以下を実行することでプロビジョニングの過程をデバッグできます: 

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

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

  • 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.

Running and debugging unit tests

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);


  • In the above file, change argv parameter to the name of your test file
  • 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 単体テスト を参照してください。

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.

トラブルシューティング

Check PHP version and settings
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.

カスタム パペット コードを追加するには?
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
Git コミット メッセージに使用するエディターを変更するには?
git config --global core.editor "vim"
カスタム ホスト名をセットアップするには?
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. 説明書は Topic:W05qhsn58ztktod8 を参照してください。

高度な使用法

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 のフラグ

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

ジョブ キュー

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.

  1. puppet/modules/mediawiki/templates/jobrunner.json.erb を開きます
  1. Change the value for the runners key from 1 to the desired value (say, 4)
  1. Re-provision with vagrant --provision
  1. 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)
  • VirtualBox マネージャーを開きます
  • VM を選択して設定を開きます
    • ストレージを選択して、「コントローラー: SATA」を選択して「ハードディスクの追加」アイコンをクリックします。
    • 既定のディスク イメージの種類を選択します。
    • ディスクに「VagrantImageSpace」などの名前を付け、十分な容量 (例えば 80GB) を指定します。既定では、ファイルは小さい状態で始まり、実際の使用量に応じて拡大されるため、必要なだけの容量を指定します
    • 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)

ロールのオーサリング

MediaWiki-Vagrantが作成した仮想マシンは、ウィキメディアの主要なプロジェクトの制作環境に似ていて、ウィキメディアの技術オペレーションチームが本番サーバー管理ならびにWikimedia Cloud VPSインスタンスに使うのと同じツール—Puppet—を用います。 設定管理ツールとしてのPuppetは、宣言型のソフトウェア設定を表現するドメイン固有の言語を提供します。 Puppetコードを含むファイルが〈マニフェスト〉です。 Puppetを実行すると利用者が送ったマニフェストを解釈し、それに従ってマシンを設定します。 Vagrantのロールとは、つまりPuppetのマニフェストの組み合わせなのです。

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:

Setting up an instance on Cloud 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.

リンク

注記

  1. ↑ Fedora利用者はOracleの指示に従わないでください。代わりに RPMfusion リポジトリを有効化（例えばApper設定経由）した後、sudo dnf install VirtualBox VirtualBox-kmodsrc akmod-VirtualBox kmod-VirtualBox を実行します (注記: 大文字小文字識別で、場合によりバージョン識別あり！ パッケージが見つからない時は Discover で検索。) こちらのガイドに従うと代替手段が使えます。 エラーが表示され、カーネルが新しすぎると警告を受けることがあります。その場合には akmods-VirtualBox をインストール後、sudo akmods を起動してモジュール作成を確認します。
  2. ↑ Fedora では、sudo dnf install vagrant を実行できます。
  3. ↑ https://github.com/hashicorp/vagrant/issues/10576#issuecomment-452793401
  4. ↑ https://peshmerge.io/how-to-speed-up-vagrant-on-windows-10-using-nfs/
  5. ↑ Vagrant dependent on MediaWiki 1.21+
Retrieved from "https://www.mediawiki.org/w/index.php?title=MediaWiki-Vagrant/ja&oldid=6753792"