From Cloudrexx Development Wiki
Jump to: navigation, search

This is the documentation of the MultiSite module (available from Contrexx 4).

What it does

Multiple independent instances of Contrexx can be used requiring only one full installation.


You have a lot of customers using the same version of Contrexx. You want to update all their installations to a newer version. Using the MultiSite module you can do the following

  1. Make a new clean install of the new version on your server
  2. Create a test.{domain} installation for all your customers (select all instances, choose 'copy')
  3. Move all test installations to the new version (select all test instances, choose 'move')
  4. Test all installations and migrate their customizings (if any)
  5. Move all non-test installations to the new version (select all instances, choose 'move')


The MultiSite module can be used in two different modes. The configuration difference for the module itself is only the path where instances are located:

Single vHost

In this mode, all instances are stored somewhere within the main installation (for example in /instances). The used vHost is configured with a wildcard (or all used domains are mapped to this single vHost).

If your main installation is at, adding an instance named foo will create a new instance available at without adding another vHost. Later some domain (let's say can be mapped to

This mode allows spawning new instances within the least amount of time possible (--> instant spawning) and works without involving other software (i.e. relying on Apache/IIS for resolving request to instance location), therefore it's easy to configure.

Multi vHost

In this mode, all instances are stored within the document root of your web server.

If your main installation is at /var/www/current, adding an instance named foo will create an instance located at /var/www/foo. Create a vHost with /var/www/foo as document root and you're good to go.

This mode makes it easier to allow your customers to access folders like /customizing, /themes, etc. per FTP or any similar service.

In order to make this work, Apache/IIS has to do the resolving from request to the folder to load. This improves performance compared to single vHost mode, since Contrexx does not have to search for the instance matching the request. But Apache/IIS will need some more configuration.

Note: This mode will not be available in the first release of the MultiSite module as in favour to focus on the release of the Single vHost mode.


Notification emails

Recipient is selected by specific website

The notification email is targeted regarding a specific website


Recipient is selected by specific user

The notification email is targeted towards the user. All websites associated to the specific user can be listed using the placeholder-template-block WEBSITE_LIST




Every instance gets a full copy of the database. So for the database there is no difference between a normal and a MultiSite setup.

The files however are always loaded from the main installation. There are only a few exceptions to this (those are needed for every instance):

  • index.php is needed when using Multi vHost mode
  • /config/configuration.php is needed in order to load a different database
  • /config/settings.php is needed in order to have different settings per instance
  • /tmp folder is needed to avoid read/write problems between instances
  • /customizing folder is needed to allow instance-specific customizings
  • /media and /images folders to allow instance-specific uploads

It is also possible to have instance-specific themes. If this should be allowed, /themes folder must be added to the list above. To achieve this, make a customizing of the main installation which changes the values for the constants ASCMS_THEMES_PATH and ASCMS_THEMES_WEB_PATH to the following values:

define('ASCMS_THEMES_WEB_PATH',             ASCMS_INSTANCE_OFFSET.'/themes');
define('ASCMS_THEMES_PATH',                 ASCMS_INSTANCE_PATH.'/themes');

Of course this is possible for all constants. This is possible because of the new PATHCONFIG variables introduced in Contrexx 3.1:

$_PATHCONFIG['ascms_root'] = '';
$_PATHCONFIG['ascms_root_offset'] = ''; // example: '/cms';
$_PATHCONFIG['ascms_installation_root'] = $_PATHCONFIG['ascms_root'];
$_PATHCONFIG['ascms_installation_offset'] = $_PATHCONFIG['ascms_root_offset']; // example: '/cms';

ascms_root and ascms_root_offset contain the filesystem locations for this installation/instance. They can be left empty, since Contrexx 3.1 can guess them correctly. ascms_installation_root and ascms_installation_offset point to the location where the codebase (main installation) lies. For a normal standalone Contrexx installation the latter are identical with the first ones. For a MultiSite instance, the latter point to the main installation (or codebase).

All info about instances that is needed to load one are stored in the file system directly. For each instance, a folder with the domain name is created; for each alias a symbolic link to this folder is created.


Master DNS-zone of the domain used by the MultiSite-system must be managed by the Website Manager Server.


Domain aliases are not possible using a Windows version older than Vista/Server 2008.


In order to ship this module, the following tasks need to be done:

  • Actually make it a module (since it's a core_module by now)
  • Load back-end templates (CSS, images, ...) from main installation (in order to make Multi vHost mode work)
  • Allow domain aliases (/symlinks)
  • Develop copy and move function
  • Find a way to add a vHost in Multi vHost mode (Apache/Plesk/...)