Jump to content

MediaWiki Docker Migration Guide: Difference between revisions

From MediawikiCIT
192.168.0.242 (talk)
VisualWikitext
Created page with "== MediaWiki Migration Guide == '''''This guide walks you through backing up and migrating your MediaWiki Docker installation to a new server. Follow the steps carefully to ensure nothing is lost during the transfer.''''' <div style="background-color: #fff3cd; border-left: 4px solid #ffc107; padding: 12px; margin: 15px 0; font-size: 90%;"> '''Prerequisites:''' Complete the '''MediaWiki Docker Setup Guide''' and '''MediaWiki Additional Configuration Guide''' bef..."
 
Blanked the page
Tag: Blanking
 
Line 1: Line 1:
== MediaWiki Migration Guide ==


'''''This guide walks you through backing up and migrating your MediaWiki Docker installation to a new server. Follow the steps carefully to ensure nothing is lost during the transfer.'''''
<div style="background-color: #fff3cd; border-left: 4px solid #ffc107; padding: 12px; margin: 15px 0; font-size: 90%;">
'''Prerequisites:''' Complete the '''[[MediaWiki Docker Setup Guide]]''' and '''[[MediaWiki Additional Configuration Guide]]''' before proceeding with this guide.
</div>
== Part 1: Back Up the Source Server ==
'''1. Back Up the Database'''
Run the following command to export your MediaWiki database to a file:
<syntaxhighlight lang="bash" style="font-size: 85%;">
docker exec mediawiki-db mariadb-dump -u your_db_user -pyour_db_password your_db_name > ~/mediawiki_db_backup.sql
</syntaxhighlight>
Verify the backup was created successfully:
<syntaxhighlight lang="bash" style="font-size: 85%;">
head -5 ~/mediawiki_db_backup.sql
</syntaxhighlight>
<div style="background-color: #f8f9fa; border-left: 4px solid #3498db; padding: 12px; margin: 15px 0; font-size: 90%;">
'''Note:''' Replace <code>your_db_user</code>, <code>your_db_password</code>, and <code>your_db_name</code> with the values you set in your <code>.env</code> file during the initial setup (Step 6 of the Docker Setup Guide). In this guide, those values are <code>MYSQL_USER</code>, <code>MYSQL_PASSWORD</code>, and <code>MYSQL_DATABASE</code>.
</div>
'''2. Back Up the Images'''
Create a compressed archive of the images volume directory:
<syntaxhighlight lang="bash" style="font-size: 85%;">
sudo tar czf ~/230912_images_backup.tar.gz /opt/stacks/mediawiki/230912_images/
</syntaxhighlight>
Verify the archive was created:
<syntaxhighlight lang="bash" style="font-size: 85%;">
ls -lah ~/230912_images_backup.tar.gz
</syntaxhighlight>
'''3. Back Up the Extensions'''
Create a compressed archive of your extensions directory:
<syntaxhighlight lang="bash" style="font-size: 85%;">
sudo tar czf ~/extensions_backup.tar.gz /opt/stacks/mediawiki/extensions/
</syntaxhighlight>
Verify the archive was created:
<syntaxhighlight lang="bash" style="font-size: 85%;">
ls -lah ~/extensions_backup.tar.gz
</syntaxhighlight>
'''4. Transfer All Files to the New Server'''
Use <code>scp</code> to copy all backup files and configuration files to the new server:
<syntaxhighlight lang="bash" style="font-size: 85%;">
scp \
  ~/mediawiki_db_backup.sql \
  ~/230912_images_backup.tar.gz \
  ~/extensions_backup.tar.gz \
  /opt/stacks/mediawiki/docker-compose.yml \
  /opt/stacks/mediawiki/.env \
  /opt/stacks/mediawiki/LocalSettings.php \
  your_user@new_server_ip:/home/your_user/
