View source for Mediawiki Docker Migration Guide

== 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.'''''