Guide to using MultiTenantInterceptor - tooltwist/documentation GitHub Wiki

This guide is used to configure ToolTwist's interceptor for multi-tenant websites. This interceptor provides generic functionality that will handle most multi-tenanting requirements, however a custom interceptor can also be written to handle more application-specific requirements. In any case, this document will provide a useful understanding of the concepts involved.

Note: This interceptor provides multi-tenantin where the domain name defined the tenant. For example http://phil.tooltwist.com/... If you wish to use the URL to switch between tenants, such as http://.../phil/portal/x, then see Guide to using MultiTenantByUrl.

A multi-tenant website is where a single web server instance is supporting multiple websites. Multiple domains are all directed to the same web server, and the web server uses this domain name to determine what should be displayed.

The most common use of multi-tenanting is for cloud based services. In order to keep cost and administration low, we don’t want to set up a hundred servers for a hundred customers if the server load is low for all those sites. Instead, a hundred sites can be placed on a single server.

For additional information see this whitepaper.

In this environment, it is essential that the operation of one site does not influence the operation, or access the functionality of other sites. There must be absolute separation of the sites, their functionality and their data, such that they remain independent of each other.

As an example, if we are running one hundred eCommerce sites all with the same functionality, it is critical that the products, shopping carts, and order histories from one site aren’t visible from the other sites. Similarly orders and payments must not cross over between the sites.

For simplicity’s sake we’ll use eCommerce stores to describe how multi-tenanting is implemented, but the same applies for other applications and websites.

To implement multi-tenanting, the MultiTenantInterceptor is used. This lightweight interceptor loads it’s configuration from $TOOLTWIST_HOME/conf/multi-tenant.xml, and like all interceptors is called before every ToolTwist page is displayed. Here’s it’s basic functionlity:

• check that the domain name in the user’s browser maps to a defined site.
• check the navpoint may be accessed.
• set session variables specific to this site, that may be used by application functionality
• navpoint mapping
• let control pass on to the navpoint rendering

In most cases multi-tenanting is used to provide multiple versions of the same application, however this need not always be the case. It is quite possible to run multiple applications as multi-tenanted sites. In ToolTwist terms, this involves running multiple web design projects in the same server.

However care must be taken to ensure that the functionality of one application does not impact another. Extra care must be taken to ensure there are no conflicts in JVM memory (use of static objects, etc), at the database level, or in connectivity with external systems.

When different domains map to different applications, we need to ensure that each domain name can only access the navpoints relevant to the site.

There are many ways to change the appearance of each of the hosted websites, even though they might use the same web design project and extension projects. Here’s a few common examples:

Logos and other images are commonly changed moving from one store to another.

The ZZZ widget can be used to do this.

The color scheme, fonts, and overall appearance of pages can be adjusted according to the site.

The ZZZ widget is often used for this.

Any custom widget can change the way it operates, according to the current domain name. A common approach is to set a define a variable in the interceptor configuration (e.g. color scheme) which will be used by the widget logic.

Sometimes the appearance of pages must be completely changed, or a different site map used. To do this multiple versions of the site may be created within the web design project, and domain name used to limit access to a single hierarchy of navpoints.

Mapping can also be defined, for example to route to home page to the correct navpoint hierarchy.

When multi-tenanting, it is essential that every database select or update only accesses data related to the domain name in use. Your database will need to also support multi-tenanting, by segmenting the database according to some identifier (for example, store ID).

Then, within your application you can define a storeId for each site in the interceptor config file, and this will be added as a session variable every time the user accesses the domain. Your application logic can then include that store identifier in every database access or update.

In some cases, a multi-tenanted front end may route requests to multiple back end systems, such as payment gateways, ERP systems, freight calculations, etc. The exact back end system to use, and the data passed to it, will vary according to the site (domain name) being used.

For example, the payment gateway and details used to make a payment on aaa.com will be quite different to those for bbb.com. The logic used to access backends is part of the application, but the details used can be defined in the interceptor configuration file and accessed as session variables described in the previous section.

<site>
	<servername>dev1</servername>
	<webdesignProject>ttdemo</webdesignProject>
	<navpoint>ttdemo-1</navpoint>
	<properties>
		<theme>blue chicken</theme>
		<paymentGateway>paypal</paymentGateway>
		<paypalClientId>171262535141</paypalClientId>
	</properties>
</site>

<site>
	<servername>dev3</servername>
	<webdesignProject>ttdemo</webdesignProject>
	<navpoint>phil-333</navpoint>
	<properties>
		<theme>cool sunset</theme>
		<paymentGateway>paypal</paymentGateway>
		<paypalClientId>9928877772</paypalClientId>
		<freddo>frog</freddo>
		<wallace>grommet</wallace>
	</properties>
</site>

In a multi-tenanted site, sites may be added or removed at any time, and you don’t want to shut down all the sites each time you make a change. To allow changes to be made on-the-fly, a special URL may be used to reload the multi-tenanting config.

    http://hostname:port/ttsvr/n/tooltwist.multitenant.reload

Phil: I’m not sure how SSL certificates might be handled on multi-tenant websites.

—