MediaWiki-Docker/Extension/SyntaxHighlight

Download the SyntaxHighlight extension into extensions/ and enable it the usual way in LocalSettings.php:

wfLoadExtension( 'SyntaxHighlight_GeSHi' );

SyntaxHighlight shells out to a Python script to perform the actual syntax highlighting work. You can configure your development environment so that this is done directly in your MediaWiki container, or you can use Shellbox instead to isolate the shell exec process from your MediaWiki runtime. Both methods require additional configuration beyond the wfLoadExtension( 'SyntaxHighlight_GeSHi' ) call.

You will need to customize the base MediaWiki image as described in MediaWiki-Docker/Configuration recipes/Customize base image to install the python3 package, which is relied upon by the extension to perform the syntax highlighting.

In the MediaWiki root directory, create a file called python3.dockerfile, with the following contents:

FROMdocker-registry.wikimedia.org/dev/bookworm-php83-fpm:1.0.0
RUNapt-getupdate&&apt-getinstall-ypython3

Then update docker-compose.override.yml to use this dockerfile when building the image for the mediawiki service:

services:
mediawiki:
build:
context:.
dockerfile:python3.dockerfile

Finally, rebuild the mediawiki service and restart docker:

dockercomposebuild
dockercomposedown
dockercomposeup-d

In the Wikimedia production wikis, Shellbox is used to run Pygments in a container that is separate from the MediaWiki container. This separation provides better protection against potential zero-day vulnerability issues.

The shellbox runner needs two containers. The "shellbox-syntaxhighlight" container runs an HTTP server. The "shellbox-syntaxhighlight-fpm" container runs shellbox in a PHP FCGI container. These containers talk to each other over a domain socket in a shared volume.

services:
shellbox-syntaxhighlight:
# HTTP listener for SyntaxHighlight Shellbox commands
image:docker-registry.wikimedia.org/httpd-fcgi:latest
pull_policy:weekly
volumes:
-shellbox_syntaxhighlight_fcgi_socket:/run/shared/:rw
environment:
FCGI_MODE:FCGI_UNIX

shellbox-syntaxhighlight-fpm:
# PHP runtime for SyntaxHighlight Shellbox comands
image:docker-registry.wikimedia.org/wikimedia/mediawiki-libs-shellbox:syntaxhighlight83
pull_policy:weekly
volumes:
-shellbox_syntaxhighlight_fcgi_socket:/run/shared/:rw
-.settings/syntaxhighlight.json:/srv/app/config/config.json:ro
environment:
FCGI_MODE:FCGI_UNIX
volumes:
shellbox_syntaxhighlight_fcgi_socket:{}

The Docker Compose configuration mounts .settings/syntaxhighlight.json from your local working directory into the shellbox-syntaxhighlight-fpm container to configure Shellbox. A typical configuration would look something like:

{
"__":"Configuration to run SyntaxHighlight in docker-compose",
"secretKey":"@@ CHANGE THIS @@",
"url":"http://localhost:8080/",
"tempDir":"/tmp",
"logFormat":"[%datetime%] %channel%.%level_name%: %message% %context% %extra%\n",
"logFile":"/tmp/shellbox.log",
"jsonLogFile":false,
"logToStderr":true,
"jsonLogToStderr":true,
"syslogIdent":"shellbox",
"logToSyslog":false,
"logToClient":true,
"allowedActions":[
"call",
"shell"
],
"useSystemd":null,
"useBashWrapper":null,
"useFirejail":null,
"firejailPath":"/usr/bin/firejail",
"firejailProfile":null
}

"secretKey" is the most important part of this configuration. The same secret key value needs to be configured in both the Shellbox and MediaWiki configuration. Things will work with the "@@ CHANGE THIS @@" value in both files. You may choose any other string for this shared secret as long as it is the same in both locations.

wfLoadExtension( 'SyntaxHighlight_GeSHi' );
$wgPygmentizePath = '/srv/app/pygmentize';
$wgShellboxUrls = [
 'syntaxhighlight' => 'http://shellbox-syntaxhighlight:8080',
];
$wgShellboxSecretKey = '@@ CHANGE THIS @@';

The $wgShellboxSecretKey value must match the value you used in .settings/syntaxhighlight.json.

Finally, restart the docker compose stack:

dockercomposedown
dockercomposeup-d