PowerTools Documentation: Index | MediaWiki

## 1 MediaWiki

MediaWiki is an GPL wiki engine available at http://wikipedia.sourceforge.net/.

### 1.1 Manual Install

This is mediawiki's manual install procedure (as I figured out) for a site on Ensim Pro server.

1. Add mysql db: <dbname>

2. ssh admin@site.com

3. cd /var/www/html

4. wget http://voxel.dl.sourceforge.net/sourceforge/wikipedia/mediawiki-1.3.9.tar.gz

5. tar zxvf mediawiki-1.3.9.tar.gz

6. mv mediawiki-1.3.9 <install_dir>

7. chmod a+w <install_dir>/config; chmod 0777 <install_dir>/images

8. Follow installation wizard

- Here mediaWiki require user to input following values

  1. Sitename
  2. EmergencyContact
  3. LanguageCode
  4. License
  5. SysopName
  6. SysopPass
  7. SysopPass2
  8. DBserver
  9. DBname
  10. DBuser
  11. DBpassword
  12. DBpassword2

9. mv <install_dir>/config/LocalSettings.php <install_dir>

10. chmod a-w <install_dir>/config

### 1.2 List of inputs required from SA

This list is required while writing dsp.xml which mainly is responsible for the rendering DSP install, reconfigure screens.

- DSP Install location
- Tooladmin name (SysopName)
- Tooladmin Password
- MySQL DB name (DBname)
- MySQL DB password (DBpassword)

### 1.3 Creating DSP source tree

Extract the powertools source arhive.

    tar jxvf powertools.tar.bz2

Create top level DSP directory which will contain subdirectories for the DSP versions

    mkdir -p lwp_si_packages/mediawiki/1.3.9 # DSPName/DSPVersion

Now we should download and copy the tool logo to DSP version directory.

    cd lwp_si_packages/mediawiki/1.3.9 # Inside source tree
    wget http://wikipedia.sourceforge.net/Mediawiki.png
    convert Mediawiki.png -resize 40%  mediawiki.gif

Create a makefile include.mk for this DSP. The DSP for mediawiki looks as below.

    shortname := mediawiki
    name := Media Wiki
    version := 1.3.9
    lib_files := dsp.xml msgs.list
    raw_lib_files := mediawiki.gif
    themes := default.xsl
    source_files :=  mediawiki-1.3.9.tar.gz
    -include $(addsuffix /make_utils/dsp_common.mk,$(all_source_dirs))

Create default.xsl and msgs.list files. Here is the minimal(sufficient for most DSPs) content for these files.

#### 1.3.1 default.xsl

    <?xml version="1.0"?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
      <xsl:import href="/usr/lib/ensim/deployables/lib/themes/default.xsl"/>
      <xsl:output method="html" omit-xml-declaration="yes"/>
    </xsl:stylesheet>

#### 1.3.2 msgs.list

    #include "common_msgs.list"

### 1.4 Writing dsp.xml

Based on our analysis of required user inputs we can write dsp.xml.

dsp.xml is mainly responsible for rendering install page for given DSP. Refer this section for dsp.xml details.

    <?xml version="1.0"?>
    <dsp>
      <dspDescription>
      <shortname>mediawiki</shortname>
      <longname>Media Wiki</longname>
      <version>1.3.9</version>
      <url>http://www.mediawiki.org/</url>
      <type>Wiki</type>
      <shortDescription>wiki</shortDescription>

       <!--
            Change the dapiversion if user intervention is needed
            during the upgrade, or if the upgrade should be performed
            at the user's convenience (e.g. it will cause downtime).

            Change the dapirelease if the upgrade does not require
            user intervention.
       -->
      <dapiversion>1.5</dapiversion>
      <dapirelease>1</dapirelease>
      <!-- DSP Install location -->
      <commonOption name="domain_to_path"/>
      <commonOption name="url_net_required"/>
      <commonOption name="url_path_required"/>
      <commonOption name="url_loc"/>
      <commonOption name="install_loc"/>
      <commonOption name="username"/>
      <!--  Tooladmin name (SysopName) for mediawiki -->
      <commonOption name="instance_admin"/>
      <!--  Tooladmin password for mediawiki -->
      <commonOption name="instance_pass1"/>
      <commonOption name="instance_pass2"/>
      <commonOption name="syncfs"/>
      <commonOption name="overwritefiles"/>
      <!--  MySQL DB name -->
      <commonOption name="dbname"/>
      <!--  MySQL DB password -->
      <commonOption name="dbpass"/>
      <commonOption name="archive_name" file="mediawiki-1.3.9.tar.gz"/>
      <commonOption name="archive_type" type="tar.gz"/>
      </dspDescription>
    </dsp>

