MediaWiki Migration Guide

Complete Step-by-Step Documentation

Overview

This document contains two approaches for migrating MediaWiki from one host to another:

Original Process: The actual steps taken during migration (includes troubleshooting)
Optimized Process: Streamlined approach avoiding common pitfalls

Migration Details

Source: Host A (47.239.248.67) - MediaWiki 1.42 + MariaDB + Traefik
Destination: Host B (56.155.45.177) - New server
Domain: wiki.semipin.net
Data Size: 149MB total (23MB database + 126MB images)

Method 1: Original Migration Process

The actual steps taken, including issues encountered and resolved

Step 1: Backup on Host A

mkdir ~/mediawiki_transfer
cd ~/mediawiki_transfer

# Copy configuration files
cp /root/mediawiki/docker-compose.yml ./
cp /root/mediawiki/LocalSettings.php ./
cp /root/mediawiki/BluePepperLogo.png ./

# Backup database (23MB)
docker exec mediawiki-database-1 mariadb-dump -u wikimedia -pwikimedia wiki_db > wiki_db.sql

# Backup images volume (126MB)
docker run --rm -v mediawiki_images:/data -v $(pwd):/backup alpine tar czf /backup/images_backup.tar.gz -C /data .

Result: Successfully created backups totaling 149MB

Step 2: Transfer Files (Host A → Mac → Host B)

# From Mac: Download from Host A
scp -i ~/Documents/semipinwiki2.pem -r root@47.239.248.67:~/mediawiki_transfer ~/Documents/

# From Mac: Upload to Host B  
scp -i ~/Documents/aws20250806.pem -r ~/Documents/mediawiki_transfer ubuntu@56.155.45.177:~/

Note: Used Mac as intermediate step due to different PEM keys for each host

Step 3: Install Docker on Host B

# Install Docker and Docker Compose
sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl start docker
sudo systemctl enable docker

Step 4: Setup MediaWiki on Host B

# Create directory structure
sudo mkdir -p /root/mediawiki
cd /root/mediawiki

# Copy configuration files
sudo cp /home/ubuntu/mediawiki_transfer/docker-compose.yml ./
sudo cp /home/ubuntu/mediawiki_transfer/LocalSettings.php ./
sudo cp /home/ubuntu/mediawiki_transfer/BluePepperLogo.png ./

# Create network and start database
docker network create webproxy
docker compose up -d database
sleep 30

# Import database
docker exec -i mediawiki-database-1 mariadb -u wikimedia -pwikimedia wiki_db < /home/ubuntu/mediawiki_transfer/wiki_db.sql

# Restore images
docker run --rm -v mediawiki_images:/data -v /home/ubuntu/mediawiki_transfer:/backup alpine tar xzf /backup/images_backup.tar.gz -C /data

# Start complete stack
docker compose up -d

Step 5: Troubleshooting Issues Encountered

Issue 1: Deprecation Warnings

Problem: MediaWiki latest (1.44) pulled instead of 1.42, causing compatibility warnings

Error:

Deprecated: Use of MediaWiki\Skin\Skin::appendSpecialPagesLinkIfAbsent was deprecated in MediaWiki 1.44

Solution: Downgraded to MediaWiki 1.42

sed -i 's/image: mediawiki:latest/image: mediawiki:1.42/' /root/mediawiki/docker-compose.yml
docker compose down && docker compose up -d

Issue 2: Database Connection Error

Problem: Database schema was updated to 1.44 during initial setup, incompatible with 1.42 after downgrade

Error:

A database query error has occurred. This may indicate a bug in the software.
Fatal exception of type "Wikimedia\Rdbms\DBQueryError"

Solution: Restored original 1.42 database

docker compose down
docker volume rm mediawiki_database
docker volume create mediawiki_database
docker compose up -d database
sleep 30
docker exec -i mediawiki-database-1 mariadb -u wikimedia -pwikimedia wiki_db < /home/ubuntu/mediawiki_transfer/wiki_db.sql
docker compose up -d

Issue 3: Outdated Appearance

Problem: Only MonoBook skin enabled, causing "last century" appearance

Solution: Re-enabled all skins in LocalSettings.php

wfLoadSkin( 'MinervaNeue' );
wfLoadSkin( 'MonoBook' );
wfLoadSkin( 'Timeless' );
wfLoadSkin( 'Vector' );

Issue 4: Server URL Configuration

Solution: Added correct server URL

echo '$wgServer = "http://56.155.45.177:8081";' >> /root/mediawiki/LocalSettings.php

Final Result ✅

Access: http://56.155.45.177:8081
Status: Migration successful after resolving compatibility issues
Lessons Learned: Version consistency critical for smooth migration

Method 2: Optimized Migration Process

Streamlined approach avoiding the issues encountered in Method 1

Step 1: Backup on Host A

mkdir ~/mediawiki_transfer
cd ~/mediawiki_transfer

# Copy configuration files
cp /root/mediawiki/docker-compose.yml ./
cp /root/mediawiki/LocalSettings.php ./
cp /root/mediawiki/BluePepperLogo.png ./

