Page tree
Skip to end of metadata
Go to start of metadata

This page and its subpages explain how to use the Multisite module to set up and run multiple websites from one Magnolia installation.

Maintaining multiple websites is facilitated by defining multiple site definitions. You need an Enterprise Pro license to properly run the Magnolia Multisite module. 

The page presents a few typical use cases for a multisite setup and the corresponding configuration required. Full working examples of certain use cases are in the subpages. We assume that you already know some basics about a Magnolia site definition

Overview

Typical use cases

Using multisite makes sense in the following scenarios:

How multisite works

In the Multisite module, you configure two important elements:

  • Site definitions
    The Multisite module is delivered with one default site definition called fallback. When developing your multisite project, you configure your own site definitions. Every site definition can have its own theme and template prototype. A site definition contains a domain mapping and mapping to a node in a repository (URI2RepositoryMapping).
  • Site resolution rules
    The site resolution rules ensure that Magnolia can properly assign a site for a given request. The Multisite module comes with a standard set of site resolution rules. The standard rules usually are sufficient. We strongly recommend you be careful if you choose to change these rules. 
    When a request is sent to Magnolia, MultiSiteFilter analyses the request to determine which site definition it fits. Once the site has been determined, it is set to the AggregationState from where it can be read during further request processing.

Setting up multisite - main steps

The following bullet points summarize what you need to do to set up a multisite environment with one Magnolia installation:

  • Create trees or subtrees of JCR nodes (usually pages) with different purposes.
  • Configure site definitions. For each one, define:
    • A mapping pointing to the tree or subtree of JCR nodes (usually pages).
    • A domain mapping to map a domain to the site.
  • Access the distinct content (sub)trees via distinct domains.

When the Multisite module is enabled, you must configure at least one site definition including a proper domain mapping. If you do not do so, pages are not served correctly on the public instance.

Magnolia setup and domains in a production environment

Magnolia is distributed as two web-applications: author and public. Among other things, editors create pages on the author instance and publish content from the author instance to public instances. Public instances serve the content to visitors. In a typical production setup you have one author and several public Instances

In a production setup, the author instance and public instance are typically accessed via distinct domains.

Best practice

In a multisite setup with one Magnolia installation, you assign multiple domains to the public instance. However, it is sufficient and recommended to have only one domain pointing to your author instance. The domain of the author instance is different from the domains of the public instance.

Example of domains in a production environment

This table shows the difference between domains when pointing to author or public instances in a production environment. 

 author instancepublic instance
Distinct sites
site a
author.yourdomain.net

www.yourdomain.net

site bwww.another-domain.net
Subsidiaries or localized sites
Main site


author.xyzdomain.com

www.xyzdomain.com
German country sitewww.xyzdomain.de
French country sitewww.xyzdomain.fr

Serving the webapps from root context

In a production environment, you access the public instance by requesting the root path of the domain. For example, when you request www.yourdomain.net you expect it to serve the webapp typically called magnoliaPublic. The same is true for the author instance: you expect author.yourdomain.net to serve the webapp called magnoliaAuthor.

If you run a bundle on localhost, you request the public instance using http://localhost:8080/magnoliaPublic. In this case, the webapp magnoliaPublic is served from /magnoliaPublic.

In a production environment, serve the webapps from the root context instead.

Application servers such as Tomcat generally only serve one webapp from root context within the same connector. However, in a production environment, you typically run the author instance and the public instance in different networks. Alternatively, you may run two Tomcat instances on the same host, or run one Tomcat instance with two connectors.

Mapping multiple domains to the application server

In a production environment, you typically use a web server such as Apache in front of Tomcat. Read Apache httpd in front of Tomcat to get some ideas about such a setup. When using the Apache HTTP Server (Apache httpd) and Apache Tomcat together, mod_jk or mod_proxy_ajp can be used to redirect from Apache httpd to Tomcat.

In a multisite setup, where your public context serves content for multiple domains, you must map multiple domains to your application server (such as Tomcat). If you use a web server in front of the application, you must define multiple virtual hosts on the web server to redirect the request from Apache http to Apache Tomcat.

 Click here to expand to see an example of virtual hosts setup

