MediaWiki-Docker/Extension/SyntaxHighlight

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

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.

Run from MediaWiki image

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.

Install python3 in custom image

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

python3.dockerfile

FROM docker-registry.wikimedia.org/dev/bookworm-php83-fpm:1.0.0
RUN apt-get update && apt-get install -y python3

You should check to be sure the FROM line to matches the image line found in docker-compose.yml.

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

docker-compose.override.yml

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

Rebuild and restart

Finally, rebuild the mediawiki service and restart docker:

docker compose build
docker compose down
docker compose up -d

Run from Shellbox container

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.

Add shellbox containers to your Docker Compose configuration

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.

docker-compose.override.yml

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: {}

Add Shellbox configuration

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:

.settings/syntaxhighlight.json

{
    "__": "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.

Add MediaWiki configuration

LocalSettings.php

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.

Restart

Finally, restart the docker compose stack:

docker compose down
docker compose up -d