Composr Tutorial: Advanced techniques for multi-site-networks

Written by Chris Graham (ocProducts)

The linking of different installations, linked via a forum, into a 'multi-site-network' (an M.S.N.) is supported by this software. This is an important feature for networks of websites which share a common community, but are segmented, for reasons such as:

Division of staff, either on a hierarchical basis or a basis of co-operation by a loose-knit alliance of websites
Strong division of content, perhaps for sub-branding or clarity
A balance between autonomy and co-operation between websites that wish to share a visitor-base

Table of contents

Composr Tutorial: Advanced techniques for multi-site-networks

Shared forum and members

All that needs to be done to create an M.S.N. is to install each Composr such that they all share a common forum driver and forum database. At its heart, this is all a M.S.N. is: Composr provides special features that allow this to work comfortably, but there is no specific 'M.S.N.' feature or setting in Composr, nor does Composr need such.

The site sharing the forum is the "central site", and all other sites are "satellite sites".

This functionality is not fully supported by the developers. Bug fixes will be produced if the functionality is not working correctly, but it is not proactively and regularly tested. Those relying on it for large deployments should make sure they have appropriate budgets to deal with the maintenance of the volume of sites desired, and to sponsor custom functionality they are likely to want running such a large/custom/special/complex operation. At the time of writing this note (2016), a more normal approach to sharing member databases is to leave it to Facebook, using the Facebook addon to handle log-ins. Usage of Facebook has obvious disadvantages, but also for most people the advantages far outweigh them. Facebook is de-facto the world's standard identity service.

If you are using the Composr forum system (Conversr) as your forum, then it is possible to run Conversr from each site, without members even knowing (from a feature and visual point of view) that a multi-site-network is in action. All you need to do to achieve this is to:

set the forum-base-URL to that of the central Composr site
enable the "Show forum within website" option shown in the screen-shot (available under site configuration)
enable the on_msn installation option

Note that if you do this, and you decide to move a site you are connecting to the M.S.N. with, then URLs may be broken for things such as photos, avatars and attachments – as these get uploaded locally and are stored on the forum using full URLs. In other words, they are not stored on the central site if they got uploaded from a member site, thus the other sites get a dependency on the member site's URL Scheme.

Important notes about Conversr M.S.N. sites:

Each site on the network must have the same setting for "Support content translations". If not, you'll find massive corruption happening.
Each site on the network must be running the same version of Composr.
Local (satellite) privileges and configuration settings are used, not ones from the central forum site: this is actually a feature, as it provides additional control, but it is important to keep in-mind from a security point of view.

Conversr may be administered from an M.S.N. site, although some very minor restrictions are put in place, such as prevention of editing rank and emoticon images.

Special note: upgrading

If you are upgrading to a new major release then you will need to upgrade all the sites together, starting with the central site.

Custom profile fields

As custom profile fields are saved to the central site, the central site will need to have any custom profile fields associated to modules that need to save data for them.

For example, if a site uses points, it'll store them in special CPFs. If the central site has had the points addon removed, then the CPF will no longer exist and sites will not be able to save. Therefore it is best to not remove any addons (especially points) from the central site if you intend to use those addons on some of your other sites.

Editing data on satellite sites

The following should only be configured on the central site:

Custom Comcode Tags
Usergroups
Emoticons

This is so as to:

Ensure consistency between sites
Make sure that any uploads are uploaded to the central site rather than a satellite site (as satellite sites don't have disk write access to the central site)

Custom fields

Custom fields on forum content are not supported across networks. If you set them up they'll only be viewable for the particular site that content is added/edited on, and not show up on other sites.

Comment forums

Composr allows configuration of what forums are used to store portal-generated comments, and support tickets. On an M.S.N. it is important to declare a different forum for each site on the network, in order to prevent conflict.

Themes

The theme management screen (Admin Zone > Style > Themes) will help you understand this – it is difficult to describe in words.

Composr supports a sophisticated theme detection system, whereby Composr themes can be automatically detected based on a priority system:

(whatever a zone might be forcibly set to)
from the "forum-theme-name-to-Composr-theme" mapping of the member chosen forum-themes, if the logged in member has made a choice. In other words, if a member Bob selects a forum theme named ForumFoo, then the Composr theme would be whatever the map says that ForumFoo's Composr equivalent is (e.g. ComposrFoo)
from the "forum-theme-name-to-Composr-theme" mapping of the forum-theme titled after the name of your website name. In other words, if the forum contains a theme titled "My Site" and your website happens to be called "My Site", then then Composr theme would be whatever the map says that MySite's Composr equivalent is (e.g. MySiteTheme)
the Composr default theme

This system is complicated to understand and configure, and is optional, but it is useful for some websites. If you do not wish to use this system, simply manually select which themes to use for each zone, by editing the zone.

Basically, Composr has a file, themes/map.ini, that contains entries that link forum-theme-codes to Composr-theme-codes. Note that the forum-theme-code is not the same as the forum-theme-title: the relationship between these vary between forums, but most forums define both a humanely readable title and a code-name.

The netlink system

The netlink is a simple but useful feature of multi-site-networks. It provides the navigation aid to move between sites on the network, via a simple drop-down list placed on to your panel via the side_network block.

The links available are edited on the central site at:
Admin Zone > Structure > Partner sites

The netlink system can be configured (from the Admin Zone Configuration module) so that all sites on the network point to a shared netlink definition file. The config option allows you to set the URL to the netlink of one of the network sites (usually the central site).

News

You may share news by placing it on the central network site, and using the RSS blocks (set to use the central site's feed) to link to it on the other network sites.

Banners

To share banners across your network, simply add all banners to the central site, and place the URL to the central site's http://yourbaseurl/banner.php script as the only banner in the banner rotation for all the other M.S.N. sites. You may add additional banners to M.S.N. sites if you want to mix central banners with individual rotations.

The staff system

As permissions are set separately on each M.S.N. site (except for forum access permissions), it is possible to assign different staff access to key functions on different sites by usergroup. However, assigning staff is more than a permissive issue, it is also a presentation issue: for the staff module to work, there needs to be some way for Composr to actually list staff other than merely by usergroup permission. This is done via the 'staff filter' feature, available under security/usergroup configuration.

The staff filter works by storing 'staff on' lists under all member profiles that would be staff if the filter was off. These are comma-separated lists of site-names the member is staff-on, and are stored as a hidden Composr custom profile field.

Domain structuring

You can make it so you have a single Composr site that runs across different subdomains. You can also make it so that zones appear to be structured hierarchically.

This is an advanced feature that is not fully supported by the developers. It requires some fairly low level web server configuration to work (i.e. it won't work on many shared webhosts).

The procedure is as follows:

It is strongly recommended, for simplicity and user-friendliness, that you operate Composr from the root of your domain name, e.g. having http://example.com as your base URL.
1. For multiple sub(domain) names, each representing a different zone…
  Set up multiple website profiles in IIS manager / virtual hosts in the Apache configuration file. These profiles must all point to the Composr installation directory (not the zone you're linking the subdomain to).
2. For complex hierarchies:
  Set up virtual directories in IIS manager / directory sections in the Apache configuration file. These virtual directories must all point to the Composr installation directory (not the zone you're linking the subdomain to).
Composr is now set up to receive requests on the various domain names / paths that you have configured. Extra information needs adding to the Composr _config.php, to tell Composr how to map these individual source locations, into zone accesses.
Let's pretend we've added a new subdomain 'forum.mydomain.com' (for the forum zone), and a new virtual directory under our normal website entry, under example/path; we'll point this to the xyz (i.e. we'll map to a zone unrelated to the subdomain name or virtual directory path). You would add this to _config.php

Code (PHP)

$SITE_INFO['ZONE_MAPPING_forum'] = array('forum.mydomain.com','');
$SITE_INFO['ZONE_MAPPING_xyz'] = array('mydomain.com','example/path');

As of Composr 10, you can do this setup in the normal zone management screen. It does save to _config.php though.
Now Composr links point to the proper complex URLs, and the complex URLs are properly recognised as zones.

Please note it is essential to configure your cookie domain to be encompassing of all the subdomains you use. In the above example you would need .mydomain.com to be set as the cookie domain. You cannot use a blank cookie domain.

Many sites, one install (not supported, very advanced)

Composr has some residual support for running many websites of a single install, although not officially supported. We informally refer to this functionality as 'Demonstratr', named after our Composr demoing system.

If run like this, certain functions of Composr, such as e-mail settings, or addon management, are disabled.

The functionality is useful if you are running a massive Composr hosting service, where individual maintenance of each site is not possible. Be prepared to invest serious money or effort to sponsor the upkeep of this Composr functionality, as it has no regular testing or maintenance by core developers.

The support is activated by setting options in the _config.php, like:

Code (`PHP`)

$SITE_INFO['throttle_space_complementary'] = 100; // Allow 100MB of disk space per user

$SITE_INFO['throttle_space_views_per_meg'] = 10; // Every MB of disk space must be accessed 10 times to justify it

$SITE_INFO['throttle_bandwidth_complementary'] = 500; // Allow 500MB of monthly bandwidth per user

$SITE_INFO['throttle_bandwidth_views_per_meg'] = 1; // There must be at least one page view for each MB downloaded

$SITE_INFO['custom_base_url_stub'] = 'http://mydomain.com/sites'; // This should be the same as the 'base_url', with '/sites' on the end

$SITE_INFO['custom_file_base_stub'] = 'sites'; // This should always be 'sites'

$SITE_INFO['custom_share_domain'] = 'mydomain.com'; // This should be the same domain name used in 'base_url'

$SITE_INFO['custom_share_path'] = 'sites'; // This should always be 'sites'

$SITE_INFO['custom_user_someuser'] = 1; // This enables the 'someuser' subdomain

$SITE_INFO['custom_user_someuserwithdomainname'] = 1; // This enables the 'someuserwithdomainname' subdomain

$SITE_INFO['custom_domain_mypersonaldomain.com'] = 'someuserwithdomainname'; // And this maps mypersonaldomain.com to be equivalent to the 'someuserwithdomainname' subdomain

…and splitting up the Composr directory structure so all the site-specific directories (uploads, zone custom pages, etc) are located like sites/someuser. For example, for 'someuser', the following directory structure would exist under the base directory:

sites
sites/www
sites/www/adminzone
sites/www/adminzone/pages
sites/www/adminzone/pages/comcode_custom
sites/www/adminzone/pages/comcode_custom/.htaccess
sites/www/adminzone/pages/comcode_custom/EN
sites/www/adminzone/pages/comcode_custom/EN/.htaccess
sites/www/adminzone/pages/comcode_custom/EN/index.html
sites/www/adminzone/pages/comcode_custom/index.html
sites/www/adminzone/pages/html_custom
sites/www/adminzone/pages/html_custom/.htaccess
sites/www/adminzone/pages/html_custom/EN
sites/www/adminzone/pages/html_custom/EN/.htaccess
sites/www/adminzone/pages/html_custom/EN/index.html
sites/www/adminzone/pages/html_custom/index.html
sites/www/caches/lang
sites/www/caches/lang/.htaccess
sites/www/caches/lang/EN
sites/www/caches/lang/EN/.htaccess
sites/www/caches/lang/index.html
sites/www/caches/guest_pages
sites/www/caches/guest_pages/.htaccess
sites/www/caches/guest_pages/index.html
sites/www/caches/self_learning
sites/www/caches/self_learning/.htaccess
sites/www/caches/self_learning/index.html
sites/www/cms
sites/www/cms/pages
sites/www/cms/pages/comcode_custom
sites/www/cms/pages/comcode_custom/.htaccess
sites/www/cms/pages/comcode_custom/EN
sites/www/cms/pages/comcode_custom/EN/.htaccess
sites/www/cms/pages/comcode_custom/EN/index.html
sites/www/cms/pages/comcode_custom/index.html
sites/www/cms/pages/html_custom
sites/www/cms/pages/html_custom/.htaccess
sites/www/cms/pages/html_custom/EN
sites/www/cms/pages/html_custom/EN/.htaccess
sites/www/cms/pages/html_custom/EN/index.html
sites/www/cms/pages/html_custom/index.html
sites/www/data_custom
sites/www/data_custom/errorlog.php
sites/www/data_custom/index.html
sites/www/data_custom/modules
sites/www/data_custom/modules/admin_backup
sites/www/data_custom/modules/admin_backup/index.html
sites/www/data_custom/modules/admin_stats
sites/www/data_custom/modules/admin_stats/index.html
sites/www/data_custom/modules/index.html
sites/www/data_custom/spelling
sites/www/data_custom/spelling/index.html
sites/www/data_custom/spelling/personal_dicts
sites/www/data_custom/spelling/personal_dicts/.htaccess
sites/www/data_custom/spelling/personal_dicts/index.html
sites/www/exports
sites/www/exports/backups
sites/www/exports/backups/index.html
sites/www/exports/index.html
sites/www/exports/addons
sites/www/exports/addons/index.html
sites/www/forum
sites/www/forum/pages
sites/www/forum/pages/comcode_custom
sites/www/forum/pages/comcode_custom/.htaccess
sites/www/forum/pages/comcode_custom/EN
sites/www/forum/pages/comcode_custom/EN/.htaccess
sites/www/forum/pages/comcode_custom/EN/index.html
sites/www/forum/pages/comcode_custom/index.html
sites/www/forum/pages/html_custom
sites/www/forum/pages/html_custom/.htaccess
sites/www/forum/pages/html_custom/EN
sites/www/forum/pages/html_custom/EN/.htaccess
sites/www/forum/pages/html_custom/EN/index.html
sites/www/forum/pages/html_custom/index.html
sites/www/imports
sites/www/imports/index.html
sites/www/imports/addons
sites/www/lang_custom
sites/www/lang_custom/.htaccess
sites/www/lang_custom/EN
sites/www/lang_custom/EN/.htaccess
sites/www/lang_custom/EN/index.html
sites/www/lang_custom/index.html
sites/www/pages
sites/www/pages/comcode_custom
sites/www/pages/comcode_custom/.htaccess
sites/www/pages/comcode_custom/EN
sites/www/pages/comcode_custom/EN/.htaccess
sites/www/pages/comcode_custom/EN/index.html
sites/www/pages/comcode_custom/index.html
sites/www/pages/html_custom
sites/www/pages/html_custom/.htaccess
sites/www/pages/html_custom/EN
sites/www/pages/html_custom/EN/.htaccess
sites/www/pages/html_custom/EN/index.html
sites/www/pages/html_custom/index.html
sites/www/site
sites/www/site/pages
sites/www/site/pages/comcode_custom
sites/www/site/pages/comcode_custom/.htaccess
sites/www/site/pages/comcode_custom/EN
sites/www/site/pages/comcode_custom/EN/.htaccess
sites/www/site/pages/comcode_custom/EN/index.html
sites/www/site/pages/comcode_custom/index.html
sites/www/site/pages/html_custom
sites/www/site/pages/html_custom/.htaccess
sites/www/site/pages/html_custom/EN
sites/www/site/pages/html_custom/EN/.htaccess
sites/www/site/pages/html_custom/EN/index.html
sites/www/site/pages/html_custom/index.html
sites/www/text_custom
sites/www/text_custom/.htaccess
sites/www/text_custom/EN
sites/www/text_custom/EN/.htaccess
sites/www/text_custom/EN/index.html
sites/www/text_custom/index.html
sites/www/themes
sites/www/themes/default
sites/www/themes/default/css_custom
sites/www/themes/default/images_custom
sites/www/themes/default/templates_cached
sites/www/themes/default/templates_cached/EN
sites/www/themes/default/templates_cached/index.html
sites/www/themes/default/templates_custom
sites/www/themes/default/templates_custom/.htaccess
sites/www/themes/default/templates_custom/index.html
sites/www/themes/default/javascript_custom
sites/www/themes/default/javascript_custom/.htaccess
sites/www/themes/default/javascript_custom/index.html
sites/www/themes/default/xml_custom
sites/www/themes/default/xml_custom/.htaccess
sites/www/themes/default/xml_custom/index.html
sites/www/themes/default/text_custom
sites/www/themes/default/text_custom/.htaccess
sites/www/themes/default/text_custom/index.html
sites/www/themes/admin
sites/www/themes/admin/css_custom
sites/www/themes/admin/images_custom
sites/www/themes/admin/templates_cached
sites/www/themes/admin/templates_cached/EN
sites/www/themes/admin/templates_cached/index.html
sites/www/themes/admin/templates_custom
sites/www/themes/admin/templates_custom/.htaccess
sites/www/themes/admin/javascript_custom
sites/www/themes/admin/javascript_custom/.htaccess
sites/www/themes/admin/javascript_custom/index.html
sites/www/themes/admin/xml_custom
sites/www/themes/admin/xml_custom/.htaccess
sites/www/themes/admin/xml_custom/index.html
sites/www/themes/admin/text_custom
sites/www/themes/admin/text_custom/.htaccess
sites/www/themes/admin/text_custom/index.html
sites/www/themes/admin/templates_custom/index.html
sites/www/uploads
sites/www/uploads/attachments
sites/www/uploads/attachments/index.html
sites/www/uploads/attachments_thumbs
sites/www/uploads/attachments_thumbs/index.html
sites/www/uploads/auto_thumbs
sites/www/uploads/auto_thumbs/index.html
sites/www/uploads/banners
sites/www/uploads/banners/index.html
sites/www/uploads/catalogues
sites/www/uploads/catalogues/index.html
sites/www/uploads/cns_avatars
sites/www/uploads/cns_avatars/index.html
sites/www/uploads/cns_photos
sites/www/uploads/cns_photos/index.html
sites/www/uploads/cns_photos_thumbs
sites/www/uploads/cns_photos_thumbs/index.html
sites/www/uploads/downloads
sites/www/uploads/downloads/.htaccess
sites/www/uploads/downloads/index.html
sites/www/uploads/filedump
sites/www/uploads/filedump/index.html
sites/www/uploads/galleries
sites/www/uploads/galleries/index.html
sites/www/uploads/galleries_thumbs
sites/www/uploads/galleries_thumbs/index.html
sites/www/uploads/repimages
sites/www/uploads/repimages/index.html
sites/www/uploads/index.html
sites/www/uploads/watermarks
sites/www/uploads/watermarks/index.html
sites/www/uploads/website_specific

Composr internally differentiates between the "base URL"/"base directory" and the "custom base URL"/"custom base directory", so as to know when to load shared files, and when to load custom ones that relate to a specific site.

In addition, each site must have a database of its own:

This should be named the same as the normal site database is named, except with a suffix or an underscore followed by the username (e.g. examplesite_someuser).
The database username should be formed by taking the normal site database username and then suffixing with an underscore and then the username, and then generating the MD5 hash of that, and then taking the first 16 characters. This is intentionally obfuscated, to make it slightly harder to hack.
The database password should be the same as for the normal database.

For the server configuration side of things you need to configure Apache to accept all page requests to a single IP address regardless of domain name, and set up a "wildcard DNS" entry – which is just a normal subdomain entry to that IP address, except a '*' is in place of the normal subdomain name.

Composr does not contain a way for individual sites to be set up automatically out-of-the-box, but developers have in the past set up code for clients to do this; for example, via an eCommerce product. In these scenarios it is common to create the new sites automatically be extracting a TAR file to create the sites/whateveruser directory automatically, and also importing an SQL file into the new correctly-named database; together the TAR and SQL would form a template for each new site.

Concepts

M.S.N.: A multi-site-network: a network of Composr sites that share a member community. Composr provides special features that are designed for such a situation
Central site: A site on an M.S.N. that is not a central site
Satellite site: The site-jump system intended for multi-site-networks
Netlink

Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.

Composr Tutorial: Advanced techniques for multi-site-networks

Shared forum and members

Special note: upgrading

Custom profile fields

Editing data on satellite sites

Custom fields

Comment forums

Themes

The netlink system

News

Banners

The staff system

Domain structuring

Code (PHP)

Many sites, one install (not supported, very advanced)

Code (PHP)

Concepts

See also

Feedback

Code (`PHP`)

Code (`PHP`)