Help:Installation 1.4.2

{{SMW admin TOC}}
This page describes how to '''install [[Semantic MediaWiki 1.4.2]]''' after having [[Help:Download|downloaded]] it (see the bottom of this page for other versions). Installation and upgrade notes change from version to version: the file [http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/SemanticMediaWiki/INSTALL 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 [[#Upgrading existing installations|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 [http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/SemanticMediaWiki/COPYING COPYING].

== Requirements ==

* MediaWiki 1.11.* or greater (tested from MW 1.11 to 1.15alpha (r46927)).
* PHP 5.x or greater installed and working
* MySQL >= 4.0.14 (version required by MediaWiki) or 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 [http://php.net/manual/en/ref.mbstring.php#mbstring.installation PHP manual] for details.
* For installation and upgrade, SMW needs the rights to create new tables (<tt>CREATE</tt>) and to alter tables (<tt>ALTER TABLE</tt>). Both can be removed again after SMW was set up. The script <tt>SMW_setup.php</tt> can use the DB credentials from <tt>AdminSettings.php</tt> for this purpose, avoiding the need of extra rights for the wiki DB user.
* SMW creates and alters temporary tables for certain semantic queries. To do this, your wikidb user must have privileges for <tt>CREATE TEMPORARY TABLES</tt>. If this is not desired, the SMW features which require this right can be disabled by adding the following to <tt>Localsettings.php</tt>:

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

== Installation ==

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

'''(1) Copy files.&nbsp;''' 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.&nbsp;''' Insert the following two lines into the file "[wikipath]/LocalSettings.php":

 include_once("$IP/extensions/SemanticMediaWiki/includes/SMW_Settings.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 [[Help:RDF export|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 &ndash; just pick one.

'''(3) ''[optional]'' Adjust namespaces.&nbsp;''' If didn't make any change the your wiki's namespaces, you can skip this step. If you have defined your own [http://www.mediawiki.org/wiki/Manual:Using_custom_namespaces custom namespaces], you have to set the parameter $smwgNamespaceIndex before including SMW_Settings.php. Semantic MediaWiki uses ten additional namespace indexes, in the range from 100 to 109. Note, 100 and 101 are only needed if <tt>$smwgSMWBetaCompatible</tt> is set. 106 and 107 are reserved for the SemanticForms 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 change the array variable <tt>$smwgNamespacesWithSemanticLinks</tt> in SMW_Settings.php.

'''(4) Setup database.&nbsp;''' 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 [[Repairing SMW|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.

=== 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. You should see Semantic MediaWiki (version nn) listed as a Parser Hook there.

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

 <nowiki>Property test:  [[testproperty::Dummypage]]</nowiki>

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.

=== 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.

== Upgrading existing installations ==

Existing SMW installations that already use the default store (SMWSQLStore2) can simply follow the above installation steps. This covers all sites with [[SMW 1.4]] or greater, and all sites with [[SMW 1.2]] to [[SMW 1.3|1.3]] that do not use a special setting to switch back to the old store ("SMWSQLStore" or "SMWRAPStore"). In these cases the new data upgrade feature will ensure that your data is refreshed to the new version. To speed up the update, use MediaWiki's script runJobs.php.

Older SMW versions or SMW versions that use the old store can upgrade in the same fashion, but first need to remove any setting that configures SMW to use the old store. Again, all data will immediately be available when the data
upgrade has finished.

Directly after enabling SMW 1.4.2, it can potentially happen that the site shows SQL errors due to background jobs trying to access the new DB structure even before you initialised it. This can even block you from reaching SMWAdmin.
In this case, either use the script SMW_setup.php from the command-line, or access your database and delete all entries in the table "job". After this, no errors should show up while accessing the special page for initialisation.

Especially when upgrading from SMW 1.3 or older, extensions of SMW (e.g. [[Semantic Forms]]) need to be updated to a version that is compatible with SMW 1.4.2. See your extension's homepage for details. If you use one of the formats [[Help:Timeline format|timeline]] (or eventline), [[Help:ICalendar format|icalendar]], or [[Help:VCard format|vcard]] in [[inline queries]], then you need to install the extension [[Semantic Result Formats]] (SRF) in version 1.4.2 or greater. The formats have been migrated to this extension package and are enabled there by default after installation.

=== 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 <tt>SMW_Settings.php</tt>. 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.3]''' Since SMW 1.3, the [[Factbox]] is hidden by default and will only appear. 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 <tt>$smwgShowFactbox = SMW_FACTBOX_NONEMPTY;</tt> The new link and the Factbox during editing can also be configured; see <tt>SMW_Settings.php</tt> 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 <tt>$smwgLinksInValues = true;</tt>
* '''[1.2]''' If your wiki uses <tt><nowiki><ask></nowiki></tt> syntax or the <tt>Relation:</tt> namespace, you may want to set <tt>$smwgSMWBetaCompatible = true;</tt> ''before'' the line including SMW_Settings.php in LocalSettings.php. Consider changing <tt><nowiki><ask></nowiki></tt> to <tt>#ask</tt> to be able to drop SMW beta compatibility.
* '''[1.2]''' If you had a setting $smwgQDisjunctionSupport = false, then you now need the following settings:

  $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 <tt>true</tt> or <tt>false</tt> 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.

{{docu|master page=Help:Installation|language=en|minversion=1.4.2|maxversion=1.4.2}}