MoinMoin: attachment:README.migration.txt of HowTo/BeginnersLinux

   1 Converting your DATA when upgrading MoinMoin
   2 ============================================
   3 
   4 Post 1.5.3 new style migration
   5 ==============================
   6 
   7 If you are migrating from a moin version older than 1.5.3, you first you have
   8 to do all steps described in the sections below or it won't work.
   9 
  10 After you have switched to new style migration, the procedure will be the same
  11 with every moin upgrade, simply follow these steps:
  12 
  13   a) First switch to the user of your data directory (www-data normally):
  14       e. g. sudo -u www-data sh
  15       or su www-data
  16 
  17   b) Invoke the following command:
  18       moin --config-dir=/path/to/config_dir --wiki-url=wiki.example.org/ migration data 
  19 
  20       Note: If you did not use setup.py, you can call the moin script directly. It is
  21       located in MoinMoin/script/moin.py
  22 
  23 The new style mig stuff will then load the config for that wiki, get into its
  24 data_dir, read the meta file content and determine what it has to do internally.
  25 
  26 1.5.3 migration
  27 ===============
  28 
  29 First make sure you have run all the old mig scripts ONCE (and only once) on
  30 your data dirs.
  31 
  32 The old style stuff moved here: MoinMoin/script/old/migration/
  33 
  34 In that directory, there is also a new 152_to_1050300.py mig script - you
  35 need to run it as the last mig script to switch to new style mig scripts.
  36 It puts a file "meta" in your data dirs that hold the data_format_revision
  37 value. The new style mig scripts use that value to make it much simpler for
  38 you in future.
  39 
  40 After this, please continue in section "Post 1.5.3 new style migration".
  41 
  42 1.3.4/1.3.5 migration
  43 =====================
  44 We added some mig scripts in moin 1.3.4. So if you have done the 1.2 to 1.3
  45 migration with some earlier moin version (like 1.3.3), then please run the
  46 new scripts, too:
  47  * 12_to_13_mig10.py
  48  * 12_to_13_mig11.py
  49 
  50 1.2 to 1.3 migration
  51 ====================
  52 
  53 Migration from 1.2 to 1.3 is done by those basic steps:
  54  1. make a backup
  55  2. install new moin code
  56  3. install new moin.cgi (if you use CGI) or other glue script
  57  4. install new moin static data (css, icons, etc.)
  58  5. convert your 1.2 data_dir using the migration scripts (see below)
  59  6. fix your configuration (begin with new sample config and modify as needed)
  60   * especially make sure that data_dir and data_underlay_dir is correct
  61 
  62 
  63 1. Making a backup
  64 ==================
  65 Make a backup of your current stuff:
  66  * CONFIG: moin_config.py, maybe also some farmconfig if you run a wiki farm
  67    Also backup the moin.cgi script (if you use CGI) or other glue script.
  68  * CODE: backup your MoinMoin/ directory (see sys.path.append at start of
  69    moin.cgi or standard location like /usr/lib/python2.x/site-packages)
  70  * DATA: backup your data/ directory (see data_dir in moin_config.py) -
  71    this is the most important stuff: your wiki pages, your wiki user accounts
  72    etc. - you want to keep this for quite a while even if the migration looks
  73    successful.
  74 
  75 
  76 2. + 3. + 4. Install new moin code, new moin.cgi script, new moin static data
  77 =============================================================================
  78 
  79 See INSTALL.html.
  80 
  81 
  82 5. Converting your data/ directory
  83 ==================================
  84 
  85 Scripts see MoinMoin/script/old/migration/12_to_13_migN.py (in your MoinMoin
  86 code directory, e.g. /usr[/local]/lib/python2.x/site-packages/MoinMoin).
  87 
  88 Those are some scripts that convert your wiki data to the current MoinMoin
  89 version. You must use them AFTER stopping your old wiki code and BEFORE
  90 starting your new wiki code.
  91 
  92 Make sure you have enough free space on your hard disk (every mig script makes
  93 a new copy, so you need N+1 times the space your data dir needs, if you do not
  94 remove the pre-migX dirs after running migX script).
  95 
  96 When upgrading, choose your entry point depending on your version:
  97 
  98  version you use         start with mig script
  99  ---------------------------------------------
 100  before 1.2              first upgrade to 1.2.4 and test for a while
 101  1.2.x                   mig01 - check from_encoding in script!
 102  1.3 <patch-78           mig02
 103  1.3 <patch-101          mig03
 104  1.3 <patch-196, =beta2  mig04
 105  1.3 <patch-221, =beta3  mig05
 106  1.3 <patch-248          mig06 - check from_encoding in script!
 107  1.3 <patch-275, =beta5  mig07
 108  1.3 <patch-305, =beta6  mig08
 109  1.3 <patch-332, =beta7  mig09
 110  1.3rc1                  -
 111  any later               mig10
 112 
 113  Modifying from_encoding setting in the scripts is necessary if your old moin
 114  installation did not use iso-8859-1 encoding (as it was the default in moin
 115  1.2.x and before. If you had changed that, e.g. to utf-8 or other encoding
 116  (see moin_config.py, charset = '...'), you need to change it in the mig
 117  scripts, too.
 118 
 119 Of course, in the end you must have run ALL mig scripts once, in correct
 120 order, the table is only to help your memory in case you forgot what you
 121 have done already.
 122 
 123 To start, copy your data/ directory to the directory where the migration
 124 scripts are located and then start with the script according to the table
 125 above and also run ALL scripts with a higher number - one after the other,
 126 in ascending order.
 127 
 128 After that, you should have a data/ directory suitable for new moin version.
 129 Maybe some stuff that didn't need conversion is missing, see the comments on
 130 top of the scripts for details.
 131 
 132 Read the comments in the scripts for details, especially in mig5.
 133 
 134 After conversion, maybe rename your old data/ dir in the original location to
 135 data.12 (or similar) and copy your new data/ directory from the scripts
 136 directory to that original location. Check permissions as the conversion
 137 scripts have changed them (on UNIX: mode, owner, group, fix by chown -R and
 138 chmod -R).
 139 
 140 Note that the migration scripts only convert your data, they do NOT magically
 141 convert your plugin scripts to new APIs of moin 1.3. So if your plugins do not
 142 work any more, look out for updates compatible with 1.3.
 143 
 144 Furthermore, they do not convert macro calls or other wiki markup which broke
 145 because the parser was changed to conform to the documentation more intensely.
 146 Especially check the calls to the search macros and look at HelpOnSearching.
 147 
 148 
 149 6. Fix your configuration
 150 =========================
 151 
 152 1.3 configuration looks similar, but works quite different than 1.2 config.
 153 1.3 uses a class based configuration, the easiest way to convert is maybe to
 154 start from a fresh sample config and change it to fit your needs.
 155 
 156 Please be careful about indentation, keep it the same way as in the samples!
 157 If you add additional config items, indent them by the same amount.
 158 
 159 Especially make sure that:
 160  * data_dir is really pointing to your converted data directory
 161  * data_underlay_dir is pointing to your underlay directory (just use a copy
 162    of the directory underlay/ in the moin distribution)
 163  * both directories have appropriate user, group and mode so that moin is
 164    able to access them.
 165 
 166 See also HelpOnConfiguration page.
 167 
 168 
 169 7. FAQ
 170 ======
 171 
 172 Q: Wiki works, but it looks extremly simply styled. All simple blue text,
 173    no icons, all menu items look like simple text aligned to left border...
 174 
 175 A: Access to /wiki is not working.
 176    Try accessing http://.../wiki/modern/img/moin-edit.png, that should show a
 177    small icon.
 178    Check your /wiki alias, web server configuration, file system rights
 179    directory where /wiki points to, etc. - see web server log for more info.
 180 
 181 Q: I see a wiki, looks ok, but all pages are empty. I can't even create new
 182    pages.
 183 
 184 A: This usually happens with an empty data/ directory and a non-working
 185    underlay directory. Check underlay_data_dir config.
 186 
 187 Q: I only see my own pages, but no RecentChanges. I can't create new pages.
 188 
 189 A: This is also a non-working underlay dir, see previous question.
 190 
 191 If your question isn't answered by above FAQ, maybe just re-check following
 192 items:
 193  * file system access rights. user, group, mode - can the running web server /
 194    moin code access all stuff needed?
 195  * is your web server allowed to access the "/wiki" directory with img and css?
 196    Some web server default configurations disallow access to most directories
 197    and you have to explicitely allow by a <Directory ...> section.
 198  * is your web server allowed to read and execute moin.cgi? Can you run another
 199    cgi script from same directory? Options +ExecCGI for Apache?
 200  * Is your Python at least v2.2.2?
 201 
 202 If you still have problems, it is best to ask on our IRC channel #moin on
 203 server irc.freenode.net.