<VirtualHost *:80>
 ServerName www.best-comics.net
 ProxyPass / ajp://localhost:8010/
 ProxyPassReverse / ajp://localhost:8010/
</VirtualHost>
 
<VirtualHost *:80>
 ServerName www.best-vinyl.net
 ProxyPass / ajp://localhost:8010/
 ProxyPassReverse / ajp://localhost:8010/
</VirtualHost>

In this example, the Apache modules proxy_ajp_module and proxy_module are used to redirect the request to Apache Tomcat using the Apache JServ Protocol (AJP). The example shows two virtual hosts both redirecting to the same Magnolia public instance.

Fallback site

The multisite module provides a fallback site. The fallback site is a special site definition that is used when no site matches the request. 

Do not delete or rename the fallback site.

When using multisite, it is common to have one main site and some additional sites. It generally makes sense to adapt the fallback site so that it extends your main site.

For example, the Magnolia Travel demo has two sites: travel-demo and sportstation. When the demo modules are installed, the fallback site is changed to extend travel-demo site.

Without the demo modules, the configuration of the fallback site looks like this:


Node nameValue

 fallback

 

 mappings

 

 extends

override

 domains

 

  extends

override

Configuration

This section is about site definition configuration in the context of multisite. It explains how to configure multiple, distinct site definitions which require the definition of  domains and mappings nodes.

We assume that you already know some basics about Magnolia site definition configuration (such as prototypes, themes, imaging variations and sitefn templating functions). 

Site app

The Site app allows you to configure a site definition. Go to Web Dev > Site to open the app.

If your bundle contains the Multisite module, the Site app shows the node /modules/multisite/config/sites from the configuration workspace.

When you open the Site app you see all configured sites as top-level nodes:


Node nameValue

 fallback

 

 comics-site

 

In this example there are two sites: fallback and comics-site.

Site definition name

The node name of the site definition is called site-definition-name.

If a site is properly configured, it can be accessed using the following URL:

<protocol>://<domain>:<port>/<context>/<site-definition-name>

Note that this only works if the domain part of the URL is different from the domain that is mapped to the site of the given site-definition-name

Mappings and domains

The mappings and domains nodes are required in a multisite context. You must create a least one entry on both mappings and domains to ensure a proper site definition for a distinct site.

Example:


Node nameValue

 comics-site

 

 mappings

 

 website

 

 URIPrefix

 

 handlePrefix

/comics

 repository

website

 jolly-jumper


 URIPrefix

/jollyjumper

 handlePrefix

/comics/belgian-comics/morris/lucky-luke/jolly-jumper

 repository

website

 domains

best-comics

 name

www.best-comics.net

The site defined above allows you to access:

Best practice

Use different values for the site-definition-name and the name of the mapped node (handlePrefix).

mappings configuration

The mapping nodes define the JCR content nodes (usually page nodes) assigned to the site definition.

A mapping has the following properties:

<mapping-node>

required

Each site can contain multiple mappings. The name of a mapping node is arbitrary. (In the example above, the node name is website.)

The corresponding java class for a mapping is URI2RepositoryMapping

repository

required

Name of the JCR workspace the mapping applies to.

handlePrefix

required

The path in the workspace the content is served from.

URIPrefix

required

Creates a node handle based on a URI. By default, a content request that does not contain a prefix is served from the node defined on handlePrefix of the given repository.

The URIPrefix property can be used to shorten URLs. (See the jolly-jumper example above and the Multisite example - Shorten URL with handlePrefix example.) Short URLs are easier to remember, quicker to type, take less space in print ads, and are ranked more favorably by search engines than content deep down in the site hierarchy. 

(warning) If this property is not set, MultiSiteURI2RepositoryManager throws an exception (leading to runtime exception and a server error 500). Add the property with an empty value (or /) if you do not need it.

Note that URIPrefix configuration can also be applied in modules independent from site definitions.

Configuration in the site definition overrides the configuration in /server/URI2RepositoryMapping/mappings/<workspace>, resulting in site-specific definitions. 

domains configuration

