MediaWiki-Docker/Extension/WikiLambda
You should generally follow the WikiLambda-specific instructions in the repo rather than this. |
This page instructs you to install Extension:WikiLambda inside MediaWiki-Docker.
Follow the Quickstart instructions at MediaWiki-Docker page. Once MediaWiki is running and available at http://localhost:8080
, then continue with instructions on this page.
All commands should be run in the directory where you installed MediaWiki. All mentioned files are also located there.
Clone the repository and its sub-module, and its dependencies
[edit]git clone "https://gerrit.wikimedia.org/r/mediawiki/skins/Vector" skins/Vector
git clone --recurse-submodules --remote-submodules https://gerrit.wikimedia.org/r/mediawiki/extensions/WikiLambda extensions/WikiLambda
git clone "https://gerrit.wikimedia.org/r/mediawiki/extensions/WikimediaMessages" extensions/WikimediaMessages
git clone "https://gerrit.wikimedia.org/r/mediawiki/extensions/EventLogging" extensions/EventLogging
Though you can use HTTPS authentication with Gerrit, using an SSH key is recommended. Follow these instructions to do so.
Add our composer dependencies
[edit]
Extend MediaWiki's composer dependencies to use ours by adding a composer.local.json
file in your mediawiki/
directory with the following:
{
"extra": {
"merge-plugin": {
"include": [
"extensions/WikiLambda/composer.json"
]
}
}
}
… and then run:
docker compose exec mediawiki composer update
Modify LocalSettings.php
[edit]If not already there, add this to the end of LocalSettings.php
.
$wgDefaultSkin = "vector-2022";
wfLoadSkin( 'Vector' );
wfLoadExtension( 'WikiLambda' );
wfLoadExtension( 'WikimediaMessages' );
wfLoadExtension( 'EventLogging' );
$wgEventLoggingBaseUri = '/beacon/event';
$wgEventLoggingServiceUri = '/beacon/intake-analytics';
$wgEventLoggingStreamNames = false;
The last three lines above provide a minimal EventLogging
configuration. If and when you need to monitor or debug WikiLambda event logging in your development environment, refer to MediaWiki-Docker/Configuration_recipes/EventLogging for additional configuration options. (Follow the instructions on that page, including the Metrics Platform section, but omitting the Minimal setup, Legacy EventLogging and Event Platform with Local Schema Repositories sections.) Note that WikiLambda employs Metrics Platform libraries, which are included in the EventLogging
extension.
Run maintenance scripts
[edit]Give your Admin user the special rights for creating and editing ZObjects.
docker compose exec mediawiki php maintenance/run.php createAndPromote --custom-groups functioneer,functionmaintainer --force Admin
Setup the database schemas and insert the initial content (this step could take around 20 minutes):
docker compose exec mediawiki php maintenance/run.php update
Check that MediaWiki side is installed correctly
[edit]You can check whether this worked by navigating to http://localhost:8080/wiki/Special:CreateZObject
, or to http://localhost:8080/wiki/Special:ApiSandbox
and looking for wikilambda_fetch
in the action
dropdown. If they are there, all is well.
Setting up the back-end services
[edit]WikiLambda uses two back-end services for running user-defined and built-in functions in a secure, scalable environment; an "evaluator" that runs user-defined native code, and an "orchestrator" that receives execution requests and determines what to run.
On install, the extension will try to use the orchestrator and evaluator services of the Beta Cluster version of Wikifunctions. This default configuration will let you do rudimentary tests with the built-in objects, but not with custom on-wiki content (as they are pointed at the content of Beta Wikifunctions).
To add the orchestrator and executor back-end services, first copy the contents of the services
block in WikiLambda's docker-compose.sample.yml
file to the analogous `services` block in your mediawiki/docker-compose.override.yml
file, including the environment
part. Replace the <TAG>
entries in the stanza you just copied with the latest builds from the Docker registry for the orchestrator and the evaluator.
You can automatically test your installation by running the ApiFunctionCallTest.php
PHPUnit test suite by using the following command (or as described in the MediaWiki install instructions if your setup is unusual):
docker compose exec mediawiki php tests/phpunit/phpunit.php extensions/WikiLambda/tests/phpunit/integration/API/ApiFunctionCallTest.php
You can manually evaluate a function call by navigating to http://localhost:8080/wiki/Special:EvaluateFunctionCall
, selecting a function from the wiki, and choosing your inputs. If successful, the function response will be presented, having traversed the orchestrator and the evaluator to be run in one of the code executors.
You can also visit http://localhost:8080/wiki/Special:ApiSandbox and try out one or more tests as follows:
- In the
action
drop-down menu, selectwikilambda_function_call
- Switch from the
main
to theaction=wikilambda_function_call
section on the left sidebar - Click on {} Examples, and select any of the listed examples
- Click the blue
Make request
button - In the Results box, look for the word "success".
🎉 Congratulations! 🎉
Special configurations
[edit]Having the services with different configuration
[edit]If you wish to use the orchestrator under a different name or port, you must over-ride the $wgWikiLambdaOrchestratorLocation
configuration value from its default (as set in extension.json
). To override the orchestrator location variable, you should add in your LocalSettings.php
file:
$wgWikiLambdaOrchestratorLocation = '<orchestrator_container_name>:6254';
If you wish to use the evaluator under a different name or port, you must change the docker compose environmental variable FUNCTION_EVALUATOR_URL
environmental configuration value from its default which you copied from docker-compose.sample.yml
. To override the evaluator location environmental variables, you should change in your docker-compose.override.yml
file:
FUNCTION_EVALUATOR_URL: "http://<evaluator_container_name>:6927/1/v1/evaluate/"
You can find out the exact container names by going to your MediaWiki installation directory and running docker compose ps
.
Note that if your checkout of MediaWiki is not in a directory called 'mediawiki
' you will need to set both of these, and also WIKI_API_URL
.
Building local versions of the services
[edit]If you would instead like to use a local version of the function orchestrator or evaluator, e.g. because you wish to make local development changes and test them, there are three steps:
- The compose command is now included in the docker CLI via docker-compose-plugin. If you are using docker-compose instead (now deprecated), ensure that you are using version 2.x or above (i.e., not 1.x). (If you have 1.x, you will need to upgrade, or, if using Docker Dashboard, you may be able to select a preference for "Use Composer v2".)
- Clone the service you wish to alter:
- (For the orchestrator):
git clone --recurse-submodules --remote-submodules git@gitlab.wikimedia.org:repos/abstract-wiki/wikifunctions/function-orchestrator.git function-orchestrator
- (For the evaluator):
git clone --recurse-submodules --remote-submodules git@gitlab.wikimedia.org:repos/abstract-wiki/wikifunctions/function-evaluator.git function-evaluator
- (For the orchestrator):
- From the root of the service you wish to alter, run either:
- (For the orchestrator):
DOCKER_BUILDKIT=1 docker build -f .pipeline/blubber.yaml --target development -t local-orchestrator .
- (For the evaluator):
DOCKER_BUILDKIT=1 docker build -f .pipeline/blubber.yaml --target development-omnibus -t local-evaluator .
- (For the orchestrator):
- Then update your
mediawiki/docker-compose.override.yml
file to change the service stanza to point to your new local image, withimage: local-orchestrator:latest
orimage: local-evaluator:latest
.