### 1.5 dAPI.py

It's time to write the most important component which defines methods for DSP life cycle management.

The first thing should be importing deployables_lib (deployables_lib.api/) module.

    import deployables_lib as dl

Although it is possible to import other python modules here try not to do that. We do not need any extra module for mediawiki.

Next we need to load msgs.

    dl.load_msgs_module("mediawiki-1.3.9", symtab = globals())

Now we need to define dAPI methods such as install, reconfigure etc.

#### 1.5.1 install

Before writing install method the programmer should have manual install procedure noted.

We should do some checks before install to make sure that install do not fail. This includes checks like quota, mysql(mediawiki requires mysql) etc.

actions is the list of actions to perform. do_install_actions method perform all the actions. The strings DSP_SHORTNAME and DSP_VERSION would be replaced to DSP's shortname and version during build.

    import deployables_lib as dl
    dl.load_msgs_module("DSP_SHORTNAME-DSP_VERSION", symtab = globals())

    def install(site, site_conf, instance_conf, msgs):
       # Some checks before install
       actions = ['resolve_location', 'check_disk_quota', 'check_mysql_enabled',
                  'check_pass', 'check_install_loc_owner', ]
       # None of above actions requires args
       args_dict = {}
       # Do all actions
       dl.do_install_actions(site, site_conf, instance_conf, msgs,
           globals(), actions, args_dict)

Once the checks are passed (msgs serveriry is not ERROR) we can proceed to create install actions list.

       # Proceed of all OK
       if msgs.get_severity() != msgs.ERROR:

To setup mediawiki following actions (in sequence) we need to take.

