MediaWiki Setup Guide (Portainer & Docker)

This guide documents how to deploy, configure, and secure a MediaWiki instance using Portainer and Docker Compose. Designed as a general tutorial, it walks through the process of setting up a wiki from scratch, resolving common extension folder issues, and applying production configurations.

Reference: Official MediaWiki Docker Image https://hub.docker.com//mediawiki

1. Prerequisites

Before starting, ensure you have:

Docker & Docker Compose: Installation Guide

Portainer CE: Docker Standalone Install Guide

Domain & Cloudflare Setup: Cloudflare Tunnel (Cloudflared) Setup Guide

NGINX Reverse Proxy: Nginx Proxy Manager Setup

2. Host Folder Setup

Create a dedicated folder for your stack on the Docker host. This path is critical as it will store your configuration and extensions.

Run on host terminal

sudo mkdir -p /opt/stacks/mediawiki
sudo mkdir -p /opt/stacks/mediawiki/extensions
cd /opt/stacks/mediawiki

3. Deployment (Portainer / Docker Compose)

In Portainer

Go to Stacks → Add stack.

Name it mediawiki.

Paste the configuration below into the Web editor.

Click Deploy the stack.

docker-compose.yml

services:
mediawiki:
image: mediawiki
container_name: mediawiki
restart: always
ports:
- 8595:80
depends_on:
- database
volumes:
- 230912_images:/var/www/html/images
# EXTENSIONS: Mounts host folder to container (Requires "Magic Command" step below)
- /opt/stacks/mediawiki/extensions:/var/www/html/extensions
# CONFIG: Uncomment the line below AFTER generating LocalSettings.php
# - /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro

database:
image: mariadb
container_name: mediawiki-db
restart: always
environment:
MYSQL_DATABASE: mediawiki
MYSQL_USER: mediawiki
MYSQL_PASSWORD: mediawiki
MYSQL_ROOT_PASSWORD: mediawiki
volumes:
- 230912_db:/var/lib/mysql

volumes:
230912_images:
230912_db:

4. First-Time Setup Wizard

Open http://[YOUR_SERVER_IP]:8595 in your browser.

Follow the prompts. When asked for Database Settings, use:

- Host: database
- Name: mediawiki
- User: mediawiki
- Password: mediawiki

Complete the wizard and Download LocalSettings.php to your computer.

5. Fixing Extensions (The "Magic Command")

Crucial Step: Because we mounted a volume to /extensions, the container's default extensions (VisualEditor, SyntaxHighlight_GeSHi, etc.) are hidden. We must copy them from the image to the host.

Step A: Extract Extensions

docker run --rm --entrypoint tar mediawiki -c -C /var/www/html/extensions . | tar -x -C /opt/stacks/mediawiki/extensions

Step B: Fix Permissions for Code Highlighting

The SyntaxHighlight_GeSHi extension requires a specific Python file (pygmentize) to be executable.

chmod a+x /opt/stacks/mediawiki/extensions/SyntaxHighlight_GeSHi/pygments/pygmentize

Step C: Add External Extensions

cd /opt/stacks/mediawiki/extensions
git clone https://github.com/SemanticMediaWiki/Mermaid.git Mermaid

6. Configuring LocalSettings.php

Move the downloaded LocalSettings.php to /opt/stacks/mediawiki/LocalSettings.php.

sudo nano /opt/stacks/mediawiki/LocalSettings.php

A. Set the Custom Domain

Find the $wgServer line and change it to your actual domain:

$wgServer = "https://wiki.gi7b.org";

B. Add Permissions & Extensions

Paste this block at the very bottom of the file:

/* -----------------------------------------------------------------------
CUSTOM PERMISSIONS & EXTENSIONS
----------------------------------------------------------------------- */

1. SECURITY: Prevent anonymous editing and account creation

$wgGroupPermissions['']['edit'] = false;
$wgGroupPermissions['']['createaccount'] = false;

2. BUNDLED EXTENSIONS

wfLoadExtension( 'WikiEditor' );
wfLoadExtension( 'VisualEditor' );
wfLoadExtension( 'CodeEditor' );
wfLoadExtension( 'SyntaxHighlight_GeSHi' ); # REQUIRED for Code Blocks
wfLoadExtension( 'Cite' );
wfLoadExtension( 'InputBox' );
wfLoadExtension( 'Scribunto' );
wfLoadExtension( 'AbuseFilter' );
wfLoadExtension( 'Gadgets' );
wfLoadExtension( 'ParserFunctions' );
wfLoadExtension( 'Interwiki' );

3. EXTERNAL EXTENSIONS

wfLoadExtension( 'Mermaid' );

4. VISUALEDITOR CONFIGURATION

$wgDefaultUserOptions['visualeditor-enable'] = 1;
$wgVisualEditorParsoidForwardCookies = true;

5. LUA CONFIGURATION (Required for Scribunto)

$wgScribuntoDefaultEngine = 'luastandalone';

7. Apply Changes

Mount the settings: In Portainer, go to the Stack Editor and uncomment the LocalSettings.php line.

Update the Stack: Click "Update the stack".

Run Database Update:

docker exec -it mediawiki php maintenance/update.php --quick

8. Email Configuration and Admin Setup

1. SMTP Logic

MediaWiki must be able to send emails for account confirmation and resets. Authentication must work with Gmail / Google Workspace.

2. Google App Password

Go to Google Account → Security → App passwords.

Critical Detail: MediaWiki must receive the password without spaces.

Displayed: xxxx xxxx xxxx xxxx → Input: xxxxxxxxxxxxxxxx

3. SMTP Configuration

Add this to LocalSettings.php:

$wgEnableEmail = true;
$wgEnableUserEmail = true;

$wgSMTP = [
'host'     => 'ssl://smtp.gmail.com',
'IDHost'   => 'wiki.gi7b.org',
'port'     => 465,
'auth'     => true,
'username' => 'admin@gi7b.org',        // REAL mailbox
'password' => 'APP_PASSWORD_NO_SPACES', // Your Google App Password
];

$wgPasswordSender = 'info@gi7b.org';       // ALIAS is fine here

4. Promote Account to Admin

docker exec -it mediawiki php maintenance/createAndPromote.php --sysop --bureaucrat YourUsername

9. Brute Force Protection

Add throttling to LocalSettings.php:

Login attempt throttling

$wgRateLimits['user']['login'] = [ 5, 60 ];   // 5 attempts per minute
$wgRateLimits['ip']['login']   = [ 20, 300 ]; // 20 attempts per 5 minutes

10. How to use Code Blocks

Source Editor: Use the tag:

<syntaxhighlight lang="python" copy>
print("This code has a copy button!")
</syntaxhighlight>

11. Quick Guide: Adding Extensions

Download:

cd /opt/stacks/mediawiki/extensions
git clone https://www.google.com/search?q=https://gerrit.wikimedia.org/r/mediawiki/extensions/ExtensionName

Enable: Add wfLoadExtension( 'ExtensionName' ); to LocalSettings.php.

Update:

docker exec -it mediawiki php maintenance/update.php --quick