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
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
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: upgradingIf 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 fieldsAs 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 sitesThe following should only be configured on the central site:
- Custom Comcode Tags
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 fieldsCustom 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 forumsComposr 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.
ThemesThe 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 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).
NewsYou 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.
BannersTo 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
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 structuringYou 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.
- 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).
- 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).
- For multiple sub(domain) names, each representing a different zone…
- 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
$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:
$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
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.
Please rate this tutorial:
Have a suggestion? Report an issue on the tracker.