- db_create (deployables_lib.api/public/deployables_lib-module.html#index-db_create) (Step 1 in manual install)
- archive_unpack (deployables_lib.api/public/deployables_lib-module.html#index-archive_unpack) (Step 5 and 6 in manual install)
- handle_security_mode (deployables_lib.api/public/deployables_lib-module.html#index-handle_security_mode) (Step 7)
- exec_php_script (deployables_lib.api/public/deployables_lib-module.html#index-exec_php_script)(Step 8 in manual install)
- Note we change permissions of config directory in step 7 and reverse it in step 10 in manual install which is not required here.

    # Proceed of all OK
    if msgs.get_severity() != msgs.ERROR:
           # actions to be performed
           actions = ['db_create', 'db_probe', 'archive_unpack',
                      'exec_php_script', 'handle_security_mode','edit_conf_file', 'access_url']

Every action (optionally) has a set of arguments. We need to pass this action arguments in form of a dictionary. archive_unpack accepts dir_moves arg which implies that the directory created after unpacking of sources should be renamed (moved) to SA specified directory [step 6 in manual install]. dir_moves is a python list of such directories. We will define it outside 'install' method to make sure this list is also available to other methods.

    dir_moves = [('DSP_SHORTNAME-DSP_VERSION', '') ]

Additionally we also require to edit LocalSettings.php to set wgScriptPath parameter after exec_php_script.

Editing php configuration file require patterns for writing config data. Patterns pat and sub below solves the purpose. We will also need these variables in reconfigure, so defining these variables outside install method makes sure that they are available to all methods.

    pat = "^\s*\$(?P<key>\S+\w)\s*=\s*(?P<value>['\"].*['\"])\s*;\s*"
    sub = "$%(key)s = %(value)s;"

exec_php_script invokes the web-installer of mediawiki and passes the form variables as mentioned in it's dictionary.

For more details on supported actions and their arguments see do_install_actions (deployables_lib.api/public/deployables_lib-module.html#do_install_actions) method in deployables_lib api.

           # vars for edit_conf_file action
           install_dir = "/%s" % instance_conf['install_loc'].split('/')[-1:][0]
           conf_vars = [('wgScriptPath', install_dir)]

           # action attributes
           args_dict = {
               'archive_unpack':       {'dir_moves': dir_moves},
               'exec_php_script' : {
                       'script' : 'config/index.php',
                   'args' : {
                       'Sitename' : site_conf['siteinfo']['domain'] + ' Wiki',
                       'EmergencyContact' : 'instance_admin_email',
                       'LanguageCode' : 'en',
                       'License' : 'no license metadata',
                       'SysopName' : instance_conf['instance_admin'],
                       'SysopPass' : instance_conf['instance_pass1'],
                       'SysopPass2' : instance_conf['instance_pass2'],
                       'DBserver' : dl.get_mysql_host(site),
                       'DBname' : instance_conf['dbname'],
                       'DBuser' : site_conf['mysql']['dbaseadmin'],
                       'DBpassword' : instance_conf['dbpass'],
                       'DBpassword2' : instance_conf['dbpass'] },
                     'success_re' : '.*', },
                   'handle_security_mode' : { 'files':[('images', 0777, 0777)]},
                   'edit_conf_file': { 'file':'config/LocalSettings.php', 'lang':'php',
                               'pat' : pat, 'sub': sub, 'vars': conf_vars }
               }

Finally we will call do_install_actions (deployables_lib.api/public/deployables_lib-module.html#do_install_actions) to perform mediawiki installation.

           # now actual action(Install here)
           dl.do_install_actions(site, site_conf, instance_conf, msgs,
                                 globals(), actions, args_dict)

Now step 9 (move LocalSetting.php) and we are done with the install method.

           fst_path = dl.site_fs(site) + instance_conf['install_loc']
           dl.exec_cmd("mv %s %s" % \
           (fst_path + '/config/LocalSettings.php', fst_path + '/LocalSettings.php'))

#### 1.5.2 reconfigure

do_reconfigure_actions lets SA to change the parameters of installed DSP.

Before allow reconfiguration one need to study the possible impact of reconfigure changes and actions required for doing these changes without affecting DSP functionality.

For this example SA is allowed to change Database name and "Recover missing tool files" (wiki/index.php/DSP_Interface.htm#syncfs).

While handling database name change we also need to update DSP database and conf file LocalSettings.php in this case.

def reconfigure(context, site, site_conf, old_site_conf, instance_conf,

                   old_instance_conf, msgs):

       if context != dl.CONTEXT_SITE_EDIT and dl.mysql_installed(site_conf,
           old_site_conf):

           actions = ['db_probe','handle_url_loc', 'resolve_location',
                  'archive_unpack', 'handle_db_changes', 'handle_username_change']
           args_dict = {}
           dl.do_install_actions(site, site_conf, instance_conf, msgs,
               globals(), actions, args_dict)

           # We always require the dbpass for mediawiki, since a reconfigure
           # need to peform database updates

           if msgs.get_severity() != msgs.ERROR:
               conf_vars = [('DBname', instance_conf['dbname'])]

               args_dict = {
                   'archive_unpack': {'dir_moves': dir_moves },
                   'edit_conf_file': {'file': 'LocalSettings.php', 'lang': 'php',
                                      'pat': pat, 'sub': sub, 'vars': conf_vars }
                   }

               if instance_conf['dbname'] != old_instance_conf['dbname']:
                   sql_stmt = [ \
                     "UPDATE objectcache SET keyname = '%s:messages' where keyname \
                     = '%s:messages'" % (instance_conf['dbname'], old_instance_conf['dbname']) ]
                   actions = ['edit_conf_file', 'exec_mysql']
                   args_dict['exec_mysql'] = { 'sql': sql_stmt }

               if instance_conf['overwritefiles'] == '1':
                  actions.append('handle_security_mode')
                  args_dict['handle_security_mode'] = { 'files':[('images', 0777,
                      0777)]}
               dl.do_reconfigure_actions(context, site, site_conf, old_site_conf,
                                     instance_conf, old_instance_conf, msgs,
                                     globals(), actions, args_dict)

#### 1.5.3 remove

Code for remove method in most DSPs looks similar, mediawiki is also not an exception. Remove typically involves dropping of database and removing the DSP install directories.

    def remove(site, site_conf, instance_conf, msgs):
       dl.db_drop(site, site_conf, instance_conf) # If DSP uses MySQL
       dl.install_loc_cleanup(site, site_conf, instance_conf, dir_moves)

#### 1.5.4 get_instance_configuration

Refer the get_instance_configuration details here.

    def get_instance_configuration(context, site, site_conf, instance_conf,
                                  old_instance_conf, locale, msgs):
       instance = dl.dsp_create_instance(instance_conf['shortname'],
                                         instance_conf['version'])
       dl.dsp_fill_instance(context, instance, site, site_conf,
                            instance_conf, old_instance_conf,
                            ['dbname', 'username', 'url_net', 'url_path',
                             'domain_to_path', 'instance_admin_email'])
       dl.enable_patches(instance, instance_patches)
       return instance

Final version of dAPI.py for mediawiki is here (MediaWiki-dAPI.py.txt).

### 1.6 Build

- Now we need to add new DSP into dirs.mk so that build system would include mediawiki in build.

  (Important)See this section on how to add DSP to dirs.mk.

- Once new DSP is added to dirs.mk we will invoke following commands to build DSP rpms.

       cd lwp_si_packages
       make rpms

- Generated rpms can be found in build/RPMS/i386/ directory.

### 1.7 Handling upgrade

In this section presents an example of tasks involved in upgrade to newer version for mediawiki.

For any DSP to support upgrade includes two tasks

#### 1.7.1 Writing dsp.xml

We can use mediawiki-1.3.9's dsp.xml and modify to support upgrade.

- First modify the version element in dsp.xml to reflect newer version.

     <version>1.3.11</version>

- Add a new section <upgrades> to dsp.xml which includes the version from which this dsp support upgrade.

     <upgrades>
       <oldversion>
         <shortname>mediawiki</shortname>
         <version>1.3.9</version>
       </oldversion>
     </upgrades>

Our dsp.xml is now ready to support upgrade from mediawiki version 1.3.9.

#### 1.7.2 Defining upgrade method in dAPI.py

To handle upgrade one need to define upgrade method in dAPI.py.

Mediawiki upgrade requires unpacking of source and resetting the permissions of images directory.

We also need to set syncfs and overwritefiles keys of instance_conf to '1'. This ensures all the old php file are overwritten.

def upgrade(site, site_conf, instance_conf, old_instance_conf, msgs):

       if old_instance_conf['shortname'] == 'mediawiki' and \
          old_instance_conf['version'] == '1.3.9':
           instance_conf['syncfs'] = '1'
           instance_conf['overwritefiles'] = '1'

           actions = ['archive_unpack', 'handle_security_mode']
           args_dict = {
               'archive_unpack': {'dir_moves': dir_moves},
               'handle_security_mode' : { 'files':[('images', 0777, 0777)]}
           }
           dl.do_upgrade_actions(site, site_conf, instance_conf, old_instance_conf, \
               msgs, globals(), actions, args_dict)

Here is the complete dAPI.py for mediawiki 1.3.11 (MediaWiki-1.3.11-dAPI.py.txt).

Retrieved from "wiki/index.php/MediaWiki"