[ar] [ast] [bg] [br] [ca] [co] [cpf] [cs] [da] [de] [en] [eo] [es] [eu] [fa] [fon] [fr] [gl] [id] [it] [ja] [lb] [nl] [oc] [pl] [pt] [ro] [ru] [sk] [sv] [tr] [uk] [vi] [zh] Espace de traduction

Home > English documentation > Webmasters > Guide to advanced features > Other advanced functions > Mutualisation: sharing a single SPIP kernel amongst several (...)

Mutualisation: sharing a single SPIP kernel amongst several sites

August 2010 — updated on : February 2013

All the versions of this article:

Sharing the core SPIP files between several sites, which we call mutualisation in French and perhaps "resource pooling" in English, makes it possible to benefit from a significant gain in disk space usage, as well as the possibility of updating SPIP for a collection of sites in a single, simple step by just updating the single common kernel.

SPIP allows for its files to be shared since SPIP 1.9. As new versions are released, the procedures for doing so are becoming clearer and more robust [1].

The concept...

Since SPIP 1.9.2, the folders required for the SPIP kernel to run (ecrire, prive, dist (which changed to squelettes-dist in 2.0)), and those tracking the activities of a site (config, IMG, tmp, local) have been clearly identified and separated from one another [2]. It is this new separation which now makes it possible to have several autonomous SPIP sites all running on the same SPIP kernel.

This autonomy relies on four directories for each site, into which SPIP will write the data and results from activities on the site. We distinguish between temporary and permanent data on the first hand, and between data which is or is not accessible via HTTP on the second hand. The two directories for non-HTTP accessible data will be protected by a .htaccess file automatically installed by SPIP (the server administrators can also locate these directories outside of the directory structure that is serviced by HTTP).

These four directories are quite distinct and are named using the following PHP constants:


In an ordinary installation of SPIP, these directories are created at the root of the site using the default directory names shown above. The pooling of the SPIP sources relies on the mapping of these four specific directories for each site as determined by their URLs.

Initialising resource pooling

This mapping is carried out by the spip_initialisation function. It accepts four arguments indicating the location of these four fundamental directories, and uses them to construct the constants that are required for SPIP to operate properly. For a standard installation, these four arguments are simply those four constants illustrated above. The spip_initialisation function is called just after the mes_options.php file has been loaded, and will silently refuse to execute if it has already been called. As a consequence, if that file applies this function on the four arguments deduced from the site URL, then we will be using the SPIP sources from the same location as the site URL. We could also define the constants using for SPIP’s operations in this file, with these definitions thereby taking priority over those that spip_initialisation would try to define.

