MediaWiki-Vagrant

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page MediaWiki-Vagrant and the translation is 74% complete.

Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎català • ‎dansk • ‎español • ‎français • ‎italiano • ‎polski • ‎português • ‎português do Brasil • ‎suomi • ‎Ελληνικά • ‎русский • ‎नेपाली • ‎中文 • ‎日本語 • ‎한국어
Aperçu visuel de Vagrant
Logo de MediaWiki Vagrant
Bryan Davis explique dans une interview à Wikimania ce qu'est MediaWiki Vagrant.
TechTalk sur MediaWiki - Vagrant par Bryan Davis et Dan Duvall
Diapositives de TechTalk sur MediaWiki - Vagrant par Bryan Davis et Dan Duvall

MediaWiki - Vagrant est un environnement de développement de MediaWiki portable. Il se compose d' un ensemble de scripts de configuration pour Vagrant et VirtualBox qui automatisent la création d'une machine virtuelle qui exécute MediaWiki. Since the configuration is geared towards easy development rather than security, MediaWiki-Vagrant is not recommended for publicly accessible wikis.

La machine virtuelle que MediaWiki-Vagrant créé fait qu'il est facile d'apprendre, de modifier et d'améliorer le code de MediaWiki : des informations de débogage utiles sont affichées par défaut, et les différents outils de développement sont mis en place spécifiquement pour inspecter et interagir avec le code MediaWiki, y compris un débogueur puissant et un interpréteur interactif. Le meilleur de tous, car la configuration est automatisée et contenue dans un environnement virtuel, les erreurs sont alors faciles à corriger.

System requirements

CPU
64-bit x86 processor
OS
Linux, macOS, or Windows
Memory
At least 4 GiB RAM total on your system, preferably 8 GiB or more, in order to run both the host operating system and the VM. Do not attempt to run on a system with only 2 GiB RAM, it will eventually fail.
Disk
Must have several gigabytes free on the primary drive (/home partition for Linux, C: drive for Windows). Note in particular that the VM disk images will be stored under your home directory by default.
Network
Active network connection with sufficient bandwidth to download Debian Linux updates and MediaWiki source code
Time for setup
20 minutes to 2 hours, depending on conditions and if you have any troubles

Démarrage rapide

(Si vous installez MediaWiki-Vagrant à partir de la distribution USB, suivez les étapes du fichier README plutôt que les quatre premières étapes.)

  1. Téléchargez Git
  2. (Linux only) Install NFS if it is not already installed. In Ubuntu, use sudo apt-get install nfs-kernel-server. Fedora usually come with NFS installed, but try sudo dnf install vagrant-libvirt and see the specific documentation page to make sure a Fedora NFS setup is OK.
  3. Téléchargez la dernière version de VirtualBox.[1]
  4. Téléchargez la dernière version de Vagrant.[2]
  5. Récupérez le code et créez votre machine :
    $ git clone --recursive https://gerrit.wikimedia.org/r/mediawiki/vagrant
    
    (This will clone into your user home directory.)
    $ cd vagrant
    $ ./setup.sh
    
    When prompted, enter your Gerrit user name (recommended), or just press Enter.
    If you want to use a release branch instead of the latest version, you can specify it now with vagrant hiera mediawiki::branch REL1_27
    $ vagrant up
    
  6. Activez les fonctionnalités additionnelles de MediaWiki, par exemple :
    $ vagrant roles list
    $ vagrant roles enable monobook --provision
    
  7. Lorsque Vagrant est opérationnel, configurez votre machine, accédez à http://127.0.0.1:8080/ pour trouver votre instance MediaWiki. You can login with user Admin and password vagrant.
Cela peut prendre une heure ou plus avant que le premier vagrant up soit terminé.

Si vous utilisez Windows

Téléchargez Git for Windows et exécutez les commandes git dans son interface système Git Bash. Exécutez setup.bat à partir de cmd.exe shell.

If using the WSL Linux-compatible shell on Windows 10: run commands with vagrant.exe instead of vagrant. Run vagrant.exe config --required instead of ./setup.bat, which does not work in the Linux bash shell

Problèmes de démarrage

Si vos questions ne trouvent pas de réponses ici, IRC est une bonne option, en particulier le canal #wikimedia-devconnect.