</syntaxhighlight>
<div style="background-color: #f8f9fa; border-left: 4px solid #3498db; padding: 12px; margin: 15px 0; font-size: 90%;">
'''Note:''' Replace <code>your_user</code> and <code>new_server_ip</code> with the actual username and IP address of your destination server.
</div>
== Part 2: Prepare the New Server ==
'''5. Move Files into the Stack Directory'''
SSH into the new server:
<syntaxhighlight lang="bash" style="font-size: 85%;">
ssh your_user@new_server_ip
</syntaxhighlight>
Create the MediaWiki stack directory and move all transferred files into it:
<syntaxhighlight lang="bash" style="font-size: 85%;">
sudo mkdir -p /opt/stacks/mediawiki
sudo mv ~/mediawiki_db_backup.sql /opt/stacks/mediawiki/
sudo mv ~/230912_images_backup.tar.gz /opt/stacks/mediawiki/
sudo mv ~/extensions_backup.tar.gz /opt/stacks/mediawiki/
sudo mv ~/docker-compose.yml /opt/stacks/mediawiki/
sudo mv ~/<wbr>.env /opt/stacks/mediawiki/
sudo mv ~/LocalSettings.php /opt/stacks/mediawiki/
</syntaxhighlight>
Verify all files are in place:
<syntaxhighlight lang="bash" style="font-size: 85%;">
ls -lah /opt/stacks/mediawiki/
</syntaxhighlight>
'''6. Restore the Extensions'''
Extract the extensions archive into the correct directory:
<syntaxhighlight lang="bash" style="font-size: 85%;">
cd /opt/stacks/mediawiki
sudo tar xzf extensions_backup.tar.gz --strip-components=3
</syntaxhighlight>
Verify the extensions are in place:
<syntaxhighlight lang="bash" style="font-size: 85%;">
ls /opt/stacks/mediawiki/extensions/
</syntaxhighlight>
'''7. Restore the Images'''
Extract the images archive into the correct directory:
<syntaxhighlight lang="bash" style="font-size: 85%;">
sudo tar xzf 230912_images_backup.tar.gz --strip-components=3
</syntaxhighlight>
Verify the images are in place:
<syntaxhighlight lang="bash" style="font-size: 85%;">
ls /opt/stacks/mediawiki/230912_images/
</syntaxhighlight>
== Part 3: Restore the Database ==
'''8. Start the Database Container First'''
Bring up only the database container before restoring data:
<syntaxhighlight lang="bash" style="font-size: 85%;">
cd /opt/stacks/mediawiki
docker compose up -d database
sleep 10
</syntaxhighlight>
'''9. Temporarily Disable the LocalSettings Mount'''
Before restoring the database, comment out the LocalSettings mount in your Docker Compose file to prevent the wiki from starting with a mismatched configuration:
<syntaxhighlight lang="bash" style="font-size: 85%;">
sudo nano /opt/stacks/mediawiki/docker-compose.yml
</syntaxhighlight>
Find this line and add a <code>#</code> to comment it out:
<syntaxhighlight lang="yaml" style="font-size: 85%;">
# - /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro
</syntaxhighlight>
Save and exit.
'''10. Restore the Database'''
Copy the backup file into the database container, then import it:
<syntaxhighlight lang="bash" style="font-size: 85%;">
docker cp /opt/stacks/mediawiki/mediawiki_db_backup.sql mediawiki-db:/tmp/
docker exec -i mediawiki-db mariadb -u your_db_user -pyour_db_password your_db_name < /opt/stacks/mediawiki/mediawiki_db_backup.sql
</syntaxhighlight>
<div style="background-color: #f8f9fa; border-left: 4px solid #3498db; padding: 12px; margin: 15px 0; font-size: 90%;">
'''Note:''' Use the same database credentials from your <code>.env</code> file (<code>MYSQL_USER</code>, <code>MYSQL_PASSWORD</code>, <code>MYSQL_DATABASE</code>).
</div>
== Part 4: Configure and Start the New Server ==
'''11. Start the MediaWiki Container'''
Bring up all containers:
<syntaxhighlight lang="bash" style="font-size: 85%;">
docker compose up -d
</syntaxhighlight>
Verify both containers are running:
<syntaxhighlight lang="bash" style="font-size: 85%;">
docker ps | grep media
</syntaxhighlight>
'''12. Update the Server Address in LocalSettings.php'''
Open LocalSettings.php on the new server:
<syntaxhighlight lang="bash" style="font-size: 85%;">
sudo nano /opt/stacks/mediawiki/LocalSettings.php
</syntaxhighlight>
Find the line that starts with <code>$wgServer</code> and update it to the new server's address:
<syntaxhighlight lang="php" style="font-size: 85%;">
$wgServer = "http://new_server_ip:8595";
</syntaxhighlight>
<div style="background-color: #f8f9fa; border-left: 4px solid #3498db; padding: 12px; margin: 15px 0; font-size: 90%;">
'''Note:''' Replace <code>new_server_ip</code> with the actual IP address of your new server. Use <code>https://</code> if you have SSL configured. This matches the same <code>$wgServer</code> setting covered in Step 12 of the Additional Configuration Guide.
</div>
Save and exit.
'''13. Re-enable the LocalSettings Mount'''
Open the Docker Compose file and uncomment the LocalSettings line you disabled in Step 9:
<syntaxhighlight lang="bash" style="font-size: 85%;">
sudo nano /opt/stacks/mediawiki/docker-compose.yml
</syntaxhighlight>
Remove the <code>#</code> to re-enable it:
<syntaxhighlight lang="yaml" style="font-size: 85%;">
- /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro
</syntaxhighlight>
Save and exit.
'''14. Final Restart'''
Apply all changes with a full restart:
<syntaxhighlight lang="bash" style="font-size: 85%;">
docker compose down && docker compose up -d
</syntaxhighlight>
== Verification ==
Open a browser and navigate to your new server's address:
<syntaxhighlight lang="text" style="font-size: 85%;">
http://new_server_ip:8595
</syntaxhighlight>
You should see your wiki with all content, extensions, and settings intact.
== Troubleshooting ==
'''Database restore fails?'''
* Verify the database container is running: <code>docker ps | grep mediawiki-db</code>
* Confirm your credentials match those in the <code>.env</code> file
* Check container logs: <code>docker compose logs -f database</code>
'''Wiki shows a blank page or error after restart?'''
* Confirm the LocalSettings mount is uncommented in <code>docker-compose.yml</code>
* Verify <code>$wgServer</code> in LocalSettings.php matches the new server's address
* Check container logs: <code>docker compose logs -f mediawiki</code>
'''Extensions not loading?'''
* Verify permissions are correct: <code>ls -la /opt/stacks/mediawiki/extensions/</code>
* Re-apply permissions if needed:
<syntaxhighlight lang="bash" style="font-size: 85%;">
sudo chown -R 33:33 /opt/stacks/mediawiki/extensions
sudo chmod -R 755 /opt/stacks/mediawiki/extensions
</syntaxhighlight>
'''Images not appearing?'''
* Verify the images directory was restored: <code>ls /opt/stacks/mediawiki/230912_images/</code>
* Hard refresh your browser: <code>Ctrl + Shift + R</code> (Windows/Linux) or <code>Cmd + Shift + R</code> (Mac)
== Summary ==
You have successfully migrated your MediaWiki installation to a new server:
✓ Database backed up and restored
<br>
✓ Images backed up and restored
<br>
✓ Extensions backed up and restored
<br>
✓ Configuration files transferred
<br>
✓ Server address updated in LocalSettings.php
<br>
✓ Wiki running on the new server
'''''Your MediaWiki installation has been successfully migrated! Refer to the [[MediaWiki Additional Configuration Guide]] if you need to re-configure SSL or any advanced settings on the new server.'''''

Latest revision as of 05:29, 5 March 2026

Retrieved from "https://mediawiki.comfac.net/index.php?title=MediaWiki_Docker_Migration_Guide&oldid=115"