The Road to 1.6
Updating from MoinMoin 1.5.x to 1.6.x
(see also: Upgrading from 1.6 to 1.7 instructions)
These instructions may be useful if you have an existing MoinMoin 1.5.x installation you want to upgrade to MoinMoin 1.6.x. First, realize that you must read the MoinMoin CHANGES document so that you know what changes (for example, between Moin 1.5.7 and Moin 1.6.3) affect you - you will probably need to change your configuration files to update them with new parameters and/or changed parameter names. In addition, as described in the README.migration, you will need to run a script to migrate your existing wiki data, edit an output file, and run the script again to completely migrate your data to the new 1.6.x format.
These migration instructions are similar for all platforms, however my example was performed on Windows. Below is my exact configuration (for comparison's sake):
- Windows operating system
MoinMoin with Apache (instructions)
FastCGI (instructions)
Domain authentication via mod_sspi.dll (instructions)
Python 2.5 and MoinMoin directories installed on D:\ drive.
Before You Begin
- Make sure you have a good backup of your data and configuration, and make sure you have verified that the backup is complete and usable. On Debian Linux, you should back up the following:
/path/to/your/wiki/instance
/usr/lib/pythonX/site-packages/MoinMoin with pythonX, depending on your Python version
/usr/share/moin
Check the CHANGES file to see what changes you need to make to your configuration files (wikiconfig.py, farmconfig.py, moin.cgi, etc.). The location of this file may differ depending on how you have installed MoinMoin - using a Linux RPM, for example, this file can be found in /usr/share/doc/moin-version.
Test the migration process on a test platform (I suggest a VMware or VirtualBox virtual machine). It may take several passes before you understand how to perform a successful upgrade.
Phase 1 - Installing the 1.6 Infrastructure
While there are brief instructions in the docs\README.migration file, most of the real hints are in the docs\CHANGES file (both found in the expanded moin-1.6.x install folder).
Install MoinMoin 1.6.x onto your existing MoinMoin:
From the command-line prompt, run something similar to d:\python25\python d:\moin-1.6.0\setup.py install (changing the paths to match your setup, of course).
Replace the moin.cgi (or moin.fcg) file:
In your current moin data directory with the new one (found in D:\Python25\share\moin\server\), and make the changes to match your configuration:
In Windows case, that would be replacing the first shebang statement (#!/usr/bin/env python) with #! d:\python25\python.
In the sys.path.insert(0, '/path/to/wikiconfig') line, change to sys.path.insert(0, r'D:\moin\farmconfig.py').
Change from MoinMoin.request import RequestCGI to from MoinMoin.request.request_cgi import Request as RequestCGI.
- Save file and continue.
Modify your farmconfig.py/wikiconfig.py file:
Change the from MoinMoin.multiconfig import DefaultConfig to from MoinMoin.config.multiconfig import DefaultConfig
For authentication (note: I use Apache authentication via SSPI, your setup may vary (see HelpOnAuthentication for details), find and change the auth statement to what you need. For example, I had to change "from MoinMoin.auth import http" to "from MoinMoin.auth.http import http". You will need to change the auth method statements for other auth types, such as LDAP (and check the release notes for new parameters).
If you use the AntiSpamGlobalSolution change from MoinMoin.utils.antispam import SecurityPolicy to from MoinMoin.security.antispam import SecurityPolicy (Note: Moin 1.6 now can optionally use TextCha's, which so far is more effective at preventing spam. You may want to consider switching (see also: HelpOnSpam)).
Modify FastCGI:
FastCGI has to be configured slightly differently for Windows than it does for Linux/Unix. Open the server_fastcgi.py file located in: D:\Python25\Lib\site-packages\MoinMoin\server\:
Find the second-to-last line (fcg = thfcgi.FCGI(handle_request, max_requests=config.max_requests, backlog=config.backlog, max_threads=config.max_threads) and specify the port, as configured in your Apache httpd.conf file. Following the example in the instructions, this would be Port=9001. So, your line should now read as: fcg = thfcgi.FCGI(handle_request, port=9001, max_requests=config.max_requests, backlog=config.backlog, max_threads=config.max_threads).
Phase one completed! Now test and make sure the wiki pages display. At this point, you should be able to see your pages, but you will notice a few things are broken (for example, links and macros) because of changes made to the wiki syntax.
Phase 2 - Converting Wiki Markup from 1.5.x to 1.6.x
You probably immediately noticed that some things are broken. For example, links are now marked up differently, and macros are now called <<macro>> from the old [[macro]]. The next phase is to run the migration scripts to auto-convert most stuff (pre/parser sections are not modified).
Upgrade System and Help pages:
Based on syntax changes, you need to upgrade the underlay directory. Copy new underlay folder from D:\Python25\share\moin\ to d:\moin\, replacing the old folder.
Run migration script
As described in the docs\README.migration file, run the migration script command from the Windows commandline. For Windows, this would be similar to this: d:\python25\python D:\python25\Lib\site-packages\MoinMoin\script\moin.py --config-dir=d:\moin --wiki-url=server.domain.com/mywiki migration data
Pay special attention to the paths to make sure they match your configuration, and note you will obviously have to change the --wiki-url= to match your server.
If you have a wikifarm, you will have to run this on each separate wiki (for example, change the --wiki-url= to mywiki2)
Example output:
- You will get output similar to below (if you don't I found it was due to configuration errors above, please review above sections carefully):
D:\>d:\python25\python D:\python25\Lib\site-packages\MoinMoin\script\moin.py --c onfig-dir=d:\moin --wiki-url=wiki.cognitivearts.com/topic migration data Calling migration script for D:\moin\projects\topic\data, base revision 1050400 Returned. New rev is 1050500. Calling migration script for D:\moin\projects\topic\data, base revision 1050500 Returned. New rev is 1050600. Calling migration script for D:\moin\projects\topic\data, base revision 1050600 Returned. New rev is 1050700. Calling migration script for D:\moin\projects\topic\data, base revision 1050700 Returned. New rev is 1050800. Calling migration script for D:\moin\projects\topic\data, base revision 1050800 Returned. New rev is 1059999. Calling migration script for D:\moin\projects\topic\data, base revision 1059999 You must first edit D:\moin\projects\topic\data\rename1.txt. For editing it, please use an editor that is able to edit UTF-8 encoded files. Carefully edit - the fields are separated by a | char, do not change this! Entries in this file look like: PAGE OLDPAGENAME NEWPAGENAME FILE OLDPAGENAME OLDFILENAME NEWFILENAME You may ONLY edit the rightmost field (the new name - in case you want to rename the page or file). After you have finished editing, rename the file to D:\moin\projects\topic\data\ rename2.txt and re-issue the moin migrate command. Final mig script reached, migration is complete. Moin
Fixing spaces
Note the message in the migration script output - contrary to the last line, the migration is not quite finished. Now you must edit any page or file names that need to be changed in the rename1.txt file that the first pass of the migration script produced. Since MoinMoin no longer treats space and underscores as the same, the migration script finds everything with spaces/underscores and writes it out to the rename1.txt file. Carefully review this file and fix the page or attachment names to reflect what you really want to see (e.g. some page named "This_is_a_page_with_blanks" should be named "This is a page with blanks", while a file "example_image.png" should better stay as is).
Run migration script, again
Now rename the file to rename2.txt and re-run the last command (d:\python25\python D:\python25\Lib\site-packages\MoinMoin\script\moin.py --config-dir=d:\moin --wiki-url=server.domain.com/mywiki migration data). If everything came back clean, congratulations!
- ...if not: a backup containing the unconverted data (wiki-pages) is created during this main migration step in a folder named "data.pre160". Thus, if this migration step fails you can easily recover: First fix the problem, then delete the half-finished data-folder that is created and rename the backup folder from "data.pre160" to "data". Then re-run the migration command again.
Third-party macros?
If you have any third-party macros installed, you will want to find those pages and make sure they still work. In some cases, you may simply need to edit the page so that the macro is now called by the new syntax (<<macro>>), others may need their code updated. In any case, you should go to the MoinMoinExtensions page and check for updates to your macro.
If you passed all the steps above, CONGRATULATIONS!
Troubleshooting Migration Problems
If you did not succeed with the upgrade, and you are still receiving errors, check whether you have:
- Updated all code in your wikiconfig.py, farmconfig.py, moin.cgi files with the appropriate new code and new parameters (for example, as mentioned above, authentication methods have changed, so code needs to be updated there, common parameters like url_prefix changed to url_prefix_static, etc.)
- Removed all scripts containing old code (for example, if I was using a 1.5.x version of the sinorca4moin theme, and did not update my theme scripts to 1.6.x-compatible versions, this may create errors about import methods)
- Removed all cached data from the wiki's /data/cache subdirectories, as well as cached data from your browser
Updated your Web server's virtual host file with any needed changes (for example, a change from url_prefix=/wiki to url_prefix_static=/moin_static163 means your Apache Alias must change as well)
A file named "meta" in your wiki's /data directory. If you do not have this file, you may see an error with the text KeyError: 'data_format_revision', and the migration script will not complete successfully. If you do not have this file, read README.migration (152_to1050300.py).
Once you're done, the fun isn't over! Now you get to upgrade to 1.7! See my Upgrading from 1.6 to 1.7 instructions