UPGRADE

   1 == The basic theory ==
   2
   3 Basically, to upgrade a wiki you:
   4 * Back up your data! (See Backups! below)
   5 * Extract the new archive. If you can do this in a clean directory that's
   6   great, but it should work to extract over the old files too. This may
   7   be easier if you have images etc in place and don't want to move them
   8   around, but remember to back up first!
   9 * Run the installer to upgrade the database schema.
  10
  11 === Web installer ===
  12
  13 You can use the web-based installer wizard if you first remove the
  14 LocalSettings.php (and AdminSettings.php, if any) files; be sure to
  15 give the installer the same information as you did on the original
  16 install (language/encoding, database name, password, etc). This will
  17 also generate a fresh LocalSettings.php, which you may need to customize.
  18
  19 You may change some settings during the install, but be very careful!
  20 Changing the encoding in particular will generally leave you with a
  21 lot of corrupt pages, particularly if your wiki is not in English.
  22
  23 === Command-line upgrade ===
  24
  25 Additionally, as of 1.4.0 you can run an in-place upgrade script from
  26 the command line, keeping your existing LocalSettings.php. This requires
  27 that you create an AdminSettings.php giving an appropriate database user
  28 and password with privileges to modify the database structure.
  29
  30 Once the new files are in place, go into the maintenance subdirectory and
  31 run the script:
  32
  33   php update.php
  34
  35 See caveats below on upgrading from 1.3.x or earlier.
  36
  37
  38 == Backups! ==
  39
  40 To upgrade an existing MediaWiki installation, first BACK UP YOUR WIKI!
  41 If something goes wrong, you want to be able to start again.
  42
  43 Your image files, configuration, etc can simply be copied or archived as
  44 you would any other files. (Make sure that the contents of your
  45 LocalSettings.php are not accidentally made public, as this contains
  46 a database password.)
  47
  48 To back up the database, use the tools provided by your service provider
  49 (if applicable) or the standard mysqldump program.
  50
  51 For general help on mysqldump:
  52 http://dev.mysql.com/doc/mysql/en/mysqldump.html
  53
  54 WARNING: If using MySQL 4.1.x, mysqldump's charset conversion may in
  55 some cases damage data in your wiki. If necessary, set the charset
  56 option to 'latin1' to avoid the conversion. Fore more info see:
  57 http://mail.wikipedia.org/pipermail/wikitech-l/2004-November/026359.html
  58
  59
  60 == Caveats ==
  61
  62 === Upgrading from 1.4beta1 ===
  63
  64 There are no database changes from beta1; just update the files.
  65
  66
  67 === Upgrading from 1.3.x ===
  68
  69 This should generally go smoothly.
  70
  71 If you keep your LocalSettings.php, you may need to change the style paths
  72 to match the newly rearranged skin modules. Change these lines:
  73   $wgStylePath        = "$wgScriptPath/stylesheets";
  74   $wgStyleDirectory   = "$IP/stylesheets";
  75   $wgLogo             = "$wgStylePath/images/wiki.png";
  76
  77 to this:
  78   $wgStylePath        = "$wgScriptPath/skins";
  79   $wgStyleDirectory   = "$IP/skins";
  80   $wgLogo             = "$wgStylePath/common/images/wiki.png";
  81
  82
  83 Note that the 1.3 beta releases included a potential vulnerability if PHP
  84 is configured with register_globals on and the includes directory is
  85 served to the web. For general safety, turn register_globals *off* if you
  86 don't _really_ need it for another package.
  87
  88 If your hosting provider turns it on and you can't turn it off yourself,
  89 send them a kind note explaining that it can expose their servers and their
  90 customers to attacks.
  91
  92
  93 === Upgrading from 1.2.x ===
  94
  95 If you've been using the MediaWiki: namespace for custom page templates,
  96 note that things are a little different. The Template: namespace has been
  97 added which is more powerful -- templates can include parameters for
  98 instance.
  99
 100 Any MediaWiki: entries that are not used by the software will be automatically
 101 moved to Template: entries at upgrade time. Be sure to go through and check
 102 that everything is working properly.
 103
 104 Also, be sure to pick the correct character encoding -- some languages were
 105 only available in Latin-1 on 1.2.x and are now available for Unicode as well.
 106 If you want to upgrade an existing wiki from Latin-1 to Unicode you'll have
 107 to dump the database to SQL, run it through iconv or another conversion tool,
 108 and restore it. Sorry.
 109
 110
 111 === Upgrading from 1.1.x or earlier ===
 112
 113 This is less thoroughly tested, but should work.
 114
 115 You need to specify the *admin* database username and password to the
 116 installer in order for it to successfully upgrade the database structure.
 117 You may wish to manually change the GRANTs later.
 118
 119 If you have a very old database (earlier than organized MediaWiki releases
 120 in late August 2003) you may need to manually run some of the update SQL
 121 scripts in maintenance/archives before the installer is able to pick up
 122 with remaining updates.
 123
 124
 125 === Upgrading from UseModWiki or old "phase 2" Wikipedia code ===
 126
 127 There is a semi-maintained UseModWiki to MediaWiki conversion script at
 128 maintenance/importUseModWiki.php; it may require tweaking and customization
 129 to work for you.
 130
 131 Install a new MediaWiki first, then use the conversion script which will
 132 output SQL statements; direct these to a file and then run that into your
 133 database.
 134
 135 You will have to rebuild the links tables etc after importing.