The code below, when inserted into the config/mes_options.php file, takes the domain name and performs resource pooling for the four directories tmp, local, config and IMG located in the sites/domain_name/ folder. Previously, the definition of a few constants made it possible to centralise the logging files for all of the sites into a single directory, log, and not into several sites/domain_name/tmp/ directories for each of them. This centralisation is certainly not compulsory but does prove to be useful; it can also be applied for the help and back-up/restore directories.

  1. <?php
  2. $rep = 'sites/';
  3. $site = $_SERVER['HTTP_HOST'];
  4. $path = _DIR_RACINE . $rep . $site . '/';
  6. // path search order
  7. define('_SPIP_PATH',
  8. $path . ':' .
  9. _DIR_RACINE .':' .
  10. _DIR_RACINE .'squelettes-dist/:' .
  11. _DIR_RACINE .'prive/:' .
  14. // add the squelettes template folder
  15. if (is_dir($path . 'squelettes'))
  16. $GLOBALS['dossier_squelettes'] = $rep . $site . '/squelettes';
  18. // example of logs at the root for all sites
  19. define('_FILE_LOG_SUFFIX', '_' . $site . '.log');
  20. define('_DIR_LOG', _DIR_RACINE . 'log/');
  22. // prefixes for cookies and tables:
  23. $cookie_prefix = str_replace('.', '_', $site);
  24. $table_prefix = 'spip';
  26. // execute the config/mes_option.php file for the mutualised site
  27. if (is_readable($f = $path . _NOM_PERMANENTS_INACCESSIBLES . _NOM_CONFIG . '.php'))
  28. include($f);
  30. // start the site
  31. spip_initialisation(
  36. );
  37. ?>


Resource pooling for domains or sub-domains

To pool the resources for several domains or sub-domains, you must redirect them all to the physical directory that contains SPIP. For example, in order to resource pool http://example.org/, http://example.net/ and http://subdomain.example.net/, they should all point to the same common directory, such as /var/www/spip/.

So this folder contains SPIP as well as a config/mes_options.php file for activating the resource pooling. Taking the code example above, we must then create the sites and log folders as well as sites/example.org, sites/example.net and sites/subdomain.example.net, and within each of these also create the config, local, IMG and tmp directories with write access. And that’s it! By then accessing any one of these sites, SPIP should proceed to offer you its normal installation routine.

If you want to be able to activate different types of URLs, such as the "url arborescentes" (hierarchical URLs) or "url propres" (personal URLs), then it will be necessary to create an HTTP access file, a template of which is included in the standard distribution with the name of htaccess.txt: just rename it as .htaccess to power it up. It will apply to all of the pooled sites, but it is possible to have differentiated access to the various sites by carefully configuring the server (see more on this below). In both cases, this will all only work if your server accepts to execute the directives included in this file, especially those relating to URL rewriting (which is not necessarily available for all ISP hosts - be sure to check with your host before attempting to use such rewriting rules).

Sharing the directories of a domain

Every (virtual) folder in a domain, when its URL is correctly processed, can also become a pooled SPIP site. For this to happen, it is necessary that the folder’s URL be redirected transparently to the SPIP root. This is the role played by the modified .htaccess file. In this way, http://example.com/first_site/ and http://example.com/second_site/ can both be pooled SPIP sites (and http://example.com/ at the same time too).

First off, the htaccess.txt must be renamed as .htaccess, and then be modified so that the virtual directories point to the SPIP root. To do this, add into the "Réglages personnalisés" section (custom settings) either the generic code which handles all of the virtual directories together (but where http://example.com/first_site without its closing "/" will return an error), or specific code indicating the directory names explicitly (no errors if there is no closing "/"):

Secondly, a resource pooling must be created by analysing the the URL passed in the config/mes_options.php file. Here is an example for having the pooled sites at sites/example.com, sites/first_site and sites/second_site:

  1. <?php
  2. if (
  3. (
  4. preg_match(',^/([\.a-zA-Z0-9_-]+)/,', $_SERVER['REQUEST_URI'], $r)
  5. AND !is_dir(_DIR_RACINE . $r[1])
  6. )
  7. ) {
  8. $site = $r[1];
  9. } else {
  10. $site = $_SERVER['HTTP_HOST'];
  11. }
  13. $rep = 'sites/';
  14. $path = _DIR_RACINE . $rep . $site . '/';
  16. // path name search order
  17. define('_SPIP_PATH',
  18. $path . ':' .
  19. _DIR_RACINE .':' .
  20. _DIR_RACINE .'squelettes-dist/:' .
  23. _DIR_RACINE .'prive/:' .
  26. // add the squelettes template folder
  27. if (is_dir($path . 'squelettes'))
  28. $GLOBALS['dossier_squelettes'] = $rep . $site . '/squelettes';
  30. // prefixes for cookies tables:
  31. $cookie_prefix = str_replace('.', '_', $site);
  32. $table_prefix = 'spip';
  34. // execute the config/mes_option.php file for the pooled site
  35. if (is_readable($f = $path . _NOM_PERMANENTS_INACCESSIBLES . _NOM_CONFIG . '.php'))
  36. include($f);
  38. // start the site
  39. spip_initialisation(
  44. );
  45. ?>


Table prefixing

The examples shown above require as many database instances as there are resource pooled sites. However, it is possible to install all of the sites on a single database by prefixing the names of their tables with a unique prefix for each site.

The example below creates a prefix of 8 characters: one prefix with the first 4 letters of the site, followed by another 4 different "random" characters.

  1. $table_prefix = substr(str_replace('.', '_', $site),0,4) . substr(md5($site),0,4);

The config/mes_options.php file

Any modification made to the config/mes_options.php file for the SPIP kernel will affect the options for all of the sites being hosted.

For example, inserting this code into that file: $type_urls = ’propres’ ;

will make all of the sites use that type of URL by default... But each of these sites is free to change that in its own "private" /sites/repertoire_du_site/config/mes_options.php file.

Configuring Apache for the domains and sub-domains

The tasks for resource pooling on the server side remain quite simple in respect of managing the sub-domains and domains. All you need is to create a redirection between the domain name and the physical directory where SPIP is stored.

Shown below is a (minimal) configuration example for a server called ’example.tld’ using some sub-domains. The configuration file is to be created in /etc/apache2/sites_availables/example.tld, which must then be activated

SPIP is installed in this example in ’/var/www/spip/’.

If you additionally want to have differentiated access files, then use the AccessFileName directive inside the VirtualHost directive, so that the access file for site S is named, for example, as .htaccess-S.

Note about back-ups and restores

By default, each site copies its back-up files into the /sites/first_site/tmp/dump (or /sites/first_site/tmp/upload/login directories for back-ups for a restricted admin).

The restores are made from the same folder. The path name for image files is also correctly taken into account [3].


[1The updates of SPIP 1.9.1 simplified the procedure a little, but a reliable implementation of sharing the SPIP kernel only came with the improvements provided in SPIP 1.9.2 (which had a new model of the internal directories to making mutualisation simpler, corrected login and site name conflicts, and offered a turn-key site start-up function for a "mutualised" site). With spip2 the addresses of documents in the XML back-up files became independent of the physical path names, thereby eliminating the last obstacle to widespread deployment (back ups and restores can be performed from one SPIP to another as if there were no mutualising going on at all).

[2Before SPIP 1.9.2, these four types of data were not clearly distinguished from each other and were found in the IMG, CACHE, ecrire and ecrire/data directories

[3Before SPIP 2, SPIP would register the full path name of image files in the database, thereby processing the /IMG directory for a pooled site with an address like sites/first_site/IMG/jpg/fichier.jpg instead of the regular IMG/jpg/fichier.jpg format for a single stand-alone SPIP site.

A restore would only work correctly on the site which created the original back-up. The trick for restoring a site anywhere else consisted of editing the dump.xml file manually and replacing all the occurrences of (excepting those for the dir_img and dir_logo declarations in the opening SPIP tag):
-  sites/first_site/IMG/

  • with (single SPIP): IMG/
  • or (pooled SPIP): sites/my_new_site/IMG/

Inversely, for switching a single SPIP into a pooled directory, it would be necessary to replace all the occurrences of:
-  IMG/
-  with: sites/my_site/IMG/

Show the template of this page Site powered by SPIP | Translation area | Private area