Tout hôte

  • Vous pouvez essayer d'installer les versions de VirtualBox et Vagrant que votre distribution Linux vous fournit. Si vous utilisez une version récente de Debian ou Ubuntu, essayez sudo apt-get install virtualbox vagrant pour installer les packages pour VirtualBox et Vagrant. (Vous avez besoin d'installer le paquet ruby-dev recommandé pour Vagrant.)
  • Si vous obtenez des erreurs de vagrant up , installez à la place les versions les plus récentes de VirtualBox et Vagrant.
  • If you run into error message like "Couldn't open file $CLONED_REPOSITORY/trusty-cloud", try the following command: vagrant up --provider=virtualbox
  • Si vous avez des erreurs de "puppet" vous pourriez avoir besoin d'initialiser les sous-modules de "puppet", dans le répertoire vagrant exécutez git submodule update --init
    • Error: Puppet::Parser::AST::Resource failed with error ArgumentError: Could not find declared class
  • Utilisez http://127.0.0.1:8080/info.php pour vérifier que le serveur Apache/PHP est en cours d'exécution.
  • Vous pourriez avoir envie de comparer la sortie de la première exécution de vagrant up dans votre terminal avec cet échantillon. La configuration initiale peut prendre un certain temps; si elle semble se bloquer quelque part, mais sans avoir d'erreurs, il suffit de lui laisser un peu temps.
  • Si vous obtenez des avertissements que vos "Guest Additions" de VirtualBox ne sont pas dans la bonne version, vous pouvez essayer d'installer le plugin vagrant-vbguest qui les met à jour automatiquement.
  • Vagrant perd rarement la liaison avec votre VM. This thread parle des façons de travailler autour de ça (par exemple l'attachement d'un ancien disque dur virtuel vers le nouveau profil)
  • Assurez-vous que ce référentiel vagrant/mediawiki soit à jour :
$ cd vagrant/mediawiki
$ git pull
  • Assurez-vous que vous ayez bien activé la virtualisation dans le BIOS. Parfois, cela se trouve dans les paramètres de sécurité.
  • Assurez-vous que vos paramètres de codage de langue soient bien en UTF-8. Si vous obtenez "invalid byte sequence in US-ASCII", essayez de (re) paramétrer vos variables d'environnement LANG et LC_ALL à une valeur convenable.

Par exemple :

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
  • Sometimes you can fix broken installations (e.g. one saying "No wiki found..." by running vagrant destroy; vagrant up which will rebuild the virtual machine without repeating the most time-consuming parts of the installation process.
Si vous avez supprimé toute les anciennes VM, vous verrez un message d'erreur comme "...le chemin contient des composants qui ne sont pas des répertoires ou qui sont inexistants..." et vagrant up ne sera pas complet. If you are using NFS (on a non-Windows host operating system), you should be able to fix this by removing /etc/exports: enter sudo rm -i /etc/exports Vagrant va recréer le fichier /etc/exports la prochaine fois que vous l'exécuterez. vagrant up.
MediaWiki-Vagrant ne fonctionnera pas sur un hôte qui ne prend pas en charge VT-X, car il est prévu pour fonctionner avec un invité 64bit (machine virtuelle). MediaWiki-Vagrant doit fonctionner sur une machine virtuelle 64 bits, en partie parce qu'il utilise des paquets deb de la production WMF qui sont uniquement compilés pour l'architecture amd64.


Spécifique à Windows

  • Si vous êtes sous Windows et que vous obtenez le message "La machine invité est entrée dans un état non valide" - "Extinction", essayez de télécharger une version de VirtualBox 4.3.15 (there is a known problem with 4.3.14 on Windows). Si cela ne vous aide pas, vérifiez que vous ayez bien activé le paramètre "Hardware Virtualization Technology" (VT-x ou AMD-V) dans le BIOS. La virtualisation du matériel est nécessaire, il ne s'agit pas d'une simple option pour améliorer les performances. (Pour certains ordinateurs portables, il est nécessaire d'enlever le câble d'alimentation et la batterie pendant 30 secondes [1]).
  • VirtualBox est incompatible avec Hyper-V de Microsoft. Si vous avez Hyper-V d'activé – ce qui peut être le cas par défaut si vous avez installé Visual Studio – vous obtiendrez les erreurs ci-dessus en essayant de démarrer une machine virtuelle dans VirtualBox. Il y a deux possibilités :
    • In command prompt run bcdedit /set hypervisorlaunchtype off to turn off Hyper-V and reboot. To turn Hyper-V back on set it back to auto instead of off
    • Désactivez Hyper-V grâce à l' "Ajout/Suppression de fonctionnalités Windows" dans le Panneau de contrôle puis, redémarrez. Cela va vous permettre de faire fonctionner VirtualBox, mais va vous empêcher d'utiliser toute VM Hyper-V que vous pourriez avoir, comme par exemple les émulateurs de téléphone Windows.
    • Ou, utilisez le fournisseur Hyper-V pour Vagrant au lieu de VirtualBox. Cela peut être instable.

Spécifique au Mac

  • Erreurs NFS Pour éviter les erreurs NFS lors de l'installation, assurez vous que le pare-feu accepte bien les connexions : Apple > Préférences Système > Sécurité et confidentialité > Pare-feu > Options de pare-feu. Vous aurez besoin de décocher la case "Bloquer toutes les connexions entrantes" et probablement aussi de décochez "Activer le mode furtif" pour pouvoir accepter les éléments suivants : netbiosd, nfsd, rpc.lockd, rpc.rquotad, rpcbind et VBoxHeadless. Notez que vous devrez peut-être redémarrer votre ordinateur et changer le statut à "Autoriser les connexions entrantes" pendant un "couple vagrant up</ code>s". Après l'installation, vous allez pouvoir être en mesure de re-vérifier "Bloquer toutes les connexions entrantes" et "Activer le mode furtif" maintenant que les règles de pare-feu ont été mises à jour.
    • Sinon, vous pouvez désactiver les partages NFS via le vagrant config nfs_shares off.

Debian et Ubuntu

  • MediaWiki-Vagrant utilise NFS pour partager certains dossiers avec la machine hôte (votre ordinateur). Vous devez configurer votre ordinateur comme un "serveur NFS", voir par exemple Ubuntu instructions. Sous Debian, sudo apt-get install nfs-kernel-server fonctionnera ; vous aurez peut-être aussi besoin de modprobe nfsv3. Notez que le serveur NFS de Debian ne démarre pas sans une entrée dans /etc/exports. Si sudo rpcinfo -p ne montre pas que les services "nfs" sont en cours d'exécution, c'est que c'est probablement le cas. l'ajout de votre répertoire personnel comme étant la dernière ligne dans /etc/exports et /etc/init.d/nfs-kernel-server restart sera généralement suffisant pour outrepasser ce problème de la poule et de l'oeuf.
  • Les partages NFS utilisés par MediaWiki-Vagrant ne peuvent pas être exécutés à partir d'un répertoire crypté, ce qui peut être le cas si vous êtes sous Ubuntu, et que vous utilisez un répertoire personnel chiffré. Pour exécuter MediaWiki - Vagrant vous pouvez soit :
    • Déplacez le répertoire MediaWiki-Vagrant vers un volume non crypté (par exemple /opt) avant l'exécution de vagrant up .
    • Sinon, vous pouvez également désactiver les partages NFS via vagrant config nfs_shares off.
  • Si vous obtenez des erreurs de redirection de port qui disent que les ports sont en cours d'utilisation, vous devrez peut-être ouvrir Virtual Box, supprimer entièrement la machine virtuelle, et essayer à nouveau.
  • Si vous êtes sous Ubuntu 16.04, vous pourriez avoir une erreur lors de l'installation du plug-in 'vagrant-vbguest'. Cela est dû à un bogue dans un fichier ruby appartenant à Vagrant. Le bug est seulement résolu en amont, mais vous pouvez le "patcher".

Utilisation de base

Screenshot

L'outil de ligne de commande vagrant sur la machine hôte fournit plusieurs sous commandes pour contrôler votre machine virtuelle. Vous en avez déjà utilisé une : vagrant up, qui tourne sur la machine virtuelle. Comme la plupart des sous commandes vagrant, vous devez l'exécuter à partir du répertoire MediaWiki - Vagrant ou l'un de ses enfants. Lorsque vous l'exécutez pour la première fois, Vagrant va chercher une image système et configurer le logiciel nécessaire pour l'exécution de MediaWiki. Cela peut prendre 1-2 heures d'utilisation du CPU avec une connexion à large bande, mais ça ne se produira que la première fois. Si vous exécutez à nouveau vagrant up par la suite, ça va tout simplement démarrer la machine.

vagrant ssh démarre un shell interactif de connexion sur la machine virtuelle. Il va vous connecter en tant qu'utilisateur vagrant; L'accès root est disponible via sudo, qui s'utilise sans avoir recours à un mot de passe. Parce que la machine virtuelle est entièrement "sandboxed" au sein de votre ordinateur, elle est configuré pour la commodité, pas pour la sécurité. En règle générale, chaque fois que vous rencontrerez une demande de mot de passe, le mot de passe à saisir sera vagrant.

Lorsque vous vous connectez, vous devriez voir une bannière MediaWiki coloré et quelques rappels de commandes utiles.

La commande hhvmsh va démarrer un interpréteur PHP interactif avec le code de base de MediaWiki déjà chargé. Vous pouvez saisir du code, appuyer sur la touche 'entrée', et le code sera évalué immédiatement. Si vous commencez une ligne avec '=', la valeur calculée sera affichée. Tapez ? pour une aide rapide ou help start pour obtenir des instructions supplémentaires.

Le dossier /vagrant correspond au dossier MediaWiki-Vagrant sur ​​votre machine hôte, et son contenu est partagé. Le code de MediaWiki est installé dans /vagrant/mediawiki. Cela vous permet d'utiliser votre éditeur d'environnement par défaut sur votre machine hôte pour modifier le code de MediaWiki qui fonctionne sur votre machine virtuelle.

Utilisez vagrant git-update pour garder vos dépôts Git, les bibliothèques externes, et le schéma de base de données à jour. Cette commande est équivalente à l'utilisation de

  1. git pull dans core et tous les répertoires d'extension et de thèmes (skins)
  2. composer update pour veiller à ce que les dernières bibliothèques "Composer-managed" soient disponibles.
  3. Et pour finir, le script update.php.

You should also occasionally (or when needed for a new feature) update MediaWiki-Vagrant itself, which vagrant git-update does not include. Run:

git pull

in your MediaWiki-Vagrant root directory. This will take effect when you run:

vagrant provision

(immediately or later).

Avertissement Avertissement : Si vous faites des mises à jour à partir de git manuellement, vous devrez peut-être exécuter composer update pour télécharger les bibliothèques externes requises par MediaWiki. Vous pouvez exécuter le script checkComposerLockUpToDate.php pour voir si composer update est nécessaire.
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.

Déconnectez-vous de votre machine virtuelle en tapant logout ou en appuyant sur CTRL + D. Maintenant que vous êtes de nouveau dans une invite de commande standard, vous pouvez exécuter vagrant halt pour arrêter la machine virtuelle et vagrant up pour la "remonter". vagrant destroy supprimera les fichiers de la machine virtuelle; Cette commande est utile si vous voulez revenir dans l'état d'origine. (Vous aurez besoin d'exécuter vagrant up à nouveau pour instancier une nouvelle machine virtuelle)

Utilisation des rôles

MediaWiki-Vagrant met en place une instance MediaWiki de base par défaut, mais cela demande aussi de savoir comment configurer une gamme de logiciels complémentaires, y compris certaines extensions populaires de MediaWiki et leurs dépendances. Ces piles de logiciels optionnels sont communément appelées «rôles» et MediaWiki-Vagrant offre une interface en ligne de commande simple et puissante pour les gérer.

$ vagrant roles list
# Affiche une liste des rôles disponibles.

$ vagrant roles enable role
# Activer les "rôles" pour cette machine.

$ vagrant roles disable role
# Désactiver les "rôles" pour cette machine.

$ vagrant provision
# After you are done enabling and/or disabling roles, run this to make the change take effect.

Regardez une petite screencast montrant comment utiliser les rôles. Vous obtiendrez plus d'informations avec Rôles sur certains rôles.

Si vous ajoutez de nombreux rôles, vous devrez peut-être augmenter la mémoire disponible sur la VM Vagrant. En particulier, la mise en place du rôle "browsertests" qui implique la compilation du ffi ruby Gem qui est une tâche gourmande en mémoire; si elle plante essayez de libérer de la mémoire dans la machine virtuelle ou d'augmenter son allocation mémoire (bug 53864).

Voir la section Authoring roles ci-dessous si vous êtes intéressé pour ajouter des rôles à MediaWiki-Vagrant.

Problèmes avec des rôles spécifiques

Centralauth

Il y a des rôles qui nécessitent une attention particulière, le rôle centralauth ne fait pas fonctionner les migrations de base de données automatiquement via "puppet" et exige leur exécution à la main. Si vous obtenez des erreurs en approvisionnant ce rôle, essayez d'exécuter ce script à partir de l'extension et de voir les erreurs qui s'affichent en sortie :

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

Une fois que vous aurez obtenu une erreur plus concrète, vous aurez probablement besoin de savoir qu'elle est la migration à faire tourner parmi celles-ici :

extensions/CentralAuth/db_patches

wikidata

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

Log out from Vagrant, then you can happily run:

 $ 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
 $ 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

Pour aller plus loin

Copie du noyau MediaWiki en local

Il se peut que vous ayez parfois envie de recommencer à zéro en supprimant l'ensemble du répertoire vagrant ou en nettoyant le répertoire vagrant/mediawiki. Afin d'accélérer le processus de provisionnement de vagrant, vous pourrez peut-être envisager de garder un clone local d'un noyau MediaWiki à jour que vous pouvez copier dans vagrant/mediawiki.

par exemple, en supposant que vous clonez un dépôts MediaWiki dans ~/projets/mediawiki/ :

# clonez et stockez une copie propre du noyau MediaWiki dans ~/projets/mediawiki/core
cd ~/projects/mediawiki/
git clone ssh://<your-gerrit-username>@gerrit.wikimedia.org:29418/mediawiki/core

# clonez une copie propre de vagrant dans ~/projets/mediawiki/vagrant.
cd ~/projects/mediawiki
git clone ssh://<your-gerrit-username>@gerrit.wikimedia.org:29418/mediawiki/vagrant

# Créez le sous-répertoire mediawiki si il n'existe pas.
cd ~/projects/mediawiki/vagrant
mkdir ~/projects/mediawiki/vagrant/mediawiki

# Copiez le noyau MediaWiki "propre" dans le répertoire "propre" vagrant/mediawiki.
cp -r ~/projects/mediawiki/core/ ~/projects/mediawiki/vagrant/mediawiki

Mise à jour des dépôts clonés

Mettre à jour les dépôts clonées aussi souvent que possible / nécessaire.

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

Recharger Vagrant

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

Quand activer les rôles

Activez les rôles seulement après avoir exécuté avec succès votre premier 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 derrière un proxy

Si vous êtes derrière un proxy, Vagrant pourrait faire apparaître quelques errors. Vous pouvez installer vagrant-proxyconf. C'est un plugin qui permet à votre machine virtuelle d'utiliser les proxy spécifiés. C'est un guide d'installation rapide. Pour une documentation plus détaillée, vous pouvez également regarder here.

Installez le plugin :

vagrant plugin install vagrant-proxyconf

Pour configurer les paramètres de proxy pour tous les logiciels sur tous les ordinateurs virtuels vagrant, ajoutez les lignes suivantes à votre $VAGRANT_HOME/Vagrantfile (par défaut ~/.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

Remplacez les adresses avec l'IP et le numéro de port de votre serveur proxy. Utilisez l'option config.proxy.no_proxy pour sortir la liste de tous les sites/domaines pour lesquels vous pourriez vouloir contourner proxy. Par exemple,

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

Maintenant, lorsque vous exécutez un vagrant up, il ne devrait pas y avoir de messages de mises en garde (warnings).

Pour désactiver le plugin, mettez config.proxy.enabled à false ou à une chaîne vide (""). Vous pouvez également le désactiver pour des applications spécifiques. Par exemple,

config.proxy.enabled         # => Toutes les applications sont activées (par défaut)
config.proxy.enabled = true  # => Toutes les applications sont activées
config.proxy.enabled = { svn: false, docker: false }
                             # => Des applications spécifiques sont activées.
config.proxy.enabled = ""    # => Toutes les applications sont désactivées.
config.proxy.enabled = false # => Toutes les applications sont désactivées.

Préparation de MediaWiki-Vagrant

Vous envisagerez peut-être d'utiliser un script d'interface système (shell) comme mw-vagrant-prep pour préparer un répertoire lors d'une installation de MediaWiki-Vagrant.

Débogage

Provisionnement

Vous pouvez déboguer le processus de provisionnement en exécutant

PUPPET_DEBUG=1 vagrant provision

PHP

Voir Manual:How to debug#HHVM. Mais commencez d'abord de travailler autour de task T94868.

Vous pouvez déboguer PHP avec Xdebug si vous vagrant enable-role zend . Déboguer en PHP est différent des autres type de débogage côté client. Votre IDE écoute pour les connexions entrantes, et lorsque vous accédez au serveur avec un navigateur, un en-tête spécial indique à PHP de se connecter à votre IDE. Voir MediaWiki-Vagrant/Advanced usage#MediaWiki debugging using Xdebug and an IDE in your host pour plus d'informations.

Chrome

  • Pour les utilisateurs de Chrome, vous devriez récupérer XDebug Helper, et éventuellement Clear Cache, HTTP headers, et Mod Headers. Configurez la suppression du cache pour recharger automatiquement après la suppression, et installer les raccourcis clavier (e.g. Ctrl+R pour suppression & rechargement, Ctrl+Shift+D pour activer/désactiver XDebugger)

Firefox

  • Les utilisateurs de Firefox devraient regarder easy Xdebug.
  • Installez et configurez un IDE xdebug-compatible sur votre machine (Eclipse, PhpStorm, Emacs, etc.)
  • Dans l'IDE, commencez par écouter la connexion de débogage entrante.
  • Dans l'IDE, mettez un point d'arrêt à l'endroit qui vous intéresse.
  • Activez XDebug dans le navigateur et accédez à votre installation vagrant (http://127.0.0.1:8080/...)

Fichiers de journalisation (log)

Les fichiers de journalisation (logs) de mediawiki peuvent être trouvés dans /vagrant/logs. Il y a des fichiers de journalisation (log) pour Apache dans /var/log/apache2/, mais il semble qu'il ne soient pas écris. Il y a un fichier de journalisation (log) pour HHVM dans /var/log/hhvm/. Les notifications, les avertissements, les erreurs et les exceptions non traitées de PHP sont enregistrées par HHVM dans le syslog que vous pouvez voir dans /var/log/syslog. Le fichier de journalisation (log) des requêtes MySQL peut être obtenu en saisissant SET GLOBAL general_log = 'ON'; dans un client, puis en regardant dans /var/lib/mysql/*.log.

Fonctionnement et débogage des tests unitaires

Pour "lancer" les tests PHPUnitManual:PHP unit testing :

$ vagrant ssh
$ cd /vagrant/mediawiki
$ sudo -u www-data php tests/phpunit/phpunit.php --wiki wiki

Vous pouvez ajouter "path/to/tests/to/run".

Certains tests peuvent nécessiter d'être exécuter en tant qu'utilisateur approprié pour créer des fichiers de verrouillage, par conséquent cette commande est exécutée comme "utilisateur" www-data qui gère les requêtes Web.

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

Le débogage des tests de phpunit est un petit peu plus compliqué. Cette méthode est un peu "hacky", mais peut être utilisé le temps que l'interpréteur à distance de débogage s'améliore (par exemple dans PHPStorm 8 EAP ). Cette solution de contournement vous permet d'exécuter des tests unitaires MediaWiki depuis le navigateur.

  • Télécharger le fichier phpunit.phar à la racine du répertoire vagrant.
  • Créez un fichier php unittest.php dans la racine du mediawiki. Ne faites pas de "commit" pour ce fichier dans le dépôt. Collez le code suivant dedans :
  • Dans le fichier ci-dessus, changez le paramètre "argv" par le nom de votre fichier de test.
  • Apache mappe la racine du répertoire de mediawiki à /w. Donc, naviguez jusqu'à $URL pour exécuter ce fichier.
  • Suivez les instructions #Debugging pour attacher votre débogueur.

Running browser tests

See here.

"Pousser" des "commit"

Si vous utilisez MediaWiki-Vagrant pour le développement, vous aurez probablement envie de pousser certains "commits" dans le noyau MediaWiki ou dans un dépôt d'extensions à l'aide de git review. Par défaut, toutes les télécommandes pointent vers les URL https://. Pour éviter leur redéfinition au cas par cas, exécutez :

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

Vous devez aussi avoir vos clés ssh dans ~/.ssh.

Comment puis je faire pour ... ?

Vérifiez la version de PHP et les paramètres.
http://127.0.0.1:8080/info.php
Modifier le fichier LocalSettings.php?
Tout d'abord, vérifiez qu'il n'y a pas de rôle (vagrant list-roles) qui fait déjà ce que vous avez besoin. Sinon, créez un fichier dans settings.d/. Voir le fichier README et le fichier d'exemple 00-debug.php.
Mettre à jour le code MediaWiki ?
Le plus simple est d'utiliser vagrant git-update à partir de l'hôte. Ou, pour simplement mettre à jour le code sans les dépendances, vous pouvez utiliser régulièrement les commandes git fetch, pull, etc. dans les répertoires vagrant/mediawiki et vagrant/mediawiki/extensions/"SomeExtension". Vous pouvez exécuter ces commandes sur la machine virtuelle, mais l' accès aux fichiers sera plus rapide sur la machine hôte. MediaWiki-Vagrant tire le code (pull) à partir du "git master" lorsque vous mettez initialement en place et/ou ajoutez un rôle, mais ne met pas automatiquement le code à jour après.
Exécutez l'interpréteur PHP MediaWiki.
Connectez vous en ssh et exécutez mwscript eval.php. Vous pourriez avoir besoin de l'exécuter avec sudo.
Exécutez l'interpréteur SQL MediaWiki
Connectez vous en ssh et exécutez mwscript sql.php. Vous pourriez avoir besoin de l'exécuter avec sudo.
Mettre à jour les paquets logiciels de la machine virtuelle ?
vagrant provision ne met pas à jour les paquets "système" de la machine virtuelle. Lorsque vous vous connectez en ssh via vagrant, le message d'ouverture de session informera que vous :
" NN packages peuvent être mis à jour.
NN mises à jour sont des mises à jour de sécurité. "
Dans "vagrant ssh" :
* Mettre à jour tous les paquets, saisissez sudo apt-get update && sudo apt-get upgrade
* Pour "l'installation automatique des mises à niveau de sécurité (et autres)", semblable à des instances de "laboratoires", entrez sudo unattended-upgrade
* Pour mettre à jour les mêmes paquets qui sont sur ​​les serveurs WMF de production... "TODO"
Personnalisez Vagrant.
Vous ne devriez jamais avoir besoin de changer directement le fichier Vagrantfile. Il y a différents aspects de vagrant que vous pouvez personnaliser :
* Les réglages de base (utilisateur git, ports, ram, ip, redirection de port) peuvent être personnalisés via le fichier .settings.yaml. Voir vagrant config --help et vagrant forward-port --help pour les instructions. So for example you may run vagrant forward-port 1234 80 to enable port forwarding from host:1234 to guest:80.
* Effectuez des étapes supplémentaires après le chargement du fichier Vagrantfile en créant un fichier appelé "Vagrantfile-extra.rb" et en le plaçant dans le même dossier où est situé le fichier Vagrantfile. Il sera chargé automatiquement. En cas de conflit, les valeurs dans le fichier «extra» remplaceront les valeurs de ce fichier. Voir l'exemple dans "support/ directory".
Ajouter du code Puppet personnalisé ?
Ceci est idéal si vous souhaitez travailler sur votre propre site MediaWiki localement et laisser le MediaWiki-Vagrant installer vos dépendances pour vous. C'est idéal si vous avez votre propre "fork". Il y a une distinction entre un rôle et ce cas d'utilisation. Les rôles sont destinés à être installés dans un ordre quelconque et sans rupture. Si votre "fork" a besoin d'appels différents et cause des problèmes avec les rôles, créez votre propre classe et appelez ce que vous avez besoin, y compris les rôles.
Pour ce faire, placez votre code puppet personnalisé dans puppet/modules/local/manifests/myown.pp avec votre propre classe, comme ce qui suit :
class local::myown {
    include ::role::svg
}

Pour appliquer votre classe, ajoutez la dans la clé "classes" dans puppet/hieradata/local.yaml. Vous pouvez créer le fichier s'il n'existe pas.

classes:
  - local::myown

Ensuite, exécutez vagrant provision pour appliquer la modification via Puppet.

Mettre à jour MediaWiki-Vagrant lui-même ?
(Par exemple, pour utiliser de nouveaux rôles.) Dans un terminal, accédez au répertoire vagrant sur l'ordinateur hôte et saisissez une commande standard git comme git pull --ff-only. En général, vous voulez exécuter vagrant provision après la mise à jour pour appliquer les nouveaux changements de puppet à votre machine virtuelle .
Exécuter les applications GUI sur la machine virtuelle ?
Si vous avez un serveur X d'installé, connectez vous en SSH dans la machine virtuelle en utilisant ssh --X pour activer le transfert de X. (Les utilisateurs de Mac devraient Mettre à jour vers la dernière version de XQuartz.)
Comme alternative, vous pouvez exécuter la machine virtuelle en mode graphique, ce qui vous permet d'interagir avec la machine virtuelle comme si elle avait un affichage physique. Pour activer le mode GUI, créez un fichier appelé Vagrantfile-extra.rb dans le dossier racine du dépôt, avec ceci commme contenu :
Vagrant.configure('2') do |config|
    config.vm.provider :virtualbox do |vb|
        vb.gui = true
    end
end
Enregistrez le fichier et lancez vagrant halt suivi de vagrant up. L'affichage de la machine virtuelle apparaîtra dans une fenêtre sur votre bureau.
Ajuster les ressources allouées à la VM ?
Si vous souhaitez allouer plus ou moins de CPU/RAM à la machine virtuelle, voir vagrant config --help

pour les instructions.

Alternativement, vous pouvez le faire en créant Vagrantfile-extra.rb (voir support/ dir pour un exemple) :

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
Changer l'éditeur utilisé pour les messages "git commit" ?
git config --global core.editor "vim"
Définir un nom d'hôte personnalisé ?

Aller à [wikitech:Help:Horizon FAQ Special:NovaProxy], cliquez sur "Ajouter proxy" et entrez un nom d'hôte DNS, par exemple <hostname> Voir votre nouveau wiki à "http://<hostname>/wiki/"

Faire pointer le nom d'hôte personnalisé vers la page d'accueil de mon rôle vagrant au lieu de la page d'accueil wiki ?

Créez un fichier local.yaml dans le répertoire /vagrant/puppet/hieradata. Dans ce dernier, ajouter :

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

Exécutez vagrant provision.

Exécuter une branche de MediaWiki autre que celle du master ?
Configurez la clé "mediawiki::branch" dans puppet/hieradata/local.yaml. Vous pouvez créer le fichier s'il n'existe pas.
mediawiki::branch: "wmf/1.24/wmf18"
Ce changement doit être fait avant l'exécution de vagrant up pour la première fois. Si vous décidez de le faire plus tard, faites le changement, détruisez votre VM actuelle avec vagrant destroy -f, supprimez votre "mediawiki checkout" existant et enfin construisez une nouvelle VM avec vagrant up.
Vagrant est conçu pour fonctionner avec la branche principale, et peut ne pas fonctionner parfaitement, ou pas du tout avec les anciennes versions du noyau et/ou des extensions [3].
Run MediaWiki under HHVM rather than Zend PHP?
  • To convert all wikis in your MediaWiki-Vagrant instance to HHVM: vagrant roles enable hhvm && vagrant provision

Utilisation avancée

Paramètres MediaWiki

Comme une alternative à la gestion de tous les paramètres MediaWiki dans un seul grand fichier LocalSettings.php ,pensez à regrouper vos configurations par composant ou thème, et à la création d'un fichier PHP séparé dans settings.d/ pour chaque groupe. Il est donc assez facile de garder vos paramètres organisés, pour désactiver provisoirement des configurations spécifiques, et pour partager les paramètres avec d'autres.

MediaWiki charge automatiquement tous les fichiers PHP dans settings.d/ dans l'ordre lexical. Vous pouvez contrôler l'ordre dans lequel vos configurations sont définies en ayant l'habitude d'ajouter un préfixe à deux chiffres pour chaque nom de fichier.

Par exemple :

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

Notez que les fichiers de paramètres dans settings.d/puppet-managed sont automatiquement créés et détruits en réponse à votre configuration Puppet. Ne mettez pas vos paramètres personnalisés ici, parce que Puppet va les effacer ou les remplacer. Gardez vos fichiers de paramètres personnalisés dans settings.d/ à la place.

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.

  1. Open puppet/modules/mediawiki/templates/jobrunner.json.erb
  2. Change the value for the 'runners' key from 1 to the desired value (say, 4)
  3. Re-provision with vagrant --provision
  4. 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)

Création des rôles

La machine virtuelle créée par MediaWiki-Vagrant ressemble à l'environnement de production de Wikimedia sur des points clés, et il utilise le même outil —Puppet— que l'équipe des opérations techniques de Wikimedia pour gérer les serveurs de production et des instances Wikimedia Labs. Puppet est un outil de gestion de configuration qui fournit un langage spécifique pour les configurations logicielles s'exprimant sous forme déclarative. Les fichiers contenant le code de Puppet sont appelés « manifestes ». Lorsque Puppet fonctionne, il interprète les manifestes que vous déclarez et configure la machine en conséquence. Un rôle Vagrant est un ensemble de manifestes de Puppet.

Le code de base de Puppet pour MediaWiki-Vagrant contient des abstractions qui le rendent facile pour automatiser la configuration des extensions MediaWiki et des logiciels connexes. Si vous êtes un développeur travaillant sur un projet de logiciel qui se rapporte à MediaWiki, vous êtes encouragés à soumettre un patch avec un rôle de Puppet pour votre projet. L'ajout d'un rôle Vagrant pour votre projet permet aux autres développeurs de facilement vérifier votre travail. L'utilisation d'une machine virtuelle configurée comme un "bac à sable" de développement pour votre projet réduit le risque d'erreurs de type "works-on-my-machine" qui résultent souvent de développeurs géographiquement distants travaillant dans des environnements incompatibles.

La meilleure façon de commencer avec des rôles personnalisés est de regarder comment les rôles existants sont mis en œuvre dans puppet/modules/role/manifests/Template:$1.pp. Ces rôles dépendent de modules de Puppet dans 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/*/Template:$1/ directories. Le code de Puppet est généralement bien documenté et contient des exemples qui démontrent son bon usage.

Some of the more useful puppet modules are:

Installation des instances "Labs"

Vous pouvez utiliser MediaWiki-Vagrant in Labs pour installer MediaWiki sur un Wikimedia Labs instance et activer les rôles MediaWiki-Vagrant dedans.

Bogues

Si vous repérez un bug dans MediaWiki-Vagrant, prenez le temps de nous le signaler. Tout d'abord , assurez-vous que le bug est pas un bug de Vagrant ou VirtualBox connu en recherchant le Vagrant issue tracker on GitHub et le VirtualBox bugtracker. Si ce n'est pas le cas, allez-y et submit the bug to Wikimedia Phabricator. Décrivez clairement le problème et incluez les étapes pour le reproduire chaque fois que c'est possible.

Liens


Remarques

  1. Si vous êtes sur Fedora, ne suivez pas les instructions d'Oracle. Au lieu de cela, activez les dépôts de RPMfusion (par exemple via la configuration de Apper), puis sélectionnez VirtualBox et kmod-VirtualBox pour l'installation (note : C'est sensible à la casse et parfois sensible à la version ! si vous ne trouvez pas le paquet, recherchez dans Apper à la place). Alternatively you can follow this guide. Il est possible que vous puissiez obtenir une erreur à propos de votre noyau qui serait trop récent. Si c'est le cas, installez akmods-VirtualBox, et exécuter akmods sudo pour vous assurer que le module soit compilé.
  2. If you are on Ubuntu 16.04, do not install Vagrant using apt-get. Instead, download it on the Vagrant web site. Using the version from APT will cause setup.sh to fail.
  3. Vagrant dependent on MediaWiki 1.21+