Jump to content

MediaWiki Docker Migration Guide

From MediawikiCIT
Revision as of 05:20, 5 March 2026 by 192.168.0.242 (talk) (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...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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.

Prerequisites: Complete the MediaWiki Docker Setup Guide and MediaWiki Additional Configuration Guide before proceeding with this guide.

Part 1: Back Up the Source Server

1. Back Up the Database

Run the following command to export your MediaWiki database to a file: 

docker exec mediawiki-db mariadb-dump -u your_db_user -pyour_db_password your_db_name > ~/mediawiki_db_backup.sql

Verify the backup was created successfully: 

head -5 ~/mediawiki_db_backup.sql

Note: Replace your_db_user, your_db_password, and your_db_name with the values you set in your .env file during the initial setup (Step 6 of the Docker Setup Guide). In this guide, those values are MYSQL_USER, MYSQL_PASSWORD, and MYSQL_DATABASE.

2. Back Up the Images

Create a compressed archive of the images volume directory: 

sudo tar czf ~/230912_images_backup.tar.gz /opt/stacks/mediawiki/230912_images/

Verify the archive was created: 

ls -lah ~/230912_images_backup.tar.gz

3. Back Up the Extensions

Create a compressed archive of your extensions directory: 

sudo tar czf ~/extensions_backup.tar.gz /opt/stacks/mediawiki/extensions/

Verify the archive was created: 

ls -lah ~/extensions_backup.tar.gz

4. Transfer All Files to the New Server

Use scp to copy all backup files and configuration files to the new server: 

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/

Note: Replace your_user and new_server_ip with the actual username and IP address of your destination server.

Part 2: Prepare the New Server

5. Move Files into the Stack Directory

SSH into the new server: 

ssh your_user@new_server_ip

Create the MediaWiki stack directory and move all transferred files into it: 

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/

Verify all files are in place: 

ls -lah /opt/stacks/mediawiki/

6. Restore the Extensions

Extract the extensions archive into the correct directory: 

cd /opt/stacks/mediawiki
sudo tar xzf extensions_backup.tar.gz --strip-components=3

Verify the extensions are in place: 

ls /opt/stacks/mediawiki/extensions/

7. Restore the Images

Extract the images archive into the correct directory: 

sudo tar xzf 230912_images_backup.tar.gz --strip-components=3

Verify the images are in place: 

ls /opt/stacks/mediawiki/230912_images/

Part 3: Restore the Database

8. Start the Database Container First

Bring up only the database container before restoring data: 

cd /opt/stacks/mediawiki
docker compose up -d database
sleep 10

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: 

sudo nano /opt/stacks/mediawiki/docker-compose.yml

Find this line and add a # to comment it out: 

# - /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro

Save and exit.

10. Restore the Database

Copy the backup file into the database container, then import it: 

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

Note: Use the same database credentials from your .env file (MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE).

Part 4: Configure and Start the New Server

11. Start the MediaWiki Container

Bring up all containers: 

docker compose up -d

Verify both containers are running: 

docker ps | grep media

12. Update the Server Address in LocalSettings.php

Open LocalSettings.php on the new server: 

sudo nano /opt/stacks/mediawiki/LocalSettings.php

Find the line that starts with $wgServer and update it to the new server's address: 

$wgServer = "http://new_server_ip:8595";

Note: Replace new_server_ip with the actual IP address of your new server. Use https:// if you have SSL configured. This matches the same $wgServer setting covered in Step 12 of the Additional Configuration Guide.

Save and exit.

13. Re-enable the LocalSettings Mount

Open the Docker Compose file and uncomment the LocalSettings line you disabled in Step 9: 

sudo nano /opt/stacks/mediawiki/docker-compose.yml

Remove the # to re-enable it: 

- /opt/stacks/mediawiki/LocalSettings.php:/var/www/html/LocalSettings.php:ro

Save and exit.

14. Final Restart

Apply all changes with a full restart: 

docker compose down && docker compose up -d

Verification

Open a browser and navigate to your new server's address: 

http://new_server_ip:8595

You should see your wiki with all content, extensions, and settings intact.

Troubleshooting

Database restore fails?

  • Verify the database container is running: docker ps | grep mediawiki-db
  • Confirm your credentials match those in the .env file
  • Check container logs: docker compose logs -f database

Wiki shows a blank page or error after restart?

  • Confirm the LocalSettings mount is uncommented in docker-compose.yml
  • Verify $wgServer in LocalSettings.php matches the new server's address
  • Check container logs: docker compose logs -f mediawiki

Extensions not loading?

  • Verify permissions are correct: ls -la /opt/stacks/mediawiki/extensions/
  • Re-apply permissions if needed:
sudo chown -R 33:33 /opt/stacks/mediawiki/extensions
sudo chmod -R 755 /opt/stacks/mediawiki/extensions

Images not appearing?

  • Verify the images directory was restored: ls /opt/stacks/mediawiki/230912_images/
  • Hard refresh your browser: Ctrl + Shift + R (Windows/Linux) or Cmd + Shift + R (Mac)

Summary

You have successfully migrated your MediaWiki installation to a new server:

✓ Database backed up and restored
✓ Images backed up and restored
✓ Extensions backed up and restored
✓ Configuration files transferred
✓ Server address updated in LocalSettings.php
✓ 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.

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