Help:Installation 1.8.0

This page describes how to install Semantic MediaWiki 1.8.0 after downloading it (see the bottom of this page for other versions). Installation and upgrade notes change from version to version: the 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 page.

To upgrade a wiki running an older version of SMW, be sure to read the 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).

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

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

Requirements
See the breakdown below for version specific requirements as well as the page on compatibility.
 * 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)

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 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 PHP manual for details.
 * For installation and upgrade, SMW needs the rights to create new tables and to alter tables . You can remove both rights after SMW is set up. The script   can use the DB credentials from   for this purpose, avoiding the need of extra rights for the wiki DB user.
 * When using  (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:
 * When using  (the RDF store connector), SMW uses the CURL functions of PHP. These functions may have to be enabled/installed to be available.

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.
 * Running SMW on older versions of MediaWiki

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 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. ''' 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  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  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  in LocalSettings.php.

'''(3) Enable the extensions. ''' Insert the following lines into the file "[wikipath]/LocalSettings.php": 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).



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

 * 1) As mentioned above, make a backup of your database.
 * 2) Replace the files in your /extensions/SemanticMediaWiki folder with the new files
 * 3) * (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

 * 1) To use the old layout at first, add the following to your LocalSettings.php file:   If you are using the following setting already...:   ... then you should keep this line and add the following:
 * 2) After setting these, run the   script from your shell, like so:   The wiki should now work as normal, but using the old storage structures.
 * 3) 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):    The running wiki will not be affected by this, but the operation could affect server speed. See the help page about repairing SMW's data for details.
 * 4) 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:

Without shell access

 * 1) Add the following code to your LocalSettings.php to disable editing
 * 2) Replace the files of Semantic MediaWiki, Validator and the other semantic extensions which need to be updated in the extensions directory.
 * 3) Go to "Special:SMW-Admin" and click on the "Initialise and upgrade tables" button.
 * 4) After the new tables were created return to "Special:SMW-Admin" and click on the "Start updating data" button.
 * 5) After the data refresh has started add   to your LocalSettings.php below the line   to switch to the old SMWSQLStore2 during the data refresh for SMWSQLStore3.
 * 6) Comment out   to make the wiki editable again. The wiki should now work as normal, but using the old storage structures.
 * 7) After the data refresh is done do the first step again: Set   in your LocalSettings.php
 * 8) Comment out   in your LocalSettings.php to switch to SMWSQLStore3
 * 9) 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.
 * 10) Do step five again: Add   to your LocalSettings.php below the line   to switch to the old SMWSQLStore2 during the data refresh for SMWSQLStore3.
 * 11) Remove   to make the wiki editable again. The wiki should now work as normal, but using the old storage structures.
 * 12) After the second data refresh is done, remove   from your LocalSettings.php to switch to SMWSQLStore3.
 * 13) 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  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.



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:



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. 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  was "SMWSQLStore2". SMW 1.8 introduced a new store "SMWSQLStore3" as a relational data backend.
 * [1.8] With the replacement of result format "rss" by "feed" the respective settings  and   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  was  . It now has changed to   so the "like" comparator   is enabled by default.
 * [1.4] Version 1.4 still supported a setting  to enable the old 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  The new link and the Factbox during editing can also be configured; see   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
 * [1.2] If your wiki uses  syntax or the   namespace, you may want to set   before the line including SemanticMediaWiki.php (formerly SMW_Settings.php) in LocalSettings.php. Consider changing   to   to be able to drop SMW beta compatibility.
 * [1.2] If you had a setting  then you now need the following settings in your  :
 * [1.0]  is one of   (it was   or   until SMW 1.0 RC1-3).
 * [1.0]  is now   by default, so that all namespaces are queried. The default in SMW RC 1-3 was ' '.
 * [1.0]  now defaults to ' ' such that all query results are linked. This is not a performance issue any more. The default until SMW RC 1-3 was ' '.

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