Help?

Help:Upgrading the TextBook Installation

From Textpattern CMS User Documentation

The TextBook wiki is highly customized from the Monobook skin that comes with MediaWiki out-of-box. Although you should be able to follow MediaWiki's docs for upgrading a wiki installation, it might be best to use the tried-and-true method below just to make sure. We certainly do not want to lose all the hard work gone into making TextBook as unique and effective as it is.

Contents

Back-up

Before you do anything else, always back-up the wiki file tree on the server, and back-up the database (create a dump file). If the upgrade implodes, you can re-add the file tree and database to recover.

Server-side Requirements (a heads-up)

Starting with MW v1.12.0 it has become necessary to include certain PHP modules beyond the minimum that used to work. See the instructions for this on a Joyent server. (This is done currently, no need to bother.)

Theoretically, MW could require other enhancements in future versions, so it pays to be vigilant to such possibilities. Please add notes here if you discover such things in the future.

Safeguarding Wiki Configurations

When MediaWiki updates, it essentially rewrites the primary LocalSettings.php file, which is also where wiki owners make customizations. If you don't safeguard your mods over time, you risk accidentally losing them on a given upgrade. To prevent this we use strip out all the good mods from the LocalSettings.php file itself and include them in via an include file that MediaWiki knows nothing about. This goes ab bottom of LocalSettings.php:

require_once('/usr/home/textbook/public_html/textbookSettings.inc');.

Now it makes no difference if the upgrade is from one version to the next or a large jump between versions, the mods are safe and you only need to run the installer.

Core Upgrade

Different approaches may be required depending on the jump your doing. First and foremost always follow the MediaWiki intructions for updgrading and then apply TextBook protocols accordingly.

Effective Installer Approach

Worked when going from 1.9.3 to 1.13.1.

  1. Download the latest stable version from MediaWiki and unpack it locally.
  2. On the TxB server, Rename LocalSettings.php to LocalSettings.old.php
  3. Make the config directory writable by the web server
  4. Make sure the database user has full rights to the database
  5. Copy the new file tree from local to live.
  6. Start the installer by browsing to wiki's front-office default, http://docs.textpattern.com (or whatever it currently is).
    Fill in the form fields with the same values as was done during the previous version's installation (see your backup version of LocalSettings.php if you are not sure). When the installation process starts, the script will detect existing MediaWiki tables, and upgrade their schema. When this is complete, a new LocalSettings.php will be generated at config/LocalSettings.php.
  7. Delete the new configuration file
  8. Rename LocalSettings.old.php back to LocalSettings.php, but ensure there's nothing new missed from the new installation's version sitting in config/LocalSettings.php to that of the old version or the TextBook's safeguard file, LocalSettingsMods.php.
  9. Restore permissions on the config directory
  10. Clean the skins folder. Go into the skins directory and delete...
    • all named skin folders except for "textbook" and common ("common" is required for various features/functions to work)
    • all named skin php files except for TextBook.php

Command-line Approach for Intra-release Upgrades

Upgrades within the same major version (for example 1.5.2 to 1.5.3) do not typically require any database changes so for the most part it's just a matter of replacing files. The instructions assume you are at /home/textbook/public_html/.

Contrarily, upgrading between major version, e.g., 1.5.3 to 1.6, can mean changes to database are necessary. Be sure to see MediaWiki's official upgrading docs on the matter.
  1. Get the archive for the version you will be upgrading to from MediaWiki.org, and place in _inactive-wiki-files/mediawiki-versions/.
  2. Extract the new archive tar -xzvf mediawiki-x.x.x.tar.gz.
  3. Edit index.php so that it doesn't redirect to the wiki and spits out a maintenance message (uncomment the first line and comment out the header directive)
  4. Save a sql dump just in case. You will have to do this from phpMyAdmin without using compression for it to work. MySQLAdmin hates us for some reason.
  5. Backup the current installation to _inactive-wiki-files/textbook_versions_old/   tar -czvf _inactive-wiki-files/textbook_versions_old/wiki-x.x.x.tgz wiki/
  6. Copy the new distribution over the old wiki install cp -rf _inactive-wiki-files/mediawiki_versions/mediawiki-x.x.x/* wiki
  7. Test that the version took by going to Special:Version
  8. Upload and compress your SQL dump to _inactive-wiki-files/textbook_DB_backups/   gzip -9 textbook-ugrade-date.sql

Command-line Approach for New Version Upgrades

Major version upgrades require changes to the Database which makes things more complicated. Normally there is an upgrade.php script that can be run from the command line but has not worked in the past with TextBook.

A new textbook_test database has been setup for safely testing the databse upgrades without affecting the live environment. See help:Wiki Testing Prior to Upgrades and Modifications for this approach.

Alternatively, you can do the Effective Installer approach described earlier in this article, which also takes into account any database upgrades required by MW.

Extensions Upgrades

Each upgrade runs the risk of extension not working until they too are updated in parallel. Nevertheless, it's necessary to check each extension to see if there is a new versions and walk through the steps to update them.

Currently Used TextBook Extensions

(coming)

Process for Updating Extensions

(coming)

Retrieved from "http://www.textpattern.net/wiki/index.php?title=Help:Upgrading_the_TextBook_Installation"
Translations [?]