Manual:Running MediaWiki on Windows Subsystem for Linux

''This is provisional documentation for running MediaWiki on Windows 10 with the Windows Subsystem for Linux (WSL). See Manual:Running MediaWiki on Windows for existing documentation on running MediaWiki directly on Windows.''

Background
Windows 10 includes a Linux compatibility layer, the Windows Subsystem for Linux, designed to help web developers needing a Linux/Unix development environment on a Windows computer. 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.

This may make it a good option for Windows 10 laptops with limited RAM and CPU resources. However, WSL requires a 64-bit edition of Windows 10 (x64 or ARM64), and cannot run on 32-bit x86 Windows 10 installations.

WSL versions
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. WSL2 is currently available only in Windows Insider Preview builds, but the original version 1 WSL is available in current releases.

WSL2 is compatible with more software, but currently complicates integration a little as the VM has its own IP address separate from.

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. 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. WSL1 doesn't require virtualization.

WSL Setup

 * Go to 'turn Windows features on and off' from the Start menu search
 * Check "Windows Subsystem for Linux" and, for WSL2, "Virtual Machine Platform"
 * let it install and reboot
 * Go to 'Microsoft Store' and search for the "Ubuntu" Linux distribution
 * install it!
 * Click on the "Ubuntu" icon in Start menu or run  from a cmd shell
 * follow the on-screen prompts about setting up a Linux username and password
 * let it extract

To use WSL2 mode, exit and run in a cmd shell:

This may take a few minutes to convert filesystems.

Debian is also available, but hasn't been tested with these directions yet.

Dependency setup
todo: make sure this is complete

First, ensure the system image is up to date: run  in the Ubuntu terminal. This may take a few minutes after first installation.

Install deps:

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

Running services
You may have to manually start up services:
 * on WSL1 this may prompt Windows Firewall about the listening port. Allow it.
 * on WSL1 this may prompt Windows Firewall about the listening port. Allow it.

You may have to jump through some hoops to set the root password on mysql:


 * Run mysql as root:
 * In the mysql terminal run:
 * Now you can use username 'root', password 'your-password-here' when logging in from the installer
 * Now you can use username 'root', password 'your-password-here' when logging in from the installer
 * Now you can use username 'root', password 'your-password-here' when logging in from the installer
 * Now you can use username 'root', password 'your-password-here' when logging in from the installer
 * Now you can use username 'root', password 'your-password-here' when logging in from the installer
 * Now you can use username 'root', password 'your-password-here' when logging in from the installer

MediaWiki setup
Clone things from git as you would on a Linux server.

Apache on Ubuntu is set by default to point at  for the docroot, you can create a dir under there to check out or reconfigure Apache with a custom path. I recommend  for consistency with convention.



If git has trouble checking out over https, use a ssh developer login. Set up your SSH key in gerrit as with a Linux system, and check out as:

Don't forget to run  in the MW directory, and for any extension dirs that require it.

You should be able to run the web installer in a browser, but on WSL2 you'll need to find the IP address to use to point to: run   in the Ubuntu terminal to find it.

When the installer prompts you to download  at the end, save it into   or equivalent and you should be able to access your wiki!

Editing files
From the Windows side you can access Linux files in, so Windows text editors that are ok with Unix line endings can be used to work with your code and config.

Visual Studio Code also has a WSL remoting extension which can integrate more directly with the WSL environment, which might be good for using PHP linting in the editor.

Or, you can use your favorite terminal-based editors.

Open issues

 * best way to set up job queue runner?
 * automate service setup?
 * WSL1 vs WSL2 differences?
 * is the process timeout issue in TimedMediaHandler a common prob or unique to ARM64?