Mediawiki Additional Configuration

MediaWiki Additional Configuration Guide

This guide covers advanced configuration options for your MediaWiki installation, including logos, permissions, email, private namespaces, and two-factor authentication.

Prerequisites: Complete the MediaWiki Docker Setup Guide before proceeding with this configuration.

Advanced Configuration

Part 1: Customizing Your Wiki's Appearance

1. Upload Your Logo Files

Before configuring logos, you need to upload your logo images to the wiki's images folder.

Step A: Prepare Your Logo Files

Create logo images in these sizes:

• Small logo (50x50 pixels): For favicon and small displays - save as yourlogo-50.svg or yourlogo-50.png
• Large logo (160x160 pixels): For the main wiki logo - save as yourlogo-160.svg or yourlogo-160.png

Tip: SVG format is recommended because it scales cleanly at any size. PNG is also acceptable.

Step B: Copy Logo Files to the Server

First, you need to upload files to the Docker volume:

# Create a temporary container to access the images volume
docker run -d --name temp-mediawiki \
  -v 230912_images:/var/www/html/images \
  mediawiki sleep 3600

# Copy your logo files into the container
docker cp ~/Downloads/yourlogo-50.svg temp-mediawiki:/var/www/html/images/
docker cp ~/Downloads/yourlogo-160.svg temp-mediawiki:/var/www/html/images/

# Fix permissions
docker exec temp-mediawiki chown 33:33 /var/www/html/images/yourlogo-50.svg
docker exec temp-mediawiki chown 33:33 /var/www/html/images/yourlogo-160.svg

# Remove the temporary container
docker stop temp-mediawiki
docker rm temp-mediawiki

Note: Replace yourlogo-50.svg and yourlogo-160.svg with your actual filename. Adjust the path ~/Downloads/ if your files are saved elsewhere.

2. Configure Logo and Favicon in LocalSettings.php

Open your LocalSettings.php file:

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

Find the existing $wgLogos section (it looks like this):

$wgLogos = [
	'1x' => "$wgResourceBasePath/resources/assets/change-your-logo.svg",
	'icon' => "$wgResourceBasePath/resources/assets/change-your-logo.svg",
];

Replace it with:

$wgLogos = [
	'1x' => "$wgResourceBasePath/images/yourlogo-160.svg",
	'icon' => "$wgResourceBasePath/images/yourlogo-50.svg",
];

$wgFavicon = "$wgResourceBasePath/images/yourlogo-50.svg";

What this does:

• '1x' sets your main wiki logo (shown in the corner)
• 'icon' sets the smaller icon version
• $wgFavicon sets the browser tab icon

Save and exit.

Part 2: Customizing the Wiki Skin (Theme)

3. Configure the Modern Vector Skin

MediaWiki comes with several "skins" (visual themes). The Vector skin has a modern version called vector-2022.

Open LocalSettings.php again:

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

Find this line near the bottom:

$wgDefaultSkin = "monobook";

Replace it with this configuration block:

# Use the modern Vector 2022 skin by default
$wgDefaultSkin = "vector-2022";

# Make existing users see the new skin too
$wgVectorDefaultSkinVersionForExistingAccounts = "2";

# Make the skin work well on mobile devices
$wgVectorResponsive = true;

# Enable appearance customization options for users
$wgVectorFeatureFlags = [
    'VectorAppearance' => [
        'logged_in' => true,
        'logged_out' => true,
    ],
];

What this does:

• Sets the modern Vector skin as default
• Makes it responsive for mobile/tablet viewing
• Allows users to customize appearance settings

Save and exit.

Part 3: Setting Up Email and SMTP

This allows your wiki to send password reset emails, notifications, and user-to-user messages.

4. Configure Email Settings

Important: This example uses Gmail. If using another email provider, you'll need their SMTP settings.

Step A: Generate a Gmail App Password

If using Gmail, you need an "App Password" (regular passwords won't work):

1. Go to your Google Account: https://myaccount.google.com/
2. Click Security in the left sidebar
3. Scroll to "How you sign in to Google"
4. Click 2-Step Verification (you must enable this first)
5. Scroll down and click App passwords
6. Select Mail and Other (Custom name)
7. Type "MediaWiki" as the name
8. Click Generate
9. Copy the 16-character password (it looks like: abcd efgh ijkl mnop)

Step B: Add Email Configuration to LocalSettings.php

Open LocalSettings.php:

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

Scroll to the bottom (after the extensions section) and add:

/*-------------------------------------------
EMAIL & SMTP CONFIGURATION
----------------------------------------- */

# Enable email features
$wgEnableEmail = true;
$wgEnableUserEmail = true;
$wgEmailAuthentication = true;

# Enable email notifications for talk pages and watchlist
$wgEnotifUserTalk = true;
$wgEnotifWatchlist = true;

# Set your wiki's email addresses
$wgEmergencyContact = "your-email@gmail.com";
$wgPasswordSender = "your-email@gmail.com";

# Gmail SMTP configuration
$wgSMTP = [
    'host'     => 'smtp.gmail.com',
    'IDHost'   => 'yourdomain.com',           # Your domain (or 'gmail.com' for testing)
    'port'     => 587,
    'auth'     => true,
    'username' => 'your-email@gmail.com',     # Your Gmail address
    'password' => 'your app password here',   # Paste your 16-character App Password
    'secure'   => 'tls'
];

# Email settings
$wgUserEmailUseReplyTo = true;
$wgAllowHTMLEmail = true;

# Enable password reset via email
$wgPasswordResetRoutes = [
    'username' => true,
    'email' => true,
];

# Password reset links expire after 24 hours
$wgNewPasswordExpiry = 86400;

Replace these values:

• your-email@gmail.com → Your actual Gmail address
• your app password here → The 16-character password from Step A (remove spaces)
• yourdomain.com → Your wiki's domain name

Save and exit.

Part 4: Permission System (Who Can Do What)

5. Create a Clean Permission Structure

By default, MediaWiki allows anyone to edit. Let's create a more controlled system with different user levels.

Open LocalSettings.php:

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

Find the existing permissions section in your CUSTOM PERMISSIONS & EXTENSIONS block:

// 1. SECURITY: Prevent anonymous editing and account creation
$wgGroupPermissions['*']['edit'] = false;
$wgGroupPermissions['*']['createaccount'] = false;

Replace it with this expanded permission system:

/*-------------------------------------------
CLEAN PERMISSION SYSTEM
----------------------------------------- */

# ANONYMOUS USERS (not logged in)
$wgGroupPermissions['*']['read'] = true;           # Can view pages
$wgGroupPermissions['*']['edit'] = false;          # Cannot edit
$wgGroupPermissions['*']['createaccount'] = false; # Cannot create accounts

# LOGGED-IN USERS (default group)
$wgGroupPermissions['user']['read'] = true;        # Can view pages
$wgGroupPermissions['user']['edit'] = false;       # Cannot edit (read-only)

# EDITOR GROUP (must be assigned by admin)
$wgGroupPermissions['editor']['read'] = true;      # Can view pages
$wgGroupPermissions['editor']['edit'] = true;      # Can edit pages
$wgGroupPermissions['editor']['upload'] = true;    # Can upload files
$wgGroupPermissions['editor']['reupload'] = true;  # Can replace existing files

# SYSOP GROUP (administrators)
$wgGroupPermissions['sysop']['read'] = true;       # Can view pages
$wgGroupPermissions['sysop']['edit'] = true;       # Can edit pages
$wgGroupPermissions['sysop']['protect'] = true;    # Can protect pages
$wgGroupPermissions['sysop']['userrights'] = true; # Can assign user groups

# Enable protection levels
$wgRestrictionLevels[] = 'user';

What this permission structure means:

• Anonymous visitors: Can only read pages
• Logged-in users: Can only read pages (no editing)
• Editors: Can read, edit, and upload files (assigned by admins)
• Sysops (Admins): Full control over the wiki

How to assign the Editor role:

After restarting your wiki, log in as an admin and go to:

• Special:UserRights (or click Special Pages → User rights management)
• Enter a username
• Check the editor box
• Click Save user groups

Save and exit.

Part 5: Creating a Private Namespace

Private namespaces let you create pages that only certain user groups can see. This is useful for internal documentation, confidential information, or drafts.

6. Configure the Private Namespace

The Lockdown extension should already be installed from the basic setup. Now let's configure it.

Open LocalSettings.php:

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

Add this section after your extensions (near the bottom of the CUSTOM PERMISSIONS & EXTENSIONS block):

/*-------------------------------------------
PRIVATE NAMESPACE (RESTRICTED ACCESS)
----------------------------------------- */

# Load the Lockdown extension
wfLoadExtension( 'Lockdown' );

# Define namespace IDs (must be unique)
define("NS_PRIVATE", 3000);
define("NS_PRIVATE_TALK", 3001);

# Register the namespace names
$wgExtraNamespaces[NS_PRIVATE] = "Private";
$wgExtraNamespaces[NS_PRIVATE_TALK] = "Private_talk";

# Set permissions for the Private namespace
# Only logged-in users, editors, and admins can READ
$wgNamespacePermissionLockdown[NS_PRIVATE]['read'] = ['user', 'editor', 'sysop'];

# Only editors and admins can EDIT
$wgNamespacePermissionLockdown[NS_PRIVATE]['edit'] = ['editor', 'sysop'];

How to use the Private namespace:

To create a private page, use this format in the URL or search:

• Private:YourPageName

Example: Private:Company_Policies

Anonymous users and non-logged-in visitors will get an access denied message.

Save and exit.

Part 6: Additional Recommended Extensions

These extensions add useful features for a professional wiki.

7. Enable Additional Extensions

Open LocalSettings.php:

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

Find your EXTERNAL EXTENSIONS section and expand it with these additional extensions:

// 3. EXTERNAL EXTENSIONS
wfLoadExtension( 'Mermaid' );

/*-------------------------------------------
ADDITIONAL RECOMMENDED EXTENSIONS
----------------------------------------- */

# Content organization
wfLoadExtension( 'CategoryTree' );      # Browse categories as tree structure
wfLoadExtension( 'ImageMap' );          # Clickable image regions

# User experience
wfLoadExtension( 'Echo' );              # Notification system
wfLoadExtension( 'Thanks' );            # Thank users for edits
wfLoadExtension( 'DiscussionTools' );   # Better talk page discussions

# Content features
wfLoadExtension( 'TemplateData' );      # Document templates
wfLoadExtension( 'TemplateStyles' );    # CSS styling for templates
wfLoadExtension( 'Poem' );              # Format poetry and verse

# File handling
wfLoadExtension( 'PdfHandler' );        # Display PDF thumbnails
wfLoadExtension( 'MultimediaViewer' );  # Better image viewing

# Moderation & security
wfLoadExtension( 'ConfirmEdit' );       # CAPTCHA for spam prevention
wfLoadExtension( 'SpamBlacklist' );     # Block spam URLs
wfLoadExtension( 'TitleBlacklist' );    # Block page title patterns
wfLoadExtension( 'CiteThisPage' );      # Citation tools

Note: Some of these extensions may already be included in your MediaWiki installation. If you get an error about a missing extension after restarting, simply comment out that line by adding # at the beginning or remove it entirely.

Save and exit.

Part 7: Enable File Uploads

8. Configure Upload Settings

Open LocalSettings.php:

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

Find the line with $wgEnableUploads and update the upload settings:

# Enable file uploads
$wgEnableUploads = true;
$wgUseImageMagick = true;
$wgImageMagickConvertCommand = "/usr/bin/convert";
$wgUseInstantCommons = false;

# Allow these file types to be uploaded
$wgFileExtensions = ['png','gif','jpg','jpeg','webp','svg','pdf','doc','docx','xls','xlsx'];

# Allow SVG files with embedded titles
$wgAllowTitleInSVG = true;
$wgSVGConverter = 'ImageMagick';

Note: You can add or remove file extensions based on your needs. Be cautious about allowing executable files or scripts.

Save and exit.

Part 8: Two-Factor Authentication for Administrators

Add an extra layer of security by requiring administrators to use two-factor authentication.

9. Install the OATHAuth Extension

First, check if the extension already exists:

ls /opt/stacks/mediawiki/extensions/ | grep -i oath

If you don't see OATHAuth, install it:

cd /opt/stacks/mediawiki/extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/OATHAuth.git
sudo chown -R 33:33 OATHAuth

10. Configure OATHAuth for Admins Only

Open LocalSettings.php:

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

Add this configuration after your extensions:

/*-------------------------------------------
TWO-FACTOR AUTHENTICATION (ADMINS ONLY)
----------------------------------------- */

# Load the OATHAuth extension
wfLoadExtension( 'OATHAuth' );

# REQUIRE 2FA for administrators (sysops) only
$wgOATHRequiredForGroups = ['sysop'];

# Optional: Also require 2FA for bureaucrats if you have this group
# $wgOATHRequiredForGroups = ['sysop', 'bureaucrat'];

# Allow TOTP (Time-based One-Time Password) - works with Google Authenticator, Authy, etc.
$wgOATHAuthModules = [
    'totp' => [
        'class' => 'MediaWiki\\Extension\\OATHAuth\\Module\\TOTP',
    ],
];

What this does:

• Loads the OATHAuth extension
• Requires 2FA only for users in the 'sysop' (administrator) group
• Regular users and editors do NOT need 2FA
• Uses TOTP method (compatible with most authenticator apps)

Save and exit.

Part 9: Apply All Changes

11. Update the Database and Restart

After making all these configuration changes, update your database and restart the containers:

# Update database to recognize new extensions and namespaces
docker exec -it mediawiki php maintenance/update.php --quick

# Restart MediaWiki to apply all changes
cd /opt/stacks/mediawiki
docker compose restart

Wait about 30 seconds for the containers to fully restart.

Setting Up Two-Factor Authentication

12. Set Up 2FA for Administrator Accounts

Now each administrator needs to enable 2FA on their account.

Step A: Install an Authenticator App (If Not Already Installed)

On your phone or tablet, install one of these apps:

• Google Authenticator (iOS/Android)
• Microsoft Authenticator (iOS/Android)
• Authy (iOS/Android)
• 1Password (if you use a password manager)

Step B: Enable 2FA on Your Admin Account

1. Log in to MediaWiki as an administrator
2. Click on your username in the top-right corner
3. Click Preferences
4. Click the Two-factor authentication tab (or OATH tab)
5. Click Enable two-factor authentication
6. You'll see a QR code on the screen

Step C: Scan the QR Code

1. Open your authenticator app on your phone
2. Tap the "+" or "Add account" button
3. Scan the QR code shown on your screen
4. The app will add an entry like "MediaWiki - YourUsername"
5. You'll see a 6-digit code that changes every 30 seconds

Step D: Verify the Setup

1. Enter the 6-digit code from your authenticator app into the MediaWiki form
2. You'll also see scratch codes (recovery codes) - SAVE THESE SAFELY!
3. Click Confirm or Enable

CRITICAL - Save Your Recovery Codes!

Write down or securely save your recovery codes (also called scratch codes). If you lose access to your phone, these codes are the ONLY way to regain access to your account. Store them in a safe place like:

• A password manager
• A secure note app
• Printed on paper in a safe location

Each recovery code can only be used once.

13. Test Two-Factor Authentication

Log out and log back in to verify 2FA is working:

1. Log out of your MediaWiki account
2. Log back in with your username and password
3. You'll now see a new screen asking for a Two-factor authentication token
4. Open your authenticator app
5. Enter the current 6-digit code
6. Click Continue or Log in

You should now be logged in successfully!

Verification Checklist

14. Test Your Configuration

Visit your wiki and verify these features are working:

• Logo: Your custom logo appears in the top-left corner and as the favicon

• Skin: The modern Vector 2022 skin is active

• Permissions:

1. Log out and confirm you can only read pages
2. Log in as a regular user and confirm you cannot edit
3. Log in as admin and assign the "editor" role to a test user via Special:UserRights
4. Confirm the editor can now edit pages

• Email:

1. Click "Forgot password?" on the login page
2. Enter your username or email
3. Check that you receive the reset email

• Private Namespace:

1. Create a page like Private:Test
2. Log out and confirm anonymous users cannot access it
3. Log in as a regular user and confirm you can view it
4. Check that only editors and admins can edit it

• File Uploads:

1. Log in as an editor or admin
2. Go to Special:Upload
3. Try uploading an image file
4. Verify it appears on the page

• Two-Factor Authentication:

1. Verify all admins have set up 2FA
2. Test login process with 2FA code
3. Verify recovery codes are saved securely

Managing Two-Factor Authentication

If an Admin Loses Access to Their Phone:

They can use one of their recovery codes instead of the authenticator code:

1. At the 2FA prompt, enter one of the saved recovery codes
2. Once logged in, immediately go to Preferences → Two-factor authentication
3. Disable 2FA, then re-enable it with a new QR code
4. Generate new recovery codes

If Recovery Codes Are Also Lost:

Another administrator needs to disable 2FA for that account:

# Run this command to disable 2FA for a specific user
docker exec -it mediawiki php maintenance/run.php OATHAuth:deleteUser --user="USERNAME"

Replace USERNAME with the actual username.

Security Tip: Create at least two administrator accounts so one admin can help recover another's account if needed.

Troubleshooting

Email not sending?

• Verify your Gmail App Password is correct (16 characters, no spaces)
• Check that 2-Step Verification is enabled on your Google account
• Look at container logs: docker compose logs -f mediawiki

Logo not appearing?

• Verify files were copied correctly: docker exec mediawiki ls -la /var/www/html/images/
• Hard refresh your browser: Ctrl + Shift + R (Windows/Linux) or Cmd + Shift + R (Mac)
• Check the exact filenames in LocalSettings.php match the uploaded files

Private namespace not working?

• Ensure Lockdown extension is installed: ls /opt/stacks/mediawiki/extensions/Lockdown
• Run database update: docker exec -it mediawiki php maintenance/update.php --quick
• Restart containers: docker compose restart

2FA prompt not appearing for admins:

• Verify the configuration in LocalSettings.php
• Check that database update ran successfully: docker exec -it mediawiki php maintenance/update.php
• Restart containers: docker compose restart
• Clear your browser cache and try again

QR code not displaying:

• Check container logs: docker compose logs -f mediawiki
• Verify OATHAuth extension is installed: ls /opt/stacks/mediawiki/extensions/OATHAuth

Authenticator codes not working:

• Verify your phone's time is set to automatic (not manual)
• Time synchronization is critical for TOTP to work
• Try syncing time in your authenticator app settings

Maintenance Tasks

Regular Backups

Create a backup script for your wiki:

#!/bin/bash
# Save as /opt/scripts/backup-mediawiki.sh

BACKUP_DIR="/opt/backups/mediawiki"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Backup database
docker exec mediawiki-db mysqldump -u root -pyour_root_password my_wiki > $BACKUP_DIR/db_$DATE.sql

# Backup LocalSettings.php
cp /opt/stacks/mediawiki/LocalSettings.php $BACKUP_DIR/LocalSettings_$DATE.php

# Backup images (use docker volume backup)
docker run --rm -v 230912_images:/data -v $BACKUP_DIR:/backup alpine tar czf /backup/images_$DATE.tar.gz -C /data .

echo "Backup completed: $DATE"

Updating MediaWiki

When a new version is released:

# Pull the latest MediaWiki image
docker pull mediawiki:latest

# Restart with the new image
cd /opt/stacks/mediawiki
docker compose down
docker compose up -d

# Update the database schema
docker exec -it mediawiki php maintenance/update.php

# Clear the cache
docker exec -it mediawiki php maintenance/rebuildLocalisationCache.php

Summary

You've successfully configured advanced features for your MediaWiki installation:

✓ Custom logos and modern Vector 2022 theme
✓ Email notifications via SMTP (Gmail)
✓ Multi-level permission system (Anonymous, User, Editor, Sysop)
✓ Private namespace for confidential content
✓ Additional professional extensions
✓ File upload capabilities
✓ Two-factor authentication for administrators
✓ Enhanced security hardening

Your MediaWiki installation is now fully configured and production-ready!

Next Steps

Your wiki is now fully configured! You can:

• Create user accounts and assign roles via Special:UserRights
• Start creating content in the main namespace
• Create private documentation in the Private: namespace
• Customize the main page by editing MediaWiki:Mainpage
• Explore Special:SpecialPages to discover all available features
• Set up automatic backups (see Maintenance Tasks above)
• Configure SSL/HTTPS if not already done
• Install additional extensions from https://www.mediawiki.org/wiki/Category:Extensions

For additional help, visit the official MediaWiki documentation at https://www.mediawiki.org/