Archive:Installation 1.1

This page describes how to install Semantic MediaWiki 1.1 after having downloaded it (see the bottom of this page for other versions). Installation notes change from version to version. The file INSTALL shipped with SMW contains instructions for the particular vrsion you may have downloaded. This page usually applies to the latest release of SMW.

For installing SMW, please check the exact requirements and follow the instructions carefully. The installation does no irreversible changes to your MediaWiki database (it just adds some tables that can be deleted again). However, there is currently no automated process to remove annotations from articles texts in the case that Semantic MediaWiki is to be uninstalled again, but one could achieve this with some script that eliminates annotations on editing.

Disclaimer
Make sure you understand the legal disclaimer in the file COPYING.

Requirements

 * MediaWiki 1.11.* or greater (tested from 1.11.0 to 1.13alpha (r33087)).
 * PHP 5.x or greater installed and working
 * MySQL >= 4.0.14 (version required by MediaWiki)

Notes:
 * SMW currently has experimental Postgres support. Testing and bug reports welcome.
 * SMW uses the PHP mb_* multibyte functions such as mb_strpos in the php_mbstring.dll extension. This is standard but not enabled by default on some distributions of PHP. See the PHP manual for details
 * SMW creates and alters temporary tables on the fly for certain semantic queries. To do this, your wikidb user must have privileges for CREATE TEMPORARY TABLE, DROP TEMPORARY TABLE, and ALTER TABLE. The according feature can be disabled by adding $smwgQSubcategoryDepth=0; and $smwgQPropertyDepth=0; to Localsettings.php.

Installation
If you upgrade an existing installation of Semantic MediaWiki, also read the remarks in the section Notes on Upgrading below! Installing SMW basically requires three easy steps:

'''(1) Copy files. ''' Extract the downloaded archive, or check out the current files from SVN to obtain the directory "SemanticMediaWiki" that contains all relevant files. Copy this directory to "[wikipath]/extensions/" (or extract/download it to this place). We abbreviate "[wikipath]/extensions/SemanticMediaWiki" as "[SMW_path]" below.

'''(2) Enable the extension. ''' Insert the following two lines into the file "[wikipath]/LocalSettings.php":

include_once('extensions/SemanticMediaWiki/includes/SMW_Settings.php'); enableSemantics('example.org');

where example.org should be replaced by your server's name (or IP address).

(3) Perhaps '''Adjust namespaces. ''' Semantic MediaWiki uses six additional custom namespaces. By default their indices start at 100. If you have added your own custom namespaces, then you have to set the variable $smwgNamespaceIndex in LocalSettings.php before including SMW_Settings.php. See the documentation in SMW_Settings.php for details. If you add more namespaces later on, then you have to assign them to higher index numbers than those used by Semantic MediaWiki.

Semantic MediaWiki only evaluates semantic annotations in some namespaces. For example, by default it ignores semantic annotations in talk pages. If you want to change the namespaces with annotations (likely if you have added your own custom namespaces), then you have to change the array variable $smwgNamespacesWithSemanticLinks in SMW_Settings.php.

'''(4) Setup database. ''' In your wiki, log in as a user with admin status and go to the page "Special:SMWAdmin" to do the final setup steps. This can also be done with a command-line PHP script. See [SMW_path]/maintenance/README for details.

If you are using a PostgreSQL database, install the needed database objects by importing the script "maintenance/SMW_Postgres_Schema.sql" using the psql utility as follows:

psql -U wikiuser -d wikidb -f maintenance/SMW_Postgres_Schema.sql

Replace with your username and database, and use a -h hostname or -p port as needed.

Testing your Installation
If you are uncertain that everything went well, you can do some testing steps to check if SMW is set up properly.

Go to the Special:Version page and you should see Semantic MediaWiki (version nn) listed as a Parser Hook and several wfSMWXxxx functions listed as Extension Functions.

Create a regular wiki page named "TestSMW", and in it enter the wiki text

Property test: testproperty::Dummypage

when you preview and save the page, the SMW "Factbox" should appear showing the Testproperty and Dummypage both as links. If you don't get these results, check the steps in the Installation section, consult the FAQ section, then contact the user support list (see the Contact section).

Running SMW on older versions of MediaWiki
In general, it is not recommended to run older versions of MediaWiki, since every new release brings also security fixes. If your site is still running on PHP4, SMW is not supported. It would hardly be possible to backport the code to the old PHP version. If you have PHP5 but an older MediaWiki version, additional patches/modifications might be needed. Download an older release of SMW and have a look at the included INSTALL instructions to find out whether other changes are recommended therein.

Notes on Upgrading
The following sections describe how to upgrade from earlier versions of SMW. In general, it is always a good idea to go to Special:SMWAdmin and to press the setup button again. Generic instructions that should be able to restroe almost any wiki to a working SMW site are given in the section General Upgrading Instructions.

Upgrading from SMW 1.0 and SMW 1.0.1
No specific actions are required to run the wiki, but you should go once to Special:SMWAdmin for minor updates in the database, and maybe for using the new SMW registration service.

Upgrading from 1.0 RC1, 1.0 RC2, 1.0 RC3
Following the generic upgrading instructions is recommended in any case. Moreover, some configuration options have changed slightly between release candidates. Currently these are:


 * $smwgQEqualitySupport now is no longer true/false, but one of SMW_EQ_NONE, SMW_EQ_SOME, SMW_EQ_FULL
 * $smwgQDefaultNamespaces is now NULL by default, so that all namespaces are queried. The old default was "array(NS_MAIN, NS_IMAGE)".
 * $smwgQDefaultLinking now defaults to 'all' such that all query results are linked. This is not a performance issue any more. The old default was 'subject'.

If you set any of these parameters in your LocalSettings.php, you need to update the config. Please see SMW_Settings.php for more documentation on the available parameters.

Upgrading from version 0.7
The below generic steps are strictly necessary, and suffice to get a wiki that basically works. However, some further steps are strongly suggested. SMW1.0 mainly introduced the following incompatible changes to SMW0.7:

(a) The concepts (and namespaces) "Relation" and "Attribute" are now unified into "Property"

(b) The special property "Main display unit" is obsolete, and the property "display unit" shows slightly modified behaviour.

(c) The configuration options in LocalSettings.php have changed.

For (a), the namespace "Attribute:" was renamed into "Property:" – you will find all your former attribute pages in the new place. All SMW-generated property links now point to "Property", and thus work for your former Attributes. But the former Relations are still in their old namespace nd need to be moved. SMW provides the maintenance script SMW_unifyProperties.php for this purpose.

Instructions:
 * 1) Install SMW_unifyProperties.php as described in [SMW_path]/maintenance/README
 * 2) Run "php SMW_unifyProperties" and follow its progress.

The script moves all Relation pages to the according Property page. Problems occur if you had Attribute and Relation pages of the same title. It will report in which cases this occurred and leave it to you to clean up the merged pages. You can also run the script with option "-c" to get an overview of the conflicts, e.g. to delete undesired pages first. The script can be run safely more than once.

In addition, you should run the MediaWiki maintenance script "refreshLinks.php" so that old links in SMW Factboxes are refreshed to point to Property: instead of Relation:/Attribute:.

For (b), all (property) pages using properties "Main display unit" and "display unit" should be updated: delete these annotations and use a single annotation " display units::... " instead. Its value is the list of units you like to have diplayed, separated by ",". See the docu for details. Running SMW_refreshData.php again (once) is required to reliably propagate the updated property setting to all pages.

For (c), please consult the file [SMW_path]/includes/SMW_Settings.php to find out about the current options, and use only those in your LocalSettings.php (using older options will not hurt, but has no effect). Note that some options have just changed labels, while others were added or removed.

Upgrading from version 0.6 or 0.5
It should in principle be possible to delete (move away) SMW, install a fresh SMW version, and run all updates as in the case of SMW0.7. Patches to MediaWiki (known before SMW0.7) are no longer required. Note that this upgrade has not been tested. An alternative would be to upgrade to SMW0.7 first, and to move on to a current SMW next.

Upgrading from 0.4.x
Upgrading should work like for versions 0.6 and 0.5. The type "Geographic area" and "Geographic length" are no longer built in. But you can easily create them by yourself with the new type customisation features. See the current docu on that site.

General Upgrading Instructions
All SMW data is extracted from wiki pages, and SMW offers an easy way of recreating all internal data from the current wiki pages. Basically, this could be done by executing Special:SMWAdmin as during the installation, and by newly saving all wiki pages afterwards. Since the latter would be rather cumbversome, SMW provides a maintenance script for refreshing all data: SMW_refreshData.php reads all pages and recreates their semantic data.

Instructions:

(0) Read the rest of this section first.

(1) Install the new SMW version as described above.

(2) Install SMW_refreshData.php as described in [SMW_path]/maintenance/README

(3) Login to your server, and change directory to [wikipath]/maintenance

(4) Run "php SMW_refreshData.php -pv" and follow its progress.

(5) Run "php SMW_refreshData.php -v" and follow its progress.

(6) Run "touch [wikipath]/LocalSettings.php" to make sure that no cached old versions of wiki pages are used in the wiki.

Since the databse updates can take a long time, it might be better to perform them via an SMW maintenance script as well instead of using Special:SMWAdmin. The according script is called SMW_setup.php. In case of problems, retry the above procedure with the modified command "php SMW_refreshData.php -fpv" in step (4).

Some versions of SMW also introduced incompatibilities in the wiki syntax that may need to be fixed. You may want to read this first.