comparison docs/README.migration @ 0:77665d8e2254

tag of nonpublic@localhost--archive/moin--enterprise--1.5--base-0 (automatically generated log message) imported from: moin--main--1.5--base-0
author Thomas Waldmann <>
date Thu, 22 Sep 2005 15:09:50 +0000
children f4a9643a24de
equal deleted inserted replaced
-1:000000000000 0:77665d8e2254
1 1.2 to 1.3 migration docs
2 =========================
4 Migration from 1.2 to 1.3 is done by those basic steps:
5 1. make a backup
6 2. install new moin code
7 3. install new moin.cgi (if you use CGI) or other glue script
8 4. install new moin static data (css, icons, etc.)
9 5. convert your 1.2 data_dir using the migration scripts (see below)
10 6. fix your configuration (begin with new sample config and modify as needed)
11 * especially make sure that data_dir and data_underlay_dir is correct
14 1. Making a backup
15 ==================
16 Make a backup of your current stuff:
17 * CONFIG:, maybe also some farmconfig if you run a wiki farm
18 Also backup the moin.cgi script (if you use CGI) or other glue script.
19 * CODE: backup your MoinMoin/ directory (see sys.path.append at start of
20 moin.cgi or standard location like /usr/lib/python2.x/site-packages)
21 * DATA: backup your data/ directory (see data_dir in -
22 this is the most important stuff: your wiki pages, your wiki user accounts
23 etc. - you want to keep this for quite a while even if the migration looks
24 successful.
27 2. + 3. + 4. Install new moin code, new moin.cgi script, new moin static data
28 =============================================================================
30 See INSTALL.html.
33 5. Converting your data/ directory
34 ==================================
36 Scripts see MoinMoin/scripts/migration/ (in your MoinMoin code
37 directory, e.g. /usr[/local]/lib/python2.x/site-packages/MoinMoin).
39 Those are some scripts that convert your wiki data to the current MoinMoin
40 version. You must use them AFTER stopping your old wiki code and BEFORE
41 starting your new wiki code.
43 Make sure you have enough free space on your hard disk (every mig script makes
44 a new copy, so you need N+1 times the space your data dir needs, if you do not
45 remove the pre-migX dirs after running migX script).
47 When upgrading, choose your entry point depending on your version:
49 version you use start with mig script
50 ---------------------------------------------
51 before 1.2 first upgrade to 1.2.4 and test for a while
52 1.2.x mig01 - check from_encoding in script!
53 1.3 <patch-78 mig02
54 1.3 <patch-101 mig03
55 1.3 <patch-196, =beta2 mig04
56 1.3 <patch-221, =beta3 mig05
57 1.3 <patch-248 mig06 - check from_encoding in script!
58 1.3 <patch-275, =beta5 mig07
59 1.3 <patch-305, =beta6 mig08
60 1.3 <patch-332, =beta7 mig09
61 1.3rc1 -
62 any later mig10
64 Modifying from_encoding setting in the scripts is necessary if your old moin
65 installation did not use iso-8859-1 encoding (as it was the default in moin
66 1.2.x and before. If you had changed that, e.g. to utf-8 or other encoding
67 (see, charset = '...'), you need to change it in the mig
68 scripts, too.
70 Of course, in the end you must have run ALL mig scripts once, in correct
71 order, the table is only to help your memory in case you forgot what you
72 have done already.
74 To start, copy your data/ directory to the directory where the migration
75 scripts are located and then start with the script according to the table
76 above and also run ALL scripts with a higher number - one after the other,
77 in ascending order.
79 After that, you should have a data/ directory suitable for new moin version.
80 Maybe some stuff that didn't need conversion is missing, see the comments on
81 top of the scripts for details.
83 Read the comments in the scripts for details, especially in mig5.
85 After conversion, maybe rename your old data/ dir in the original location to
86 data.12 (or similar) and copy your new data/ directory from the scripts
87 directory to that original location. Check permissions as the conversion
88 scripts have changed them (on UNIX: mode, owner, group, fix by chown -R and
89 chmod -R).
91 Note that the migration scripts only convert your data, they do NOT magically
92 convert your plugin scripts to new APIs of moin 1.3. So if your plugins do not
93 work any more, look out for updates compatible with 1.3.
95 Furthermore, they do not convert macro calls or other wiki markup which broke
96 because the parser was changed to conform to the documentation more intensely.
97 Especially check the calls to the search macros and look at HelpOnSearching.
100 6. Fix your configuration
101 =========================
103 1.3 configuration looks similar, but works quite different than 1.2 config.
104 1.3 uses a class based configuration, the easiest way to convert is maybe to
105 start from a fresh sample config and change it to fit your needs.
107 Please be careful about indentation, keep it the same way as in the samples!
108 If you add additional config items, indent them by the same amount.
110 Especially make sure that:
111 * data_dir is really pointing to your converted data directory
112 * data_underlay_dir is pointing to your underlay directory (just use a copy
113 of the directory underlay/ in the moin distribution)
114 * both directories have appropriate user, group and mode so that moin is
115 able to access them.
117 See also HelpOnConfiguration page.
120 7. FAQ
121 ======
123 Q: Wiki works, but it looks extremly simply styled. All simple blue text,
124 no icons, all menu items look like simple text aligned to left border...
126 A: Access to /wiki is not working.
127 Try accessing http://.../wiki/modern/img/moin-edit.png, that should show a
128 small icon.
129 Check your /wiki alias, web server configuration, file system rights
130 directory where /wiki points to, etc. - see web server log for more info.
132 Q: I see a wiki, looks ok, but all pages are empty. I can't even create new
133 pages.
135 A: This usually happens with an empty data/ directory and a non-working
136 underlay directory. Check underlay_data_dir config.
138 Q: I only see my own pages, but no RecentChanges. I can't create new pages.
140 A: This is also a non-working underlay dir, see previous question.
142 If your question isn't answered by above FAQ, maybe just re-check following
143 items:
144 * file system access rights. user, group, mode - can the running web server /
145 moin code access all stuff needed?
146 * is your web server allowed to access the "/wiki" directory with img and css?
147 Some web server default configurations disallow access to most directories
148 and you have to explicitely allow by a <Directory ...> section.
149 * is your web server allowed to read and execute moin.cgi? Can you run another
150 cgi script from same directory? Options +ExecCGI for Apache?
151 * Is your Python at least v2.2.2?
153 If you still have problems, it is best to ask on our IRC channel #moin on
154 server