Developers can use this to test their local version of Codex with
MediaWiki by pointing $wgCodexDevelopmentDir to their local clone of the
Codex repo, e.g. $wgCodexDevelopmentDir = '/home/yourname/git/codex';
Setting $wgCodexDevelopmentDir affects where the following things come
from:
- Codex JS/CSS files for the full library
- Codex JS/CSS files for code-split chunks, and the manifest.json file
that points to them
- Icons retrieved by CodexModule::getIcons()
- CSS-only icons imported in Less
- Design tokens imported in Less
Other changes in this patch:
- Add CodexModule::makeFilePath() to centralize the repeated path
concatenation. This makes it easier to switch out the regular path for
the dev mode path.
- Replace all uses of $IP (which is deprecated) and MW_INSTALL_PATH in
CodexModule with the BaseDirectory config setting.
- Make CodexModule::getIcons() reset its static cache if the path to the
icons file changes. Without this, it's impossible to make the unit
tests pass.
- Move the i18n messages code from the CodexModule constructor to
getMessages(). It can't be in the constructor because makeFilePath()
doesn't work there (it fails because the Config object hasn't been set
up yet).
- Add a 'mediawiki.skin.codex' import path so that we can stop
hard-coding the path to the Codex mixins file. Without this, we can't
make the Codex mixins come from the right place in development mode.
- Consider $wgCodexDevelopmentDir in setting the cache key for compiled
Less code, since changing this setting can change the output of Less
compilation (by changing design tokens, icons or mixins).
- Add unit tests for (the non-dev mode behavior of)
CodexModule::getIcons() and the i18n message key handling.
Bug: T314507
Change-Id: I11c6a81a1ba34fe10f4b1c98bf76f0db40c1ce98
Follows-up 6ba8efd0a7 (I0f42a2a52f), which removed it from the actual
docker-compose.yaml file.
Bug: T364815
Change-Id: Iceab6a2b0cca54296cd732d9132df0b6109fd12d
Add a note to disable the use of Rosetta if the user
encounters a 503 error.
https://phabricator.wikimedia.org/P49617
Change-Id: I8257b3767ab92d4b4ebc1201e712fe00b735bdab
* Changed the example to talk about an extension (EventLogging) rather
than a skin.
* Fixed some wording to make sentences make more sense.
Change-Id: I96a49422d4d7dbd14d4bb392dcb78a07a906506f
This is mentioned at the very bottom of the document, but I think it
is also worth a mention higher up.
Bug: T341310
Change-Id: I39d44b54715ac7895405ede7c964f1b057702585
Mention the first bullet of
https://www.mediawiki.org/wiki/MediaWiki-Docker in DEVELOPERS.md. The
idea is to get all steps into DEVELOPERS.md, even obvious steps. More
beginner friendly.
Bug: T341310
Change-Id: Id169594b30cfaa572b1fa3cb0cf30af6c67c8f6b
MW_DOCKER_UID= and MW_DOCKER_GID= need to be set to blank to avoid
warnings about undeclared variables from appearing in bash.
The extra line break at the end of line 63 is intentional. If a
Windows user copy pastes the text on lines 50-57 into a file named
.env, it may not end in a line break.
Bug: T341309
Change-Id: I9ca94f7e5afc3514d9fd4c587112b287478d7ece
The script should never be used directly, to allow an easier migration
to vendor/bin/phpunit.
Bug: T90875
Change-Id: I8d0c4c3a9007d50f39a6bef37a0db62fe83de4d7
When using the command that this commit changes, the console
would give a warning that that way of using update.php is
deprecated since 1.40, and that one should use maintenance/run.php
instead.
Follows up Ibd47e3f29f93238ccd3e607774927e639ba74ace
and I2cd89a6a9218dadb1bc6088d1c7e1f2c85642902.
Change-Id: Id4bdd7fb0f505d119f8cac574889b06012d5c22a
DEVELOPERS.md states that the user should run a command to add their
user and group id to the .env file when setting up a Docker environment.
The command does not work or is required in Windows.
Change-Id: I4ff8806fcccd925ff7a3945ac605bb5c854dbbee
* `docker-compose` is now deprecated for all OS, replace
commands with `docker compose`
* `docker-engine`, `docker` packages are now deprecated for linux, remove
references and replace with correct package names.
* Installing by repo is now much more mature, I don't think it makes
sense to preference binaries now - but I've added a direct link to the
binaries for those that prefer it, as the current link doesn't go there
directly anymore.
Change-Id: I64d93fb0f47d31b3a1178521e63b1c9f9b9628a8
It's all great that it's up and running, but how does one stop the
containers when you're done with it and want/need to reduce load on
the computer, or re-create them after something went wrong?
Change-Id: I9ec446d73a5fac41550c19eb83912469cfdb92ee
The overall theme of this patch is to reduce cognitive overhead,
and increase confidence and familiarity for new developers.
== Intro
* Fix phab link, which pointed to an unrelated Docker-Hub tag.
* Simplify requirements to "Docker Desktop" for macOS/Windows,
as that already includes docker-compose.
* Add link to webchat.
* Docker "Development" isn't a relevant noun, drop cap.
* Phabricator `#mediawiki-docker` felt obscure and internal.
Rephrase without the obscure comment syntax hashtag, and indicate
that it is about creating tasks (not another chatroom).
The term "task" will come in handy once on the other side.
* Re-balance paragraph boundaries.
== Quickstart
* Number sections.
This suggests more clearly that each section is needed and in order
(not a recipe menu, like the other sections). Also offers a sense of
progress and makes it easier to remember where you are.
* Move "Requirements" into Quickstart as step 1.
* Explain what certain steps are for.
Especially steps that are not important or useful to most. For
example, Linux users creating an override file, is only relevant for
people that will 1) contribute in PHP, 2) and have an elaborate IDE,
3) and want to specifically use the "breakpoint" feature of Xdebug.
* Add missing "Done" indication. There was no indication that one
is done with the installation or what to expect where/when.
== Usage
* Flatten sections.
* Demonstrate PHPUnit using bash.
The common case for install commands is to do them once, and have
no desire to understand how they work. The common case for tests,
is to run them a lot, run variations on them, inspect results, maybe
benefit from tab completion on paths, run a maintenance script, etc.
Using the wrapped commands gives people a slow experience with no
path to learn or discover the surrounding abilities. Encourage
curiousity and graduation to other things in the shell, by starting
there from the get go. This makes other commands less complicated
and should allow for much on-wiki documentation to be applicable
in a straight-forward manner without needing to know the
"mediawiki docker version" of any such command.
== Modify the environment
* Start the extension how-to with a recommendation to follow the
existing install instructions of any extension on mediawiki.org.
This should avoid surprises since for many extensions the two steps
given here will not suffice, and will cause confusion, and it's
probably better if we don't aim to cover them all here inline.
* Trade brevity for practical and interoperable advice.
Instead of using a clever git-clone command with destination
override, use the plain one that people would see and copy from
elsewhere such as mediawiki.org or Gerrit, etc, and execute it from
the relevant subdirectory. Otherwise they'd have to modify two
parts of the command and thus need the "mediawiki docker version"
of every extension install command.
Instead of clever `echo >>` append commands, state to add it to
the LocalSettings.php file. It's not as brief, but I think making
this not a scary file from the get-go is going to pay off in the
long term, especially because you then also likely know how to
disable it again (by removing it from where you added it), instead
of expecting Linux knowledge and abstraction of these shell concepts.
* Add example of how to install an extension.
* De-emphasize obscure need to mount extensions from another directory.
This shouldn't be something we recommend to people out of the blue
as two normal ways to install an extension. Rather, the amount is a
solution to a pre-existing problem the person may have. Explain what
that problem is and offer it in that context. If people do this as
just another option, it's going to cause a lot more problems down
the road.
== Troubleshooting
De-emphasize caching workaround to the Troubleshooting section, and set
clear expectations about its impact on speed. Thiis is a debugging
mechanism for when caching has broken down. It should not be needed,
and for the past 11 years I have not at any point done anything like
this other than when directly working on the low-level caching
mechanisms themselves, which is a pretty rare thing to do.
There are many aggressive caching features in MW, which the linked
manual page on mediawiki.org explains how to enable, because they are
not enabled by default. The ones enabled by default are mild, and
(perhaps by accident) happen to be well-suited for the use case of
local development, as they have automatic propagation of changes.
Change-Id: I40750c694a75948824a8a35f657747ffec42a704
Injecting it does nothing other than break the wiki with 404 errors.
The only thing that uses it is the install.sh script, which then
one-time substitutes it in LocalSettings.php.
It isn't used by the mount logic for /var/www/w, and it isn't used
by the Apache config in the referenced Docker images either.
While the injection is removed, I have kept the following two:
1. It is still set for the docker images so that the env variable
can still be read, to allow new additions to the dev images to
not have to hardcode it, and to perhaps one day actually support
this. It seems useful to retain as abstraction layer from that
perspective.
2. It is still part of the recommended `.env` file. For the same reason
as the previous point, but not theoretical. Our test tools (Selenium,
QUnit, fresh-node, etc.) all expect this env variable for discovery
and those tools are not specific to MediaWiki-Docker so they need
this indeed.
After this change, there remains one weak link, which is someone
copying the recommended .env file and then deciding to change
MW_SCRIPT_PATH for some reason. What will happen is that the wiki
continues to work and identify with "/w", and the only impact is
that external tooling will look for their custom path, and not find
a wiki there.
Bug: T273529
Change-Id: I4aa71f8994810ea0fbe2950958097c223c88916c
The default caching is so aggressive that the unbeknownst developer is
going to be baffled why changes they make don't seem to have any effect.
We should offer a common configuration for development so they can get
to developing more quickly.
Change-Id: I5a73e3e3608edd4d514a0502df7f4631afd55fd8
* Removes no-longer needed docker-compose.override.yml directions.
* Updates directions for skins/extensions to indicate the
skin/extension must be in the core directory or mounted as a volume.
Bug: T288456
Change-Id: I0053b44f88b434649b72e9e386331a34b46fa981
Apparently Docker for Mac (I assume also Docker for Windows) has changed
and we now need to set the host user/group mapping to avoid permissions
problems in the running container. As a result, we don't need to make
Linux users create an override file anymore.
Also, update the docker-compose.yml to reference the `.env` file,
apparently this explicit reference is required for those values to be read.
Bug: T273218
Change-Id: Iaadce5d27d6e973ad02afd5b069646e95b5de0aa
Adds a mediawiki-web service running Apache, and changes mediawiki
service to run only PHP-FPM. Assumes users will continue to run CLI PHP
in the mediawiki container.
Passes MEDIAWIKI_USER and MEDIAWIKI_PASSWORD into the PHP container
as MW_USER and MW_PASS respectively. (The difference should be
reconciled in a future patch.) Also passes in MW_SCRIPT_PATH if set.
There's still some weirdness here in that MW_SERVER, if set in the .env,
isn't used, though MW_PORT is.
Adds instructions for XDebug 3.x, clarifies some documentation around
environment variables and Xdebug use.
See https://gerrit.wikimedia.org/r/c/releng/dev-images/+/622575
for more context.
Bug: T245444
Depends-On: I67ed53c4bd8e92a4c506da4aa7ffee79ca2910bb
Depends-On: Iab57d34b2012eb9e0271a7d4ec02053f984ccf86
Change-Id: I0cfef6f05a9237f310a85942ee881536288131ae
Updates docker-compose.yml to run stretch-php72-fpm-apache2-xdebug:0.3.0, which
will contain a /docker/install.sh. Usage is described in DEVELOPERS.md.
Depends-On: Icf7dd0e22e0421cf97de1d7c1d4a44ca14f2190a
Bug: T246953
Change-Id: Ib7e6e9b872c284583db3a5e83b310183343b4341
- allows for cleanly overriding host exposed port
- easier to override XDebug settings
- easier setup for Linux hosts
When wikimedia/fresh is updated with https://github.com/wikimedia/fresh/pull/18,
we can simplify the Selenium / API testing instructions too (removing the
`export` statements).
Bug: T246586
Bug: T246588
Change-Id: Ibd266411636ac144789617bb0999c33a83e9e652
This has come up a few times already with users (T248624#6008494,
T246827#5944100) so it would be useful to document the solution here.
Change-Id: I7c2fa16fd3f129e03c053935f32ebda3b589b9fe
Removed an extra character preventing the "Fresh" links from being resolved
on Github mirrors
Bug: T246957
Change-Id: I029d819052c0977dfc45f4566f0179f8969e5649
As noted in the task, UID is a read-only variable by default in Bash. Rather
than rely on it existing let's explicitly define MW_DOCKER_(UID/GID) for use
with docker-compose.override.yml.
Bug: T246020
Change-Id: I768486858bc63393f35c3b89fb783c3845183da5
This patch introduces a simple docker-compose based development environment
with the idea to allow most development use cases for beginning and
experienced MediaWiki developers.
- PHP and Apache container with XDebug enabled
- Support for overriding services with docker-compose override file
- Documentation for usage and a documented place for sharing docker-compose
overrides and LocalSettings.php configuration snippets for e.g. MySQL,
DB replication, Redis, etc
Depends-On: I50079cca6a286d8aaea8fd0785be48c80e80271c
Bug: T238224
Change-Id: I3b76c1599b1ff32174af5603aadc9f7c7634c98b
