Multisite support is an Enterprise Edition Pro feature provided by the Multisite module. It allows you to manage multiple websites in a single Magnolia instance. Each site has its own site definition which can apply unique templates, themes, variations, domains and locales to the site. Besides making each site unique, the multisite feature lets you inherit features from another site.
You can use multisite support for microsites, campaigns, events and product launches. A microsite can inherit page templates from the parent site, yet have its own theme and domain. You save time and effort by not having to create new templates. Sites that are localized to the visitor's language or geographical area can inherit templates and themes from a parent site and add their own locales to support additional languages and country-specific domains.
Multisite requires an Enterprise Edition Pro license. You can create multiple site definitions also in EE Standard but you need an EE Pro license to unlock the multisite feature. With an EE Standard license, the system only takes the default site definition into account and will ignore additional site definitions.
If you do not need Multisite, remove the Multisite module jar from the bundle before you install Magnolia. Working with the Multisite module installed on EE Standard (running a single website) leads to logging errors. Due to module dependencies it is very difficult to uninstall the Multisite module once a website is running.
About site definitions
A site definition is responsible for assigning the following elements to a website:
- Templates defines which page and component templates are available on the site.
- Variations output content in various forms and formats.
- i18n (internationalization) configuration allows you to serve sites in the visitor's language or geographical location.
- Mappings identify where content for the site should be served from.
- Domains allow branding and localization.
Default site definition
default site definition is the fallback configuration for all sites and is the basis for site-specific definitions. It includes:
- Template prototype configuration in
- Page templates available on a global level in
- Assignment of the default
- Variation configurations in
Internationalization settings in
Node name Value default
Individual site definitions
Each site requires its own site definition. The individual site definitions use the extends mechanism to extend the
default definition. This means they use the
default configuration and make exceptions for site-specific additions and changes.
Here are a few suggestions that you can configure in an individual site definition:
- A site-specific template prototype that change the navigation or creates new areas.
- Make unique page and component templates available to editors.
- Reference a unique theme.
The multisite feature uses Magnolia''s core URI2RepositoryMapping (Git) mechanism to map a site definition to a site. This means that the mechanism examines the requested URL and serves content from one of Magnolia's workspaces accordingly.
The most common use case is mapping a URI to the
website workspace and serving a Web page. Content is served from the
website workspace by default if the request does not contain a prefix. If a prefix such as
dam is detected the requested content is served from the workspace configured in the
repository property. For example, if the requested URL contains
/demo-project alone, the system maps the request to the
website workspace. If the request contains
/demo-project/docs you could map the request to the
dam workspace instead.
handlePrefix property defines the path where content should be served from. In the
demo-project website the handle points to
/demo-project and in
/demo-features. These are the respective root nodes of the sites.
The handle prefix is useful when you point it to a node deeper in the site hierarchy. For example, suppose you have built a winter clothing campaign in
handlePrefix to this path will apply the site definition to that branch of the site only. Now content for the site will be served from the branch. In the same site definition you could configure a custom winter theme for the campaign and assign a vanity URL such as
winter2013.example.com. Visitors who request the vanity URL are served content from
/demo-project/campaigns/winter2013, not from the site root, and they see the campaign specific theme.
URIPrefix property is used to inject a path into a URL in order to shorten it. Shorter 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.
Suppose your marketing campaign resides deep in the site hierarchy at
/demo-project/marketing/campaigns/2013/winter. First set
handlePrefix to this path so that content is served from the right place. Then shorten the URL by setting
/winter2013. Visitors who request the URL
www.example.com/winter2013 are served content from
/demo-project/marketing/campaigns/2013/winter but the URL they type is short and friendly.
The standard URI2RepositoryMapping mechanism is enhanced by the following classes in the Multisite module. They add multisite and domain support.
You can map a domain name to a site in the
/domains node. Mapping domains in Magnolia empowers editors as there is no need to configure a Web server. As a prerequisite, make sure the domain's DNS entries point to the Magnolia server. When visitors access the site with the domain name, content is served from the location identified by the
context: Context path represents a web application such as
magnoliaPublic. Context and port are needed to make links between sites work. You do not need to set these properties if you deploy to root context and default port.
name: Domain name such as www.example.com.
port: Port number such as 8080. Context and port are needed to make links between sites work. You do not need to set these properties if you deploy to root context and default port.
protocol: Protocol such as HTTPS. Default is HTTP.
DomainNamePathTransformerconstructs URLs by prefixing the path with
Server.getDefaultBaseUrl()and domain name.
CrossSiteAbsolutePathTransformerconstructs URLs by prefixing the path with
Server.getDefaultBaseUrl(), domain name and site name.
You can map multiple domain names to the same site. This is useful for covering top-level domains such as
.org and setting localized prefixes for sites like
Much of what can be done with domain mapping can also be done with virtual URIs. As a rule, virtual URI mapping should only be used for a small number of pages and for temporary purposes. For example, you could use a virtual URI for a Christmas campaign but once your campaign becomes a Christmas shop you should assign a site definition to it and make it a site. Defining a site opens up options such as themes and i18n support.
Request matcher rules
When a request arrives to Magnolia it needs to be matched to a site so that the right content is served.
MultiSiteManager is the class that matches requests to a site in a multisite environment. Request matcher rules ensure that the correct content is served. You can configure request matcher rules in the module configuration. Magnolia 5.2.6+ / Multisite 1.0.5+ and Magnolia 5.3.2+ / Multisite 1.1.1+
For complex multisite structures, you can configure precise matcher rules that take account of every possibility. Matcher classes for all properties in the site definition, and well as the site name, are provided.
The rules are resolved in the order in which they are configured, with higher configurations taking precedence. All rules are evaluated and the best-matching site served. The rules apply to all configured sites.
The default configuration in
/modules/multisite/config/rules should suffice in most environments.
|URI starts with site name: /site-name|
|Domain and not empty uri prefix (subsites)|
class: Matcher class.
description: Describes what the configuration does.
multipleMatchesPossible: Whether the rule allows more than one match. When set to
false, if two site definitions match, the rule is bypassed.
info.magnolia.multisite.sites.matchers.SiteNameMatcher: Checks the sitename (root node of the site in Pages).
info.magnolia.multisite.sites.matchers.DomainMatcher: Checks the domains configured in the site definition.
info.magnolia.multisite.sites.matchers.AdminOnlyMatcher: Checks the context (author or public), matches only on an author instance.
info.magnolia.multisite.sites.matchers.NotEmptyUriPrefixMatcher:Checks for a
URIPrefixproperty in the mappings node of the site definition.
info.magnolia.multisite.sites.matchers.NotEmptyHandleMatcher: Checks for a handlePrefix property in the mappings node of the site definition.
info.magnolia.multisite.sites.matchers.SiteHasEmptyUriPrefixMatcher: Checks for an empty URIPrefix property.
uri-starts-with-sitename: Site name matches. URI starts with site name: /<site-name>. Single-class rule uses
SiteNameMatcher. Multiple matches not possible.
domain-and-uri-prefix-not-empty: Domain matches and URI prefix is not empty. Used for subsites. Dual-class rule uses
NotEmptyUriPrefixMatcher. If a matching domain and URI prefix are found, the rule is bypassed. Multiple matches not possible.
domain-and-handle-not-empty: Domain matches and handle is not empty. Used for AdminCentral access. Dual-class rule uses
NotEmptyHandleMatcher. If a matching domain and handle prefix are found, the rule is bypassed. Multiple matches not possible.
domain-and-site-uri-prefix-empty: Domain matches and the URI prefix is empty. Used for main site. Dual-class rule uses
SiteHasEmptyUriPrefixMatcher. Multiple matches not possible.
uri-prefix-not-empty: URI prefix is not empty. Used for subsites that have a URI prefix. Single-class rule uses
NotEmptyUriPrefixMatcher. Multiple matches possible.
handle-not-empty: Handle matches. Used for AdminCentral access. Singe-class rule uses
NotEmptyHandleMatcher. Multiple matches possible.
You can write your own custom matcher classes to create new rules.
The custom class should extend
AbstractMatcher that implements the
RequestMatcher interface. The interface matches requests (domain and URI) to a site. It returns an integer, minus is false, and positive is true. The return value of
@link #matches(String, String, info.magnolia.module.templatingkit.sites.Site) is used to filter the best matching request.
The first three examples demonstrate the default behavior. The last example provides a scenario where it is necessary to change it. You can replicate the examples on the demo sites. The examples assume you have mapped the domains to your system
hosts file and are working locally. Domains used are
No site definition
- Set up a new site with the following structure:
Company A site renders because it is the best-matching site. The
uri-starts-with-sitename rule finds a match to the site name. No other rules are met.
Best practice is to always configure a site definition.
Domain and handle prefix
companyA site definition that extends
/domains/companyA/nameproperty set to
You can now request the Company A site at
domain-and-handle-not-empty rule is met. Both the domain and handle prefix match. The pop theme is applied by extension.
Domain and URI prefix
In the site definition created in the previous example, in
When you request
www.domain1.com:8080/magnoliaAuthor/ you are redirected to the app launcher because the URI prefix is no longer empty. When you request
www.domain1.com:8080/magnoliaAuthor/investors , the Investors page renders as the
uri-prefix-not-empty rule is met.
In this example the default configuration does not serve the correct content and new rules need to be configured.
The use case could, for example, be a large corporation with a number of divisions. The corporation itself and each division has its own website and domain. Each site has a site definition that is mapped to the domain and root page (
The following site structures do not result in a conflict.
Top level site
Top level site
However when you add the subpages highlighted below, the default rules no longer resolve all requests correctly because there is a URI conflict. Both sites have subpages with identical names to top-level sites.
When you request the Division A page on the Corporation site, the
/division-a site renders instead of the
/corporation/division-a page. When you request the Corporation page on the Division A site, the
/corporation site renders instead of the
/division-a/corporation page. This is because there is no configured rule to take account of the situation.
Here's the configuration to correct this behavior. The configuration replaces the default
uri-starts-with-sitename rule with the
domain-and-sitename rule that requires both the domain name and site name to match.
|Domain and URI starts with site name: /<site-name>|
After configuring the new rule. the correct sites and subpages render.
Internationalization support is provided by
info.magnolia.multisite.i18n.MultiSiteI18nContentSupport. This class is configured in the Configuration app >
/server/i18n/content and it delegates to the i18n support configured in a site definition.
i18n configuration is typically in the
default site definition. Site-specific site definition can extend and override it. See Site definition > i18n for more about the
default configuration. In the
/demo-project-de definition the
defaultLocale is changed from
MultiSiteFilterinitializes the multi-domain support and makes domain related properties available in the aggregation state.
CrossSiteSecurityFilterdoes cross-site security checking based on the
domainPattern. For more information see Cross-site security
SiteUriSecurityFilteris a site-aware URI security filter. For more information see Site-aware ACLs.
When content is published, the cache on the public instance is flushed to show the new content. This increases the load on the server and affects all sites in a multisite environment. You can configure multiple cache configurations to ensure that only cache entries that belong to the same subree (site) as the published content are flushed. See Multisite cache configuration for more.