User:Novem Linguae/Essays/Docker tutorial for Windows (no WSL)

Written from a Windows and VS Code perspective.

Some pessimistic advice
Expect to spend more time setting up your dev environment/toolchain than you do coding, until you've got it set up perfectly on all your computers, and you've mastered the ins and out of this work instruction. Can take months to become fluent. MediaWiki has a complicated toolchain.

Docker
Docker is a fancy XAMPP. It lets whatever codebase you're working on pick what OS, what version of PHP/Python/Node, what database, etc. to use instead of depending on whatever version of XAMPP you happened to install. Then it automates the installation of everything for you.

If you try to use PHP 8.1 with a repo that is using a bunch of PHP 7.4 dependencies, for example, you may not be able to get a dev environment up and running, even if you do  instead of. You'll get a bunch of errors. You'd be forced to uninstall XAMPP 8.1 and install XAMPP 7.4, which is a pain. Maybe you need XAMPP 8.1 for your other project, so would have to do this all over again when switching projects. Docker automates all this.

How to set up Mediawiki Docker for Windows

 * install Docker Desktop for Windows
 * - replace "novemlinguae" with your Gerrit username
 * follow the official instructions at https://github.com/wikimedia/mediawiki/blob/master/DEVELOPERS.md
 * create .env file with default settings
 * - does initial configuration and database creation. assumes sqlite. if you already have a LocalSettings.php file and want to install mariadb, see below.
 * VERY IMPORTANT FOR WINDOWS USERS:
 * foreach (skin/extension):
 * - replace "novemlinguae" with your Gerrit username, and replace "PageTriage" with the extension name
 * add,   , or similar to LocalSettings.php
 * - does database updates for skins and extensions
 * - replace "novemlinguae" with your Gerrit username, and replace "PageTriage" with the extension name
 * add,   , or similar to LocalSettings.php
 * - does database updates for skins and extensions
 * add,   , or similar to LocalSettings.php
 * - does database updates for skins and extensions

PHP step debugging: XDebug
Always run XDebug from the /mediawiki/ directory, not from an extension directory. According to the documentation, this is mandatory.

Add this to your .env file:

Replace your launch.json with this (may be optional, default config might work, maybe someday I'll test this):

JavaScript step debugging: Google Chrome devtools

 * TODO: see if I can get this working in VS Code instead
 * If you're having trouble setting a breakpoint (for example, the code you need is minified by ResourceLoader), add  to your code.

VS Code

 * If you're working on a MediaWiki extension or skin, open two windows: one for MediaWiki core, and one for the extension you're working on.
 * Run your step debugger in the MediaWiki core window (including setting breakpoints)
 * Do your coding work in the extension window. This will give you "search within repo", git, etc.
 * Add this to your extension, in a file called, so that MediaWiki core's libraries get imported and detected by PHP IntelliSense:

Running tests
Add this to your .env file to get PHPUnit to stop outputting detailed debugging (recommended, else your unit test output is really noisy):
 * how to run an extension's PHP unit tests
 * - all
 * - tests in the /unit/ subfolder only
 * - tests in the /integration/ subfolder only
 * - an extension's tests only
 * - a specific test file only
 * how to run an extension's Jest tests
 * how to run an extension's QUnit tests
 * how to run an extension's Selenium tests
 * how to run an extension's Selenium tests
 * how to run an extension's Selenium tests

SQL database

 * how to install the database if you already have a LocalSettings.php file with correct database connection info, and a created database
 * harder than it should be. I've created a ticket. But in the meantime...
 * go into HeidiSQL, delete all the tables
 * rename your LocalSettings.php file to something else
 * re-run, with all the correct CLI parameters
 * delete LocalSettings.php
 * rename your old LocalSettings.php back to LocalSettings.php
 * how to update the database (installs SQL tables for extensions)
 * how to drop all tables on a MariaDB
 * install HeidiSQL
 * drop the tables
 * drop the tables

SQLite or MariaDB?

 * SQLite is the default. Pros and cons:
 * Pro - Keep your localhost database synced between computers, e.g. desktop and laptop, because the database is stored in the docker container in the /cache/ directory.
 * Pro - Easily clear the database by simply deleting the /cache/ directory.
 * Pro - Easy to set up a database viewer and editor, since you just need to point it to /cache/sqlite/my_wiki.sqlite
 * Con - Causes integration tests to fail for certain extensions such as PageTriage, likely due to atomicity issues.
 * Con - Different than Wikimedia production, which uses MariaDB
 * MariaDB is an alternative. How to set it up:
 * MediaWiki-Docker/Configuration recipes/Alternative databases
 * follow this exactly. don't forget both the docker-compose.override.yml step and the maintenance/install.php step (copy pasting their custom string)
 * re-run

Viewing and modifying the database: HeidiSQL

 * to view/edit the SQL database, install HeidiSQL (download page)
 * sqlite
 * point HeidiSQL at mediawiki/cache/sqlite
 * mariadb
 * make sure your docker-compose/override.yml file has the following:
 * configure HeidiSQL with hostname = localhost, username = my_username, password = my_password, database = my_database

Miscellaneous

 * File sizes
 * MediaWiki + skin + extension files is around 1.1 GB
 * Docker files are around ?? GB
 * how to remote into Docker so that you don't have to add  to the start of every command, and so that you can   around more easily
 * how to run an extension's maintenance script
 * restarts
 * any changes to the .env file require a restart of the Docker container:
 * restarts
 * any changes to the .env file require a restart of the Docker container:
 * any changes to the .env file require a restart of the Docker container:

Troubleshooting

 * Container mediawiki-mariadb-1: Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:3306 -> 0.0.0.0:0: listen tcp 0.0.0.0:3306: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.
 * Are you also running XAMPP? Close XAMPP, then go into Task Manager and terminate mysqld.exe.
 * error during connect: This error may indicate that the docker daemon is not running.: Get " http://%2F%2F.%2Fpipe%2Fdocker_engine/v1.24/containers/json?all=1&filters=%7B%22label%22%3A%7B%22com.docker.compose.project%3Dmediawiki%22%3Atrue%7D%7D&limit=0 ": open //./pipe/docker_engine: The system cannot find the file specified.
 * Start Docker Desktop, then try your CLI command again.