Help:Installation

This page describes how to install Semantic MediaWiki 1.7.0 after having downloaded it (see the bottom of this page for other versions). Installation and upgrade notes change from version to version: the file INSTALL shipped with SMW contains instructions for the particular version you may have downloaded.

To upgrade a wiki running an older version of SMW, please make sure to have read the relevant section before starting the upgrade.

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.16.0 or greater (MediaWiki 1.17.0 or greater is recommended)
• Validator extension version 0.4.13 or greater
• PHP 5.2 or greater installed and working (except for version 5.3.1)
• MySQL >= 4.0.14 (version required by MediaWiki, except for versions 5.1.49 to 5.1.52)

or PostgreSQL >= 8.3 (note that support for the latter is still preliminary and requires some extra steps, see PostgreSQL for details)

Notes

• 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.
• For installation and upgrade, SMW needs the rights to create new tables (CREATE) and to alter tables (ALTER TABLE). Both can be removed again after SMW was set up. The script SMW_setup.php can use the DB credentials from AdminSettings.php for this purpose, avoiding the need of extra rights for the wiki DB user.
• When using SMWSQLStore2 (default data store for SMW), SMW creates and alters temporary tables for certain semantic queries. To do this, your wikidb user must have privileges for CREATE TEMPORARY TABLES. The according features can be disabled by adding the following to Localsettings.php:

$smwgQSubcategoryDepth= 0;
$smwgQPropertyDepth   = 0;
$smwgQFeatures        = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY;
$smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY &
                       ~SMW_CONCEPT_QUERY;

• When using SMWSparqlStore (RDF store connector), SMW uses the CURL functions of PHP. These functions may have to be enabled/installed to be available.

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.

Installation

If you upgrade an existing installation of Semantic MediaWiki, also read the remarks in the section Upgrading existing installations below! Installing SMW basically requires three (or four) easy steps:

(1) Copy files.  Extract the downloaded archives for Validator and Semantic MediaWiki, or check out the current files from SVN to obtain the directories "Validator" and "SemanticMediaWiki" that contain all relevant files. Copy these directories to "[wikipath]/extensions/" (or extract/download it to this place).

(2) [optional] Adjust namespaces.  If you did not make any change the your wiki's namespaces, you can skip this step. If you have defined your own custom namespaces, you have to set the parameter $smwgNamespaceIndex before including SemanticMediaWiki.php. Semantic MediaWiki uses additional namespace indexes, in the range from 102 to 109. Note, 104 and 105 are only needed if $smwgHistoricTypeNamespace is set. 106 and 107 are reserved for the Semantic Forms extension and not used by SMW. See the documentation within SMW_Settings.php for details. If you add namespaces after installing SMW, then you have to assign them to higher numbers than those used by Semantic MediaWiki.

Note: 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 add the desired array for parameter $smwgNamespacesWithSemanticLinks in LocalSettings.php.

(3) Enable the extensions.  Insert the following lines into the file "[wikipath]/LocalSettings.php":

 require_once( "$IP/extensions/Validator/Validator.php" );
 include_once( "$IP/extensions/SemanticMediaWiki/SemanticMediaWiki.php" );
 enableSemantics('example.org');

where example.org should be replaced by your server's name (or IP address). This string is only used as a globally unique name for identifying the wiki's exported data on the Semantic Web, and a valid server name works very well for that purpose. There is no need to worry if a wiki has more than one server name – just pick one.

