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).
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 .
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