# Backup database (23MB)
docker exec mediawiki-database-1 mariadb-dump -u wikimedia -pwikimedia wiki_db > wiki_db.sql

# Backup images volume (126MB)
docker run --rm -v mediawiki_images:/data -v $(pwd):/backup alpine tar czf /backup/images_backup.tar.gz -C /data .

Step 2: Transfer Files (Host A → Mac → Host B)

# From Mac: Download from Host A
scp -i ~/Documents/semipinwiki2.pem -r root@47.239.248.67:~/mediawiki_transfer ~/Documents/

# From Mac: Upload to Host B  
scp -i ~/Documents/aws20250806.pem -r ~/Documents/mediawiki_transfer ubuntu@56.155.45.177:~/

Step 3: Install Docker on Host B

# Install Docker and Docker Compose
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl start docker
sudo systemctl enable docker

Step 4: Prepare Configuration for Host B

# Create directory structure
sudo mkdir -p /root/mediawiki
cd /root/mediawiki

# Copy configuration files
sudo cp /home/ubuntu/mediawiki_transfer/docker-compose.yml ./
sudo cp /home/ubuntu/mediawiki_transfer/LocalSettings.php ./
sudo cp /home/ubuntu/mediawiki_transfer/BluePepperLogo.png ./

# CRITICAL: Modify docker-compose.yml to use MediaWiki 1.42 (matching Host A)
sed -i 's/image: mediawiki:latest/image: mediawiki:1.42/' /root/mediawiki/docker-compose.yml

# Add correct server URL to LocalSettings.php
echo '$wgServer = "http://56.155.45.177:8081";' >> /root/mediawiki/LocalSettings.php

Step 5: Setup MediaWiki on Host B

# Create network and start database
docker network create webproxy
docker compose up -d database
sleep 30

# Import database
docker exec -i mediawiki-database-1 mariadb -u wikimedia -pwikimedia wiki_db < /home/ubuntu/mediawiki_transfer/wiki_db.sql

# Restore images
docker run --rm -v mediawiki_images:/data -v /home/ubuntu/mediawiki_transfer:/backup alpine tar xzf /backup/images_backup.tar.gz -C /data

# Start complete stack (MediaWiki 1.42 will be pulled)
docker compose up -d

Step 6: Verify Migration

# Check containers are running
docker ps

# Test access
curl -I http://localhost:8081

# Verify database tables
docker exec mediawiki-database-1 mariadb -u wikimedia -pwikimedia -e "USE wiki_db; SHOW TABLES;" | head -10

# Test in browser: http://56.155.45.177:8081

Key Optimizations Made

Version consistency from start: Modified docker-compose.yml to use MediaWiki 1.42 before first startup
No upgrade/downgrade cycle: Avoided MediaWiki 1.44 entirely
Pre-configured server URL: Added correct server setting before startup
Clean deployment: Single MediaWiki version throughout the process

Benefits of Optimized Approach

✅ No deprecation warnings: Version consistency prevents compatibility issues
✅ No database schema conflicts: Database remains compatible throughout
✅ Faster deployment: No need for version changes after setup
✅ Cleaner process: Single MediaWiki pull instead of multiple versions

Comparison: Original vs Optimized

Aspect	Original Process	Optimized Process
MediaWiki Versions Used	1.44 → 1.42 (downgrade)	1.42 only
Database Updates	Required restoration	Clean import
Deprecation Warnings	Yes (resolved)	None
Schema Conflicts	Yes (resolved)	None
Steps Required	5 + troubleshooting	6 (streamlined)
Complexity	High (debugging needed)	Low (preventive)
Time to Complete	Longer (due to issues)	Shorter (no issues)

Technical Details

Final Configuration

MediaWiki Version: 1.42
Database: MariaDB latest
Skins Enabled: Vector (default), MinervaNeue, MonoBook, Timeless
Extensions: WikiEditor, SyntaxHighlight_GeSHi
Access Method: HTTP (port 8081)
Domain Ready: Configured for wiki.semipin.net (DNS update needed)

Container Structure

services:
  mediawiki2:
    image: mediawiki:1.42
    ports:
      - 8081:80
    volumes:
      - images:/var/www/html/images
      - ./LocalSettings.php:/var/www/html/LocalSettings.php
      - ./BluePepperLogo.png:/var/www/html/images/BluePepperLogo.png
  
  database:
    image: mariadb:latest
    environment:
      MYSQL_DATABASE: wiki_db
      MYSQL_USER: wikimedia
      MYSQL_PASSWORD: wikimedia
    volumes:
      - database:/var/lib/mysql

Security Considerations

Database credentials maintained from original setup
Server URL configured for current host
Traefik labels preserved for future SSL setup
File permissions maintained during transfer

Next Steps (Optional)

Domain Setup

To enable https://wiki.semipin.net access:

Install Traefik on Host B (matching Host A configuration)
Update DNS: Point wiki.semipin.net to 56.155.45.177
SSL Certificates: Let's Encrypt will auto-issue via Traefik
Firewall: Ensure ports 80/443 open on Host B

Maintenance Recommendations

Regular database backups using the same mysqldump approach
Monitor MediaWiki security updates
Keep Docker images updated
Backup LocalSettings.php after configuration changes

Conclusion

Both migration approaches successfully transferred the MediaWiki installation from Host A to Host B. The optimized approach prevents common pitfalls and provides a smoother migration experience.

Migration Status: ✅ Complete and Successful

Final Access: http://56.155.45.177:8081

Document generated: August 7, 2025
Migration completed successfully with full functionality restored

Migrate MediaWiki docker and Traefik docker

"scp" all files (img volume, database dump, docker compose file, LocalSettings.php).

do the following on local shell (not logged in on the remote VPS)

scp -i /Users/mikaelhsu/Documents/semipinwiki2.pem root@47.239.248.67:/root/mediawiki/LocalSettings.php .

scp -i /Users/mikaelhsu/Documents/semipinwiki2.pem root@47.239.248.67:/root/mediawiki/docker-compose.yml .

create database dump

docker exec mediawiki-database-1 /usr/bin/mariadb-dump -u root -p'root' wiki_db > /root/mediawiki/db_dump_${DATE}.sql

backup docker image volume

docker run --rm --volumes-from mediawiki-mediawiki2-1 -v $(pwd):/backup ubuntu tar cvf /backup/images_backup.tar /var/www/html/images

# Copy the dated database dump to local Mac

scp -i /Users/mikaelhsu/Documents/semipinwiki2.pem root@47.239.248.67:/root/mediawiki/db_dump_2025-08-06.sql .

# Copy the dated images backup to local Mac

scp -i /Users/mikaelhsu/Documents/semipinwiki2.pem root@47.239.248.67:/root/mediawiki/images_backup_2025-08-06.tar.gz .

copy files from local Mac to new host

scp -i ~/Documents/aws20250806.pem ~/Documents/images_backup.tar ubuntu@56.155.45.177:/home/ubuntu/mediawiki/

On new server, install docker, install MediaWiki docker (through docker compose up -d)
Restore image volume, import database dump
Run MediaWiki "update.php" if necessary (sometimes new mediawiki docker might be of newer version than the mediawiki version on the old server)
Modify LocalSettings.php (change server IP/name, disable extensions etc.)
On new server, open firewall port if necessary

Start mediawiki docker first (don't start Traefik docker yet)
Access the mediawiki service through non-encrypted http only, to "bring it up"
http://wiki.semipin.net:8081/index.php/Main_Page
Now start Trafik docker (2025-05-08, uncommented the "--log.level=DEBUG" line in docker compose file, which seems to help improve https://wiki access after Traefik docker is started)
Now https://wiki.semipin.net should be accessible.

chmod 400 Documents/semipinwiki2.pem

ssh -i ~/Documents/semipinwiki2.pem root@47.239.248.67

docker cp LocalSettings.php mediawiki-mediawiki2-1:/var/www/html/

root@06a732ee8c8f:/var/www/html/maintenance# php Version.php

*******************************************************************************
NOTE: Do not run maintenance scripts directly, use maintenance/run.php instead!
Running scripts directly has been deprecated in MediaWiki 1.40.
It may not work for some (or any) scripts in the future.
*******************************************************************************

MediaWiki version: 1.42.1 (built: 12:36, 26 April 2025)

+------------------------+
| VERSION() |
+------------------------+
| 11.4.2-MariaDB-ubu2404 |
+------------------------+

MediaWiki Cloudflare tunnel docker command

docker run --detach --network tunnel cloudflare/cloudflared:latest tunnel --no-autoupdate run --token eyJhIjoiNjIwYzJhYzE0Y2E4NmZkNDIyYTdkZjM2YmU1ZDcyZTIiLCJ0IjoiYmNmM2M2ZjAtZTFiZC00ZGYwLTkyNzUtMzU5ZGRkZjZkODg5IiwicyI6IllqY3dPREV3TUdFdFpETmlNQzAwTlRZMkxUZzRZMk10TW1Vd05URTBORFJpWlRNNCJ9

Lab Ideas & Ideas Lab

Sunday, August 18, 2024

MediaWiki Migration Guide

Complete Step-by-Step Documentation

Overview

Migration Details

Method 1: Original Migration Process

Step 1: Backup on Host A

Step 2: Transfer Files (Host A → Mac → Host B)

Step 3: Install Docker on Host B

Step 4: Setup MediaWiki on Host B

Step 5: Troubleshooting Issues Encountered

Issue 1: Deprecation Warnings

Issue 2: Database Connection Error

Issue 3: Outdated Appearance

Issue 4: Server URL Configuration

Final Result ✅

Method 2: Optimized Migration Process

Step 1: Backup on Host A

Step 2: Transfer Files (Host A → Mac → Host B)

Step 3: Install Docker on Host B

Step 4: Prepare Configuration for Host B

Step 5: Setup MediaWiki on Host B

Step 6: Verify Migration

Key Optimizations Made

Benefits of Optimized Approach

Comparison: Original vs Optimized

Technical Details

Final Configuration

Container Structure

Security Considerations

Next Steps (Optional)

Domain Setup

Maintenance Recommendations

Conclusion

No comments:

Blog Archive

Contributors