(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. Two steps are needed: at first, trigger the database setup ("Database installation and upgrade"). Afterwards, activate the automatic data update ("Data repair and upgrade"). Note that the first step requires permissions to alter/create database tables, as explained in the above note. The second step takes some time; go to Special:SMWAdmin to follow its progress. SMW can be used before this completes, but will not have access to all data yet (e.g. page categories).

Special:SMWAdmin

Storage was successfully set up

SMW was successfully tested

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:

1. Go to the Special:Version page. You should see Semantic MediaWiki (Version nn) listed in the top section "Semantic Extensions".
2. Create a regular wiki page named "TestSMW", and in it enter the wiki text

   Property test:  [[testproperty::Dummypage]]

   When previewing the page before saving, you should see a Factbox at the bottom of the article that shows your input. After saving the page, click on the link "Browse properties" in the page's toolbox. This view should show Testproperty with value Dummypage.

Upgrading existing installations

Upgrading SMW 1.6.x

Installations of SMW 1.6.* and can be upgraded by replacing the files, and by running the database update (Special:SMWAdmin or SMW_setup.php script) as usual. Moreover, it is strongly suggested to enable the refresh process to update all data on Special:SMWAdmin. Older versions of SMW can be upgraded in the same way, but there can be more feature changes that require changes of wiki pages. See the current documentation for details on using the current version.

Upgrading SMW 1.5.x

SMW 1.6.0 introduces a new software dependency (which also applies to all later versions): the Validator extension that helps Semantic MediaWiki to validate user-provided parameters. It must be installed for SMW to work. Make sure that you include Validator prior to the inclusion of SMW in your LocalSettings.php. Do note that Validator comes bundled with SMW releases as of version 1.6.0. If you are obtaining the code via svn, you will need to get a checkout of Validator yourself.

Do not forget to also install the extension Validator first and include it in LocalSettings.php prior to SMW with the following line of code. After that you may proceed to upgrade SMW.

require_once( "$IP/extensions/Validator/Validator.php" );

Extensions for SMW versions up to 1.5.* should not be assumed to work with SMW 1.6.0 out of the box. All SMW extensions should be upgraded to versions that are compatible with SMW 1.6. Moreover, some functions changed and pages might need updates (see below). Additional remarks on upgrading older SMW versions are given below.

If not done already, it is suggested to change the inclusion of SMW in LocalSettings.php to the following as described in the installation instructions above:

include_once("$IP/extensions/SemanticMediaWiki/SemanticMediaWiki.php");

Including SMW_Settings.php as in earlier versions will no longer work.

Changed configuration options

Some configuration options (used in LocalSettings.php) have changed since SMW 1.0. All settings are documented in detail in the file SMW_Settings.php. The following list gives the version in which a setting was first introduced, so it can be ignored if you already run this version or a more recent one.

• [1.4] Up to version 1.4, the default for value for the setting $smwgQComparators was '<|>|!'. It now has changed to '<|>|!|~' so the "like" comparator ~ is enabled by default.
• [1.4] Version 1.4 still supported a setting $smwgSMWBetaCompatible to enable the old <ask> query syntax and the Relation namespace. This backwards compatibility has now been dropped and the setting is no longer used. Please update your wiki to not use the outdated (and now undocumented) features.
• [1.3] Since SMW 1.3, the Factbox is hidden by default and will only appear in page previews. As a compensation, the toolbox (usually on the left below the search field) shows a link to Special:Browse. To use the display behaviour of the Factbox as it was before SMW 1.3, set $smwgShowFactbox = SMW_FACTBOX_NONEMPTY; The new link and the Factbox during editing can also be configured; see SMW_Settings.php for details.
• [1.2.1] SMW will no longer support nested link syntax in property values by default, since this was known to cause problems. To re-enable this, set $smwgLinksInValues = true;
• [1.2] If your wiki uses <ask> syntax or the Relation: namespace, you may want to set $smwgSMWBetaCompatible = true; before the line including SemanticMediaWiki.php (formerly SMW_Settings.php) in LocalSettings.php. Consider changing <ask> to #ask to be able to drop SMW beta compatibility.
• [1.2] If you had a setting $smwgQDisjunctionSupport = false; then you now need the following settings in your LocalSettings.php:

  $smwgQFeatures        = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY;
  $smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY & ~SMW_CONCEPT_QUERY;

• [1.0] $smwgQEqualitySupport is one of SMW_EQ_NONE, SMW_EQ_SOME, SMW_EQ_FULL (it was true or false until SMW 1.0 RC1-3).
• [1.0] $smwgQDefaultNamespaces is now NULL by default, so that all namespaces are queried. The default in SMW RC 1-3 was 'array(NS_MAIN, NS_IMAGE)'.
• [1.0] $smwgQDefaultLinking now defaults to 'all' such that all query results are linked. This is not a performance issue any more. The default until SMW RC 1-3 was 'subject'.

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