The core of multisite functionality lies in the use of site definitions.
A site definition allows you to control each website separately, for example, configuring different languages or domains per website.
Using the Multisite module, you can set up and run multiple websites with different domains and languages from one Magnolia installation.
We present 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.
Site limitation
In DX Core, the number of sites that can be used is defined by the
number of sites purchased.
In the Community Edition, you can only create and use one site.
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.
Since version 3.0.0 of the Multisite module, site definitions are no longer configured in the config folder of this module, but in the sites subfolder of any module.
You can configure a site in a YAML definition (preferred) or directly in the JCR Configuration app.
Overview
Typical use cases
Using multisite makes sense in the following scenarios:
You have different websites for subsidiaries and country branches.
You have localized versions of the same website.
You use handles and URI prefixes to get shorter URLs.
How multisite works
You can have one site definition per website.
In Magnolia 6.3, site definitions are registered in light modules and not directly in the multisite module, which was the case in Magnolia 6.2.
You can control each website independently. Some important aspects of the site definition are explained below.
Site definitions
When developing your multisite project, you configure your own site definition.
For public instances, we strongly recommend that you map the domains served to their websites unless they are microsites, which mostly won’t have domain mappings.
This allows the mapped content to be served to its respective domain.
Optionally, you can add languages.
For more on defining locales, see Define locales for the site.
The Multisite module is delivered with one default site definition
called fallback, for details see the Fallback site page.
In the Multisite module, you can optionally configure site resolution rules.
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, info.magnolia.multisite.filters.MultiSiteFilter analyzes the request to determine which site definition it fits. Once the site has been determined, it is set to info.magnolia.cms.core.AggregationState from where it can be read during further request processing.
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.
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 sample below shows the difference between domains when pointing to author
or public instances in a production environment.
Site
Author Instance
Public Instance
site a/b
author.yourdomain.net
www.yourdomain.net (a)
www.another-domain.net (b)
Main/German/French
author.xyzdomain.net
www.xyzdomain.com (Main)
www.xyzdomain.de (DE)
www.xyzdomain.fr (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
http://www.yourdomain.net, you expect it to serve
the webapp typically called magnoliaPublic. The same is true for the
author instance: you expect
http://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.
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.
Think of it as a default.
Creating a fallback.yaml file in a light module’s sites folder overrides the default fallback definition.
A fallback definition is created automatically by info.magnolia.multisite.sites.MultiSiteManager#createDefaultFallbackSite if no fallback exists (file-based or in the JCR).
In Magnolia 6.2, a fallback site could be a folder.
In Magnolia 6.3, it has to be a node.
Choosing a fallback site definition
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.
Use the inherit property to reference a complete site definition.
For example, the Magnolia Travel Demo has two sites: travel-demo and sportstation.
When the demo modules are installed, you can change the fallback definition to extend travel-demo site.
The fallback definition filename must be named fallback.yaml.
Full qualified fallback configuration
Fallback config inherited from travel-demo
<my-light-module>/sites/fallback.yaml example definition
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).
The sites folder
You can configure sites in the sites folder of any module using YAML. See, for example, the following site definitions:
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.
The configuration name for the domain is arbitrary.
2
Mapped content is served to this domain name.
The site defined above allows you to access:
The content node /comics via the URL
http://www.best-comics.net.
The content node
/comics/belgian-comics/morris/lucky-luke/jolly-jumper via the URL
http://www.best-comics.net/jollyjumper.
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:
Property
Description
<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 class for a mapping is
info.magnolia.cms.beans.config.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.
If this property is not set,
info.magnolia.multisite.MultiSiteURI2RepositoryManager
throws an exception (leading to a 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:
Property
Description
<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 http://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 port, protocol 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 or property
Value
site-1
site-2
extends
../site-1
site-3
extends
../site-1
Inheriting mappings and domain can lead to unexpected
results and may destroy your site setup.
When extending site definitions, turn off inheritance for mapping and
domains by using @extends=override.
Node or property
Value
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.
Configuration examples
To understand multisite setup in different use cases, look at the following examples: