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 and 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

Open LocalSettings.php and find $wgDefaultSkin. 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 configuration uses environment variables to keep sensitive credentials out of LocalSettings.php. You will need to configure both your .env file and docker-compose.yml.

Step A: Set Up the .env File

Create or edit your .env file at /opt/stacks/mediawiki/.env and add your SMTP credentials:

# SMTP Configuration
SMTP_HOST=mail.comfac-it.com
SMTP_PORT=587
SMTP_USER=your-email@comfac-it.com
SMTP_PASS=your_smtp_password_here

Warning: Never commit your .env file to version control. Add it to .gitignore.

Step B: Pass Environment Variables in docker-compose.yml

Ensure your docker-compose.yml passes the SMTP variables into the MediaWiki container:

services:
  mediawiki:
    image: mediawiki
    container_name: mediawiki
    restart: always
    ports:
      - "${MEDIAWIKI_PORT}:80"
    depends_on:
      - database
    volumes:
      - ./230912_images:/var/www/html/images
      - /opt/stacks/mediawiki/extensions:/var/www/html/extensions
      - /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro
    environment:
      - SMTP_HOST=${SMTP_HOST}
      - SMTP_PORT=${SMTP_PORT}
      - SMTP_USER=${SMTP_USER}
      - SMTP_PASS=${SMTP_PASS}

Step C: Add Email Configuration to LocalSettings.php

Open LocalSettings.php and add the following section after the extensions block:

/*-------------------------------------------
 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@comfac-it.com";
$wgPasswordSender   = "your-email@comfac-it.com";

# SMTP configuration — credentials loaded from environment variables
$wgSMTP = [
    'host'     => getenv('SMTP_HOST'),   # e.g. mail.comfac-it.com
    'IDHost'   => 'comfac-it.com',        # Your mail domain
    'port'     => getenv('SMTP_PORT'),   # 587 for TLS
    'auth'     => true,
    'username' => getenv('SMTP_USER'),   # Your SMTP username
    'password' => getenv('SMTP_PASS'),   # Your SMTP password
    'secure'   => 'tls'
];

# Additional 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;

# ================================
# ALLOWED EMAIL DOMAINS
# ================================

# Users can register/use these email domains
$wgAllowedEmailDomains = [
    'gmail.com',
    'comfac.net',
    'comfac-it.com',
];

What this does:

• Uses getenv() to read SMTP credentials from Docker environment variables at runtime
• Keeps passwords out of LocalSettings.php and version control
• IDHost is set to your mail domain (comfac-it.com)
• Restricts user email registration to approved domains only

Save and exit.

Part 4: Permission System (Who Can Do What)

5. Create a Clean Permission Structure

Open LocalSettings.php and replace the permissions section with:

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

# Anonymous users
$wgGroupPermissions['*']['read']          = true;
$wgGroupPermissions['*']['edit']          = false;
$wgGroupPermissions['*']['createaccount'] = false;

# Allow bureaucrats/admins to create accounts
$wgGroupPermissions['bureaucrat']['createaccount'] = true;

# Logged-in users (view only)
$wgGroupPermissions['user']['read'] = true;
$wgGroupPermissions['user']['edit'] = false;

# Editor group
$wgGroupPermissions['editor']['read']     = true;
$wgGroupPermissions['editor']['edit']     = true;
$wgGroupPermissions['editor']['upload']   = true;
$wgGroupPermissions['editor']['reupload'] = true;

# Sysop (admin)
$wgGroupPermissions['sysop']['read']          = true;
$wgGroupPermissions['sysop']['edit']          = true;
$wgGroupPermissions['sysop']['protect']       = true;
$wgGroupPermissions['sysop']['userrights']    = true;
$wgGroupPermissions['sysop']['createaccount'] = true;

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 and rights section)
• Enter a username
• Check the editor box
• Click Save user groups

Save and exit.

Part 5: Creating a Private Namespace

6. Configure the Private Namespace

Open LocalSettings.php and add this section after your extensions:

/*-------------------------------------------
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";

# 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: 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

7. Enable Additional Extensions

Open LocalSettings.php and expand your extensions section:

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

# Content organization
wfLoadExtension( 'CategoryTree' );
wfLoadExtension( 'ImageMap' );

# User experience
wfLoadExtension( 'Echo' );
wfLoadExtension( 'Thanks' );
wfLoadExtension( 'DiscussionTools' );

# Content features
wfLoadExtension( 'TemplateData' );
wfLoadExtension( 'TemplateStyles' );
wfLoadExtension( 'Poem' );

# File handling
wfLoadExtension( 'PdfHandler' );
wfLoadExtension( 'MultimediaViewer' );

# Moderation & security
wfLoadExtension( 'ConfirmEdit' );
wfLoadExtension( 'SpamBlacklist' );
wfLoadExtension( 'TitleBlacklist' );
wfLoadExtension( 'CiteThisPage' );
wfLoadExtension( 'AbuseFilter' );
wfLoadExtension( 'LoginNotify' );

Note: If you get an error about a missing extension after restarting, comment out that line by adding # at the beginning.

Save and exit.

Part 7: Enable File Uploads

8. Configure Upload Settings

Open LocalSettings.php 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';

Save and exit.

Part 8: Two-Factor Authentication for Administrators

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 and add:

/*-------------------------------------------
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
# $wgOATHRequiredForGroups = ['sysop', 'bureaucrat'];

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

What this does:

• 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

# 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

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 Manage and Add an authenticator app
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. If you lose access to your phone, these codes are the ONLY way to regain access to your account. Each recovery code can only be used once.

13. Test Two-Factor Authentication

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

Verification Checklist

14. Test Your Configuration

Logo & Skin

• Your custom logo appears in the top-left corner and as the favicon
• 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 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 and verify 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 and 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:

1. At the 2FA prompt, enter one of the saved recovery codes
2. Once logged in, 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 SMTP credentials are correct in your .env file
• Check SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS values
• Ensure environment variables are passed correctly in docker-compose.yml
• Check 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 OATHAuth configuration in LocalSettings.php
• Run: docker exec -it mediawiki php maintenance/update.php
• Restart containers and clear your browser cache

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

#!/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
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

# 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 (environment-variable-secured credentials)
✓ 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/