A domain node assigns a domain to the given site definition. It defines how the above mapped content node(s) can be accessed by URL. You can map multiples domain to the same site.

A domain mapping has the following properties:

<domain-node>

required

The name of a domain mapping node is arbitrary. You can apply multiple domain nodes per site.

name

required

Domain name such as www.best-comics.net.

port

optional

Port represents the port the web application was deployed on.

Default is 80.

protocol

optional

HTTP or HTTPS.

Default is HTTP.

context

optional

The context path of the Magnolia instance webapp such as magnoliaAuthor or magnoliaPublic.
You do not need to set the context property if the webapp is served from root context.

The optional properties portprotocol and context are only used to build links between the pages of different sites. In a typical production setup, where you serve the webapps from the root context on different domains, you do not have to set port and context.

Extending site definitions

Another configuration strategy is to have one site definition for your main site with a template prototype that you can then reuse on other site definitions.  This is a common alternative to having multiple independent site definitions.  

In the example below, site-2 and site-3 inherit from site-1.


Node nameValue

 site-1

 

  site-2


 extends

../site-1

  site-3


  extends

../site-1

(warning) Inheriting mappings and domain can lead to unexpected results and may destroy your site setup.

Best practice

When extending site definitions, turn off inheritance for mapping and domains by using @extends=override.



Node nameValue

 site-1

 

 site-2


 extends

../site-1

 mappings


 extends

override

 domains


 extends

override

Removing unwanted virtualURIMapping on public context

Make sure you have no unwanted virtualURIMapping redirections on the public context.

Use the Configuration app on the public context and search for virtualURIMapping. On a standard Magnolia bundle you most probably find the node /modules/ui-admincentral/virtualURIMapping/default which redirects to /.magnolia/admincentral. You must delete the node to ensure a request to http://<your-domain>/ really serves the root page of your site. (For further details look at the example). 

Site resolution rules

The site resolution rules ensure that Magnolia can properly assign a site for a given request. The Multisite module comes with a standard set of site resolution rules. The standard rules usually are sufficient

If you change the site resolution rules, verify your changes on a test system before making any changes to your production environment. Errors in the site resolution rules can break your site.

Rule configuration

The multisite site resolution rules are configured below the node /modules/multisite/config/rules

Node nameDescription
 modules
 

 multisite

 

 config

 

 rules

 

 uri-starts-with-sitename

 

 domain-and-uri-prefix-not-empty


 domain-and-handle-not-empty


 domain-and-site-uri-prefix-empty


 uri-prefix-not-empty


 handle-not-empty


Note that every rule contains one or more configured Matcher classes.

Disabling the uri-starts-with-sitename rule on the public instance

The uri-starts-with-sitename rule is a cross-site-evaluation rule that enables you to access a site using its site-definition-name from another domain. This is desired and required on the author instance, which typically runs on a domain different from the domain(s) mapped to a site definition(s).

If you have two site definitions, this rule allows you to access site A from the domain which is mapped to site B. This is typically not desired on a public instance.

Best practice

Disable the uri-starts-with-sitename rule in the public context.

Add an additional voter AdminOnlyMatcher to the rule. This way you can use the same configuration on both the author and public instances.


Node nameDescription

 rules

 

 uri-starts-with-sitename

 

 matchers


 0


 class

info.magnolia.multisite.sites.matchers.SiteNameMatcher

 1


 class

info.magnolia.multisite.sites.matchers.AdminOnlyMatcher

 multipleMatchesPossible

false

Matcher 0 is set by default in the uri-starts-with-sitename rule. Add AdminOnlyMatcher as a second matcher to ensure the rule is applied in the author instance only.

Custom site resolution rules and matcher classes

You can write your own custom matcher classes to create new rules. The custom class should extend AbstractMatcher, which implements the RequestMatcher interface.  

Examples

To understand multisite setup in different use cases, look at the following examples:


  • No labels

1 Comment

  1. I might come back at you in the near future and will provide yet another bit of information for this documentation. We figured out how to setup the CrossSiteSecurityFilter for above scenarios. This would be an ideal addition to this site.