View source for Help:Installation 1.8.0

{{SMW admin TOC}}

This page describes how to '''install [[Semantic MediaWiki 1.8.0]]''' after [[Help:Download|downloading]] it (see the bottom of this page for other versions). Installation and upgrade notes change from version to version: the [https://github.com/SemanticMediaWiki/SemanticMediaWiki/blob/master/docs/INSTALL.md INSTALL file] shipped with SMW contains instructions for the particular version you have downloaded. If you are '''installing SMW 1.9 or higher''', see the instructions in the INSTALL file and the relevant [[Help:Installation|help page]].

To '''upgrade a wiki running an older version of SMW''', be sure to read the [[#Upgrading existing installations|relevant section]] ''before'' starting the upgrade.

To install 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 could later be removed). However, there is currently no automated process to remove annotations from articles' text if you uninstall Semantic MediaWiki (one could achieve this with a script that removes annotations upon editing).

<big>{{Note}} '''If you are using MediaWiki 1.23 and higher and/or PHP 5.4 and higher you are strongly encouraged to install or to update to [[Semantic MediaWiki 2.0]] or higher. Semantic MediaWiki 1.8 is not recommended for productive use with these versions.'''</big>

== Disclaimer ==

Make sure you understand the legal disclaimer in the file [https://git.wikimedia.org/raw/mediawiki%2Fextensions%2FSemanticMediaWiki/6ed064d81bfa14e2532666902dd6c0b941fc207b/COPYING COPYING].

== Requirements ==
* MediaWiki 1.17+ (MediaWiki 1.19+ is recommended)
* [[Validator]] extension version 0.5+
* PHP 5.2+ (except for version 5.3.1)
* MySQL 4.0.14+ (except for versions 5.1.49 to 5.1.52)
{{note}} See the breakdown below for version specific requirements as well as the page on [[compatibility]].

=== MediaWiki 1.17.x and 1.18.x ===
* PHP 5.2+ (except for version 5.3.1)
* MySQL 4.0.14+ (except for versions 5.1.49 to 5.1.52)

=== MediaWiki 1.19.x ===
* PHP 5.2+ (except for version 5.3.1)
* MySQL 5.0.2+ (except for versions 5.1.49 to 5.1.52)

=== MediaWiki 1.20+ ===
* PHP 5.3.2+
* MySQL 5.0.2+ (except for versions 5.1.49 to 5.1.52)

;Notes
*  Individual [[Help:SMW extensions|extensions]], e.g. [[Semantic Result Formats]] may have different requirements.
* 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 (<code>CREATE</code>) and to alter tables (<code>ALTER TABLE</code>). You can remove both rights after SMW is set up. The script <code>SMW_setup.php</code> can use the DB credentials from <code>AdminSettings.php</code> for this purpose, avoiding the need of extra rights for the wiki DB user.
* When using [[Help:Configuration#smwgDefaultStore|<code>SMWSQLStore3</code>]] (the 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 and DROP. The according features can be disabled by adding the following to Localsettings.php:
<syntaxhighlight lang="php">
$smwgQSubcategoryDepth= 0;
$smwgQPropertyDepth   = 0;
$smwgQFeatures        = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY;
$smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY &
                       ~SMW_CONCEPT_QUERY;
</syntaxhighlight>
* When using [[Help:Configuration#smwgDefaultStore|<code>SMWSparqlStore</code>]] (the 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|Upgrading existing installations]] below! Installing SMW basically requires three (or four) easy steps:

'''(1) Copy files.&nbsp;''' Extract the downloaded archives for Validator and Semantic MediaWiki, or check out the current files from Git 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.&nbsp;''' If you did not 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 [[Help:Configuration#smwgNamespaceIndex|<code>$smwgNamespaceIndex</code>]] 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 [[Help:Configuration#smwgHistoricTypeNamespace|<code>$smwgHistoricTypeNamespace</code>]] 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 [[Help:Configuration#smwgNamespacesWithSemanticLinks|<code>$smwgNamespacesWithSemanticLinks</code>]] in LocalSettings.php.

'''(3) Enable the extensions.&nbsp;''' Insert the following lines into the file "[wikipath]/LocalSettings.php":
<syntaxhighlight lang="php">
 require_once( "$IP/extensions/Validator/Validator.php" );
 include_once( "$IP/extensions/SemanticMediaWiki/SemanticMediaWiki.php" );
 enableSemantics('example.org');
</syntaxhighlight>
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.

'''(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. SMW can be used before this completes, but will not have access to all data yet (e.g. page categories).
{|
|[[File:Admin functions for Semantic MediaWiki.png|thumb|300px|Special:SMWAdmin]]
|[[File:Setting up Storage for Semantic MediaWiki.png|thumb|250px|Storage was successfully set up]]
|}

[[File:Testing your Semantic Mediawiki installation.png|thumb|300px|right|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:
# Go to the [[Special:Version|Special:Version page]]. You should see Semantic MediaWiki (Version nn) listed in the top section "Semantic Extensions".
# Create a regular wiki page named "TestSMW", and in it enter the wiki text<pre>Property test:  [[testproperty::Dummypage]]</pre>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 ==
Before upgrading existing installations make sure that you back up your database and your installation.

SMW 1.6.0 introduced 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 Git, you will need to get a clone of Validator yourself.

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

=== Upgrading SMW 1.6.x and SMW 1.7.x ===
Installations of SMW 1.6.x and 1.7.x and can be upgraded by replacing the files and follow the steps mentioned below, since SMW 1.8.0 introduces a new default database layout (SMWSQLStore3). You can continue to use the old layout (SMWSQLStore2) for transition purposes, but it is strongly recommended to migrate to the new layout for future compatibility.

==== Preliminary steps ====

# As mentioned above, make a backup of your database.
# Replace the files in your <wiki-root>/extensions/SemanticMediaWiki folder with the new files 
#* (You can for example rename the old folder to something like SemanticMediaWiki_old, while updating, so that you can easily switch back if needed)

==== With shell access ====

# To use the old layout at first, add the following to your LocalSettings.php file: <syntaxhighlight lang="php">$smwgDefaultStore = 'SMWSQLStore2';</syntaxhighlight> If you are using the following setting already...: <syntaxhighlight lang="php"> $smwgDefaultStore = 'SMWSparqlStore'; </syntaxhighlight> ... then you should keep this line and add the following: <syntaxhighlight lang="php">
SMWSparqlStore::$baseStoreClass = 'SMWSQLStore2'; // directly below enableSemantics('example.org');</syntaxhighlight>
# After setting these, run the <code>SMW_setup.php</code> script from your shell, like so: <syntaxhighlight lang="bash">php SMW_setup.php -b SMWSQLStore3</syntaxhighlight> The wiki should now work as normal, but using the old storage structures.
# To migrate to the new store, you must do a normal "full refresh" for the new store. To do this execute the following two commands (both will run a while): <syntaxhighlight lang="bash">php SMW_refreshData.php -v -b SMWSQLStore3 -fp</syntaxhighlight><syntaxhighlight lang="bash">php SMW_refreshData.php -v -b SMWSQLStore3</syntaxhighlight> The running wiki will not be affected by this, but the operation could affect server speed. See the help page about [[Help:Repairing SMW's data|repairing SMW's data]] for details.
# After successful migration, '''remove the lines with 'SMWSQLStore2' from your LocalSettings.php''' file to use the new store. You can always return to the old store in case of problems. If the old store is no longer needed, it can be deleted (and its memory freed) by running the following command: <syntaxhighlight lang="bash">php SMW_setup.php --delete --backend SMWSQLStore2</syntaxhighlight>

==== Without shell access ====

# Add the following code to your LocalSettings.php to disable editing <syntaxhighlight lang="php">$wgReadOnly = 'This wiki is currently in maintenance mode and cannot be edited.';</syntaxhighlight>
# Replace the files of Semantic MediaWiki, Validator and the other semantic extensions which need to be updated in the extensions directory.
# Go to "Special:SMW-Admin" and click on the "Initialise and upgrade tables" button.
# After the new tables were created return to "Special:SMW-Admin" and click on the "Start updating data" button.
# After the data refresh has started add <syntaxhighlight lang="php">$smwgDefaultStore = 'SMWSQLStore2';</syntaxhighlight> to your LocalSettings.php below the line <syntaxhighlight lang="php">enableSemantics('example.org');</syntaxhighlight> to switch to the old SMWSQLStore2 during the data refresh for SMWSQLStore3.
# Comment out <syntaxhighlight lang="php">$wgReadOnly = 'This wiki is currently in maintenance mode and cannot be edited.';</syntaxhighlight> to make the wiki editable again. The wiki should now work as normal, but using the old storage structures.
# After the data refresh is done do the first step again: Set <syntaxhighlight lang="php">$wgReadOnly = 'This wiki is currently in maintenance mode and cannot be edited.';</syntaxhighlight> in your LocalSettings.php
# Comment out <syntaxhighlight lang="php">$smwgDefaultStore = 'SMWSQLStore2';</syntaxhighlight> in your LocalSettings.php to switch to SMWSQLStore3
# Do step four again: Return to to "Special:SMW-Admin" and click on the "Start updating data" button to start the second data refresh for SMWSQLStore3.
# Do step five again: Add <syntaxhighlight lang="php">$smwgDefaultStore = 'SMWSQLStore2';</syntaxhighlight> to your LocalSettings.php below the line <syntaxhighlight lang="php">enableSemantics('example.org');</syntaxhighlight> to switch to the old SMWSQLStore2 during the data refresh for SMWSQLStore3.
# Remove <syntaxhighlight lang="php">$wgReadOnly = 'This wiki is currently in maintenance mode and cannot be edited.';</syntaxhighlight> to make the wiki editable again. The wiki should now work as normal, but using the old storage structures.
# After the second data refresh is done, remove <syntaxhighlight lang="php">$smwgDefaultStore = 'SMWSQLStore2'; </syntaxhighlight> from your LocalSettings.php to switch to SMWSQLStore3.
# In case annotations ore changes to them were done during the refresh of SMWSQLStore3 return to to "Special:SMW-Admin" and click on the "Start updating data" button to start a third data refresh for SMWSQLStore3.


You can always return to the old store buy adding <syntaxhighlight lang="php">$smwgDefaultStore = 'SMWSQLStore2';</syntaxhighlight> in your LocalSettings.php in case of problems. If the old store is no longer needed, the respective tables can be deleted manually in the database itself. Their names are : "smw_ids", "smw_conccache", "smw_rels2", "smw_atts2", "smw_text2", "smw_spec2", "smw_subs2", "smw_subp2", "smw_inst2", "smw_redi2", "smw_conc2" and possible "sm_coords" if it is there. It is not possible to delete the obsolete database tables via Special:SMWAdmin.

=== Upgrading SMW 1.5.x and below ===
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. Make sure that you also follow the instructions for upgrading described in earlier versions of SMW. See the navigation bar at the bottom of this page for the respective help pages.

<div style="float:left;"><syntaxhighlight lang="php">
require_once( "$IP/extensions/Validator/Validator.php" );
</syntaxhighlight></div><br style="clear:both;" clear="all" />

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:

<div style="float:left;"><syntaxhighlight lang="php">
include_once("$IP/extensions/SemanticMediaWiki/SemanticMediaWiki.php");
</syntaxhighlight></div><br style="clear:both;" clear="all" />

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

== Changed configuration options ==
Some [[Help:Configuration|configuration]] options (used in LocalSettings.php) have changed since SMW 1.0. All settings are documented in detail in the file <code>SMW_Settings.php</code>. 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.8]''' Up to version 1.8, the default value for <code>$smwgDefaultStore</code> was "SMWSQLStore2". SMW 1.8 introduced a new store "SMWSQLStore3" as a relational data backend.
* '''[1.8]''' With the replacement of result format "[[Help:RSS format|rss]]" by "[[Help:Feed format|feed]]" the respective settings <code>$smwgRSSEnabled</code> and <code>$smwgRSSWithPages</code> were removed, too. The first setting was dropped entirely while the second one was replaced by the new output parameter "page".
* '''[1.4]''' Up to version 1.4, the default for value for the setting <code>$smwgQComparators</code> was <code>'<|>|!'</code>. It now has changed to <code>'<|>|!|~'</code> so the "like" comparator <code>~</code> is enabled by default.
* '''[1.4]''' Version 1.4 still supported a setting <code>$smwgSMWBetaCompatible</code> to enable the old <nowiki><ask></nowiki> 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 <code>$smwgShowFactbox = SMW_FACTBOX_NONEMPTY;</code> The new link and the Factbox during editing can also be configured; see <code>SMW_Settings.php</code> 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 <code>$smwgLinksInValues = true;</code>
* '''[1.2]''' If your wiki uses <code><nowiki><ask></nowiki></code> syntax or the <code>Relation:</code> namespace, you may want to set <code>$smwgSMWBetaCompatible = true;</code> ''before'' the line including SemanticMediaWiki.php (formerly SMW_Settings.php) in LocalSettings.php. Consider changing <code><nowiki><ask></nowiki></code> to <code>#ask</code> to be able to drop SMW beta compatibility.
* '''[1.2]''' If you had a setting <code>$smwgQDisjunctionSupport = false;</code> then you now need the following settings in your <code>LocalSettings.php</code>:
<syntaxhighlight lang="php">
  $smwgQFeatures        = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY;
  $smwgQConceptFeatures = SMW_ANY_QUERY & ~SMW_DISJUNCTION_QUERY & ~SMW_CONCEPT_QUERY;
</syntaxhighlight>
* '''[1.0]''' <code>$smwgQEqualitySupport</code> is one of <code>SMW_EQ_NONE, SMW_EQ_SOME, SMW_EQ_FULL</code> (it was <code>true</code> or <code>false</code> until SMW 1.0 RC1-3).
* '''[1.0]''' <code>$smwgQDefaultNamespaces</code> is now <code>NULL</code> by default, so that all namespaces are queried. The default in SMW RC 1-3 was '<code>array(NS_MAIN, NS_IMAGE)</code>'.
* '''[1.0]''' <code>$smwgQDefaultLinking</code> now defaults to '<code>all</code>' such that all query results are linked. This is not a performance issue any more. The default until SMW RC 1-3 was '<code>subject</code>'.

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

== See also ==
* [[mediawikiwiki:Manual:Installation guide|MediaWiki installation manual]]

{{docinfo
| master page = Help:Installation
| master rev  = {{REVISIONID}}
| master link = internal
| status   = effective
| progress = 100
| priority = 1
| category = Manual
| author = Markus Krötzsch
| editor = {{REVISIONUSER}}
| support = Jeroen De Dauw
| minversion = 1.8.0
| maxversion = 1.8.0
| lang = en
| desc =
| return =
| nowarn
}}