how to move a MediaWiki wiki from one server to another
It happens every so often. You upgrade your web server, and you want to move your MediaWiki wiki from the old server to the new server. Or maybe you just want to back up your wiki and have confidence that you can restore it later. Either way, this guide will show you the way.
overview
There are many resources out there suggesting various methods for backing up MediaWiki wikis. I have found, however, that most of the methods are deficient in one way or another -- or they are simply too troublesome. Generally speaking, you should avoid any technique that involves MediaWiki maintenance scripts, because they don't really seem capable of producing or restoring complete backups. You can play around with dumpBackup.php and importDump.php, but you will find that they don't address users, images, and other less visible "infrastructure" data.
The basic strategy for moving your wiki is as follows:
- Back up the source wiki's page data.
- Back up the source wiki's media files.
- Copy the backup files to your new server.
- Import the page data into the destination wiki.
- Import the media files into the destination wiki.
These steps assume the following:
- You have already created a new, empty wiki on the destination server. (See "configuring multiple MediaWiki instances on a single host.")
- You have root access on the new server.
- You know how to use basic Linux tools, such as "cd", "scp", etc. (If you don't know how to use these, you have no business attempting to move a wiki!)
If these assumptions are not valid, this guide may not be right for you, or you might need to improvise a different solution. These steps were verified on an Ubuntu 10.04 LTS (32 bit x86) system. If you are using something different, some adaptation may be necessary.
Step 1: Back up the source wiki's page data.
In this step, we will dump the source wiki's database to a file that we can later use to recreate the database. Before we can do this, however, we'll need to know a few things about how your old wiki accesses its database. The essential database parameters are listed in the table below.
| item | variable name | example value |
|---|---|---|
| your wiki's database name | $wgDBname
|
wikidb |
| your wiki's database username | $wgDBuser
|
wikiuser |
| your wiki's database password | $wgDBpassword
|
wikipassword |
You can find these parameters in your wiki's main configuration file, LocalSettings.php. Look for the PHP variables named in the table. After you have found the parameters, substitute them into the following command and execute it:
mysqldump -u wikiuser -pwikipassword wikidb -c > wikidb.sql
If you prefer not to enter your wiki's database password on the command line, leave the "-p" option but omit the password, and you will be prompted.
After this command has successfully connected to your database, there is a chance it will fail with the following error message:
- mysqldump: Got error: 1044: Access denied for user 'wikiuser'@'localhost' to database 'wikidb' when using LOCK TABLES
If this happens, add the option "--skip-lock-tables" to the mysqldump command, just before the ">" character:
mysqldump -u wikiuser -pwikipassword wikidb -c --skip-lock-tables > wikidb.sql
If all goes well, you will not see any output, but a new file, wikidb.sql, will be created. Feel free to explore this file. You'll find that it is filled with SQL commands capable of building and repopulating an exact replica of your wiki's MySQL database.
Depending on the size and age of your wiki, this file might be huge. Fortunately, the data inside is also highly compressible. Use the following command to compress the file:
gzip wikidb.sql
Then move wikidb.sql.gz to a suitable location for backup files.
Step 2: Back up the source wiki's media files.
Now that you've backed up the database, the next step is to back up the media files. The MediaWiki software engineers decided that images would be more efficiently stored and retrieved as regular files in the file system, rather than as BLOBs in the database. Because of this, backing up the database does not back up the entire wiki. You also need to back up the images, and any other externally stored media.
Your source wiki most likely stores its images in a folder directly under the wiki's base folder, probably in a folder called "images". Determine your wiki's base folder and media folder, and adapt the following commands as necessary.
cd wiki tar czvf images.tgz images/
That's it. Pretty easy, right? Now move images.tgz to a suitable location for backup files.
Step 3: Copy the backup files to your new server.
You've backed up your database and your images. The next step is to move the backup files to your new server. (Obviously, if you are simply moving your data to a new wiki on the same server, you can skip this step.)
To move the two backup files, use any technique available to you for transferring files. My preferred technique is secure copy:
scp wikidb.sql.gz images.tgz sharky@newserver:.
Once again, you will want to adapt this command as required for your own namings.
Step 4: Import the page data into the destination wiki's database.
We've backed up the old wiki's data and copied it over to the new server. Now it's time to begin importing the data into the new wiki.
Open a terminal on the destination server and change into the folder containing the backup files. Adapt and execute the following command:
gunzip -c wikidb.sql.gz | sudo mysql -C -p wikidb
This command simultaneously decompresses the database backup file and replaces your new wiki's database with its content.
The second "wikidb" is the database name of the wiki on the new server. Hopefully, you chose this name and already know what it is. If you need to look it up, you can find it in the destination wiki's LocalSettings.php file. Look for the variable named $wgDBname.
You may have noticed that the command on the right side of the pipe is run with root privileges. This is necessary because the pop script contains table drop commands that the wiki's unprivileged user cannot execute.
The alternative to using sudo is to run the mysql command as any MySQL user that has all the permissions necessary to drop and repop all the tables in the new wiki's database. That's probably the more proper way to do it; I'm just lazy and choose to do it this way, because I can. It's quick, it's painless, it works, and I have root. :-) If you know a better way, please let me know about it, and I'll add your trick to this article.
Step 5: Import the media files into the destination wiki.
You've restored your page data from your old wiki into your new wiki, but you still need to restore the images.
Begin by copying your image backup file (images.tgz) into your new wiki's base folder. Then, using a terminal, cd into the base folder and issue the following command:
sudo tar xzvf images.tgz
The output of this command will be the path of each image you're restoring. If your wiki has quite a few images, you may not want to see all this. You can suppress this output by removing the "v" option from the tar command.
In the command above, you need sudo because the images your restoring, as well as the images folder you're restoring them to, may have different ownership than the account you're logged in as.
Now the next part is a little tricky. If you got lucky, no action is necessary. However, if the Linux IDs for user www-data and group www-data are not the same on the old and new servers, you'll need to fix some file ownerships in the files you just restored. You can do this with the following command:
sudo chown -R www-data.www-data images
This step is necessary because it is the Apache server, with the Apache server's permissions, that manipulates the files in your new wiki's images folder.
After you have executed the command, cd into the images folder and examine the permissions. Make sure that all files and folders under images have the owner and group set to www-data.
Step 6: Enjoy!
That's it! You're all done! In five fairly simple steps, you have backed up your old wiki and used the backup files to populate a new one. If all went well, your new wiki is now a perfect clone of your old wiki. But don't take my word for it; make sure you test your new wiki thoroughly. If something seems wrong, review the "afterthoughts" section.
At this point, if you have tested your new wiki and verified that all is well, feel free to clean house by deleting the two backup files, or by moving them to a safe place.
afterthought: transferring customizations
This guide did not address backing up the actual MediaWiki software, or your wiki's settings file, because we began by assuming you already had a working, empty wiki on the new server. There is also a strong likelihood that when you built your new, empty wiki, you selected at least one or two settings that were different from your old wiki's settings. After all, you were probably upgrading.
If you have done anything to customize the behavior of your old wiki, then you'll probably need to copy most of those custom settings into the new wiki. Generally, these customizations are stored as changes to your wiki's LocalSettings.php file, usually appended to the end of the stock file. I recommend against copying the whole file blindly, as there are some settings determined during wiki initialization that are not very portable.
Another thing to consider is the extensions folder. If you find that your new wiki shows only blank pages, or you get strange errors, it may be because extensions were not properly considered during the wiki move. Your old wiki may depend on certain extensions that were available on the old server. To preserve extension-specific behavior in the new wiki, you should ensure that the new server has all the extensions available that were enabled in your old wiki.
The handling of these issues is left as an exercise to the wikimaster. I don't feel too terrible about this, because you're probably the geek who customize your old wiki in the first place! If I'm right, I doubt you'll have any trouble re-enabling the same customizations. I just wanted to mention it here in case you forgot. Good luck!
