View source for Manual:Running MediaWiki on Windows Subsystem for Linux

<languages/>
{{Installation Guides}}
<translate><!--T:1--> This is documentation for running <tvar name=1>{{ll|MediaWiki}}</tvar> on Windows 10 with the Windows Subsystem for Linux (WSL).</translate>
<translate><!--T:2--> See <tvar name=1>{{ll|Manual:Running MediaWiki on Windows}}</tvar> for documentation on running MediaWiki directly on Windows.</translate>

<translate>
== Background == <!--T:3-->
</translate>
<translate><!--T:16--> Windows 10 includes a Linux compatibility layer, the '''[<tvar name=url>https://docs.microsoft.com/en-us/windows/wsl/about</tvar> Windows Subsystem for Linux]''', designed to help web developers needing a Linux/Unix development environment on a Windows computer.</translate>
<translate><!--T:17--> This can be used to run MediaWiki as if on a Linux machine, with less overhead and better integration compared to setting up and running a virtual machine.</translate>

<translate><!--T:18--> This may be good option for Windows 10 laptops with limited RAM and CPU resources.</translate>
<translate><!--T:19--> However, WSL '''requires''' a 64-bit edition of Windows 10 (x64 or ARM64), and cannot run on 32-bit x86 Windows 10 installations.</translate>

<translate>
=== Security notes === <!--T:4-->
</translate>
<translate><!--T:20--> MediaWiki is a web application, and following these directions will set up a web server that runs on your computer and can be exposed to other computers on the network.</translate>
<translate><!--T:21--> In particular, note that PHP and other Linux code running in the web server may have access to your Windows <code>C:\</code> drive and may be able to read or modify files or run Windows programs.</translate>

<translate><!--T:22--> It is strongly recommended to use this for development purposes only, not for server deployments, and to limit network access to the web server to avoid accidentally opening anything to the network.</translate>
<translate><!--T:23--> Only run MediaWiki and extensions that you trust.</translate>

<translate>
=== WSL versions === <!--T:5-->
</translate>
<translate><!--T:24--> There are two major versions of WSL available: the original which emulates the Linux kernel ABI as a Windows driver, and the newer WSL2 which uses a specialized Hyper-V virtual machine to run a native Linux kernel.</translate>
<translate><!--T:26--> While MediaWiki should work with WSL1, the [<tvar name=url>https://www.microsoft.com/en-us/software-download/windows10</tvar> May 2020 Update] introduces WSL 2 as an alternative.</translate>
<translate><!--T:94--> It is possible to freely upgrade/downgrade from WSL1 and WSL2. </translate>

<translate><!--T:27--> WSL2 is compatible with more software, but can complicate some integration scenarios a little as the VM has its own IP address separate from <tvar name=1><code>localhost</code></tvar>.</translate>
<translate><!--T:28--> (Servers are port-forwarded to <tvar name=1><code>localhost</code></tvar>, so this mostly works ok for setting up a web server.)</translate>

<translate><!--T:29--> Note that WSL2 requires hardware support for virtualization and uses Hyper-V under the hood, but is available on Windows 10 Home as well as Windows 10 Pro.</translate>
<translate><!--T:31--> WSL1 doesn't require virtualization. </translate>
<translate><!--T:30--> This will make it easier for developers to install on existing machines without spending money on a Pro upgrade, but may have compatibility problems with other VM software like VirtualBox (v6.0 is the earliest version that can coexist with Hyper-V based products).</translate>

<translate>
== Setup == <!--T:6-->
</translate>
* <translate><!--T:80--> Go to Control Panel, Programs and Features, then the link on the left side Turn Windows features on or off, or run <tvar name=1><code>C:\Windows\System32\OptionalFeatures.exe</code></tvar>.</translate>
** <translate><!--T:88--> Check "Windows Subsystem for Linux" and, for WSL2, "Virtual Machine Platform"</translate>
** <translate><!--T:89--> let it install and reboot</translate> 
*<translate><!--T:82--> Go to 'Microsoft Store' and search for the latest [<tvar name=url>https://www.microsoft.com/en-gb/search/shop/apps?q=ubuntu</tvar> "Ubuntu" Linux distribution]</translate>
** <translate><!--T:90--> install it!</translate>
** <translate><!--T:91--> Debian is also available, but might be slightly different in some respects.</translate>
*<translate><!--T:76--> Click on the "<tvar name=1>Ubuntu</tvar>" icon in Start menu or enter <tvar name=2><code>wsl</code></tvar> from a <tvar name=3>PowerShell</tvar> session, (notice how the prompt changes from Windows to Linux style).</translate>
** <translate><!--T:92--> follow the on-screen prompts about setting up a Linux username and password</translate>
** <translate><!--T:93--> let it extract</translate>

<translate>
=== WSL Setup === <!--T:7-->

<!--T:87-->
To use WSL2 mode, exit and run in a PowerShell session:
</translate>

*<code>wsl --set-version Ubuntu 2</code>

<translate>
<!--T:33-->
This may take a few minutes to convert filesystems.

<!--T:34-->
To verify which version of WSL is in use do:
</translate>

*<code>wsl -l -v</code>

<translate>
=== Dependency setup === <!--T:8-->
</translate>
<translate><!--T:35--> First, ensure the system image is up to date: run <tvar name=1><code>sudo apt update && sudo apt upgrade -y</code></tvar> in the Ubuntu terminal.</translate>
<translate><!--T:36--> This may take a few minutes after first installation.</translate>

<translate>
<!--T:37-->
Install deps: <tvar name=1><code>sudo apt install apache2 composer git git-review imagemagick mysql-client mysql-server php php-apcu php-cli php-gd php-intl php-mbstring php-mysql php-xml zip</code></tvar></translate>

<translate>
=== Running services === <!--T:9-->

<!--T:57-->
You may have to manually start up services:
</translate>

*<code>sudo service mysql start</code>
*<code>sudo service apache2 start</code>
** <translate><!--T:58--> on WSL1 this may prompt Windows Firewall about the listening port.</translate> <translate><!--T:59--> Allow it, but consider limiting to "private" networks for safety.</translate>

<translate>
<!--T:60-->
You may have to jump through some hoops to set the root password on mysql:
</translate>

*<translate><!--T:61--> Run mysql as root:</translate>
**<code>sudo mysql</code>
*<translate><!--T:62--> In the mysql terminal run:</translate>
** <code>use mysql;</code>
** <code>alter user 'root'@'localhost' identified by '<b>your-password-here</b>';</code> - <translate><!--T:63--> If that fails try <tvar name=1><code>update user set authentication_string=password('<b>your-password-here</b>'), plugin='mysql_native_password' where user='root';</code></tvar> instead.</translate>
** <code>create user 'your_name'@'localhost' identified by '<b>your-password-here</b>';</code>
** <code>create database 'database_name';</code> - <translate><!--T:64--> This must match with the wiki database in the install process</translate>
** <code>grant all on 'database_name'.* to 'your_name'@'localhost';</code>
** <code>flush privileges;</code>
** <code>exit</code>
* <translate><!--T:65--> Now you can use username 'root', password 'your-password-here' when logging in from the installer</translate>

<translate>
=== MediaWiki setup === <!--T:10-->

<!--T:66-->
[[<tvar name=1>Special:MyLanguage/Download from Git</tvar>|Clone things from git]] as you would on a Linux server.
</translate>

<translate><!--T:67--> Apache on Ubuntu is set by default to point at <tvar name=1><code>/var/www/html</code></tvar> for the docroot, you can create a dir under there to check out or reconfigure Apache with a custom path.</translate>
<translate><!--T:68--> I recommend <tvar name=1><code>/var/www/html/w</code></tvar> for consistency with convention that <tvar name=2><code>/w/index.php</code></tvar> is the main script path.</translate>

* <code>cd /var/www/html</code>
* <code>sudo mkdir w</code>
* <code>sudo chown '''your-user-name''' w</code>
* <code>cd w</code>
* <code>git clone https://gerrit.wikimedia.org/r/mediawiki/core.git .</code> - <translate><!--T:69--> Don't miss the dot at the end.</translate>
* <code>cd skins</code>
* <code>git clone https://gerrit.wikimedia.org/r/mediawiki/skins/Vector.git</code>

<translate>
==== Extensions ==== <!--T:11-->

<!--T:47-->
For example (from <tvar name=1>skins/</tvar>):
</translate>

* <code>cd ../extensions</code>
* <code>git clone https://github.com/wikimedia/mediawiki-extensions-CollapsibleVector</code>
* <code>git clone https://github.com/wikimedia/mediawiki-extensions-Gadgets</code>
* <code>git clone https://github.com/wikimedia/mediawiki-extensions-ParserFunctions</code>
* <code>git clone https://github.com/wikimedia/mediawiki-extensions-Scribunto</code>
* <code>git clone https://github.com/wikimedia/mediawiki-extensions-WikiEditor</code>

<translate>
<!--T:48-->
Don't forget to run <tvar name=1><code>composer update --no-dev</code></tvar> in the MW directory, and for any extension dirs that require it.

<!--T:49-->
Run the web installer in a browser at <tvar name=url><code><nowiki>http://localhost/w/</nowiki></code></tvar>; use your name and database here for installation.

<!--T:50-->
When the installer prompts you to download <tvar name=1><code>LocalSettings.php</code></tvar> at the end, save it into <tvar name=2><code>\\wsl$\Ubuntu\var\www\html\w</code></tvar> or equivalent and you will be able to access your wiki!

=== Job queue === <!--T:12-->

<!--T:38-->
You may want or need to manually run the [[<tvar name=1>Special:MyLanguage/Manual:Job queue</tvar>|job queue runner]].</translate> <translate><!--T:39--> Ideally this should be done via the web server, but in a pinch you can fire up the Ubuntu terminal and run:</translate>

* <code>cd /var/www/html/</code>
* <code>php maintenance/runJobs.php</code>

<translate>
== Other configuration == <!--T:13-->
</translate>
<translate><!--T:40--> For the most part the WSL environment will look like any other Ubuntu or Debian system, except that services won't automatically start and must be manually run on every boot.</translate>
<translate><!--T:41--> See [[<tvar name=1>Special:MyLanguage/Manual:Running MediaWiki on Debian or Ubuntu</tvar>|Running MediaWiki on Debian or Ubuntu]] for general instructions on running on these operation systems.</translate>

<translate>
== Editing files == <!--T:14-->

<!--T:42-->
From the Windows side you can access Linux files in <tvar name=1><code>\\wsl$\Ubuntu</code></tvar>, so Windows text editors that are ok with Unix line endings can be used to work with your code and config.

<!--T:43-->
[<tvar name=url1>https://code.visualstudio.com/</tvar> Visual Studio Code] also has a [<tvar name=url2>https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl</tvar> WSL remoting extension] which can integrate more directly with the WSL environment, which might be good for using PHP linting in the editor.

<!--T:44-->
However note the warnings at [<tvar name=url>https://devblogs.microsoft.com/commandline/do-not-change-linux-files-using-windows-apps-and-tools/</tvar> Do not change Linux files using Windows apps and tools]

<!--T:45-->
Or, you can use your favorite terminal-based editors.
</translate>

[[Category:Installation{{#translation:}}]]