Deploying a WAR on Apache Tomcat
A WAR file is provided for the Apache Tomcat installation that contains
many of the files needed for Magnolia. When the WAR file is deployed,
the files in the WAR file are extracted and placed in the server’s
webapps
directory. The remaining directories and files, including the
repositories, are retrieved during the deployment and installation.
Server configuration with Advanced query filters in the Delivery API require extra Tomcat configuration, namely setting |
Deploy WAR
Tomcat should not be running when executing the following procedure.
To deploy WAR file:
-
Download DX Core or Community Edition WAR file.
-
Put WAR file into server’s
webapps
directory. -
Adapt JVM heap size by editing the applicable file in the
/bin
directory in the Apache Tomcat directory:-
On Unix, edit
setenv.sh
file and add:
export CATALINA_OPTS="-server -Xmx1024m"
-
On Windows, create
setenv.bat
file and add:
set CATALINA_OPTS=-server -Xmx1024m
-
-
(Optional) Use headless mode.
When running on a system without a GUI, you should set the
java.awt.headless
system property to true.-
On Unix:
export CATALINA_OPTS="-server -Xmx1024m -Djava.awt.headless=true"
-
On Windows:
set CATALINA_OPTS=-server -Xmx1024m-Djava.awt.headless=true
-
-
Start Tomcat and wait until it is completely started.
When deploying the Magnolia WAR file Tomcat will need time and heap size to extract the file and bootstrap repositories. Once bootstrapped, Tomcat will not need that much heap anymore. |
A directory containing the content of the WAR file and retrieved files is created in the server’s webapps
directory.
Tomcat configuration
If you need to configure Tomcat to use virtual hosts, data sources and so on, see the Tomcat Documentation.
Disclosing potentially sensitive information
By default, the magnolia-tomcat-barebone
provided by Magnolia (Nexus) will not disclose potentially sensitive information, such as details about errors or server type and version.
Any custom error page for errors which can’t be mapped to pages declared in web.xml
can be changed accordingly by modifying the configuration in server.xml
.
Examples
<Valve className="org.apache.catalina.valves.ErrorReportValve"
errorCode.0="webapps/ROOT/errorOthers.html"
showReport="false"
showServerInfo="false" />
<Valve className="org.apache.catalina.valves.ErrorReportValve"
errorCode.400="webapps/myMagnoliaApp/docroot/my400.html"
showReport="false"
showServerInfo="false" />
In Tomcat’s log, an admin can still see what caused the error, though.
For instance in localhost_access_log_xxx.txt
, one could see:
0:0:0:0:0:0:0:1 - - [30/Jun/2022:09:50:53 +0200] "GET /magnoliaAuthor/()%7B%7D[] HTTP/1.1" 400 435
Known issues
Unable to log in with an SSO/OpenID setup
Starting with Magnolia 6.2.10, in your Tomcat configuration, make sure that the CookieProcessor
component
does not have the sameSiteCookies
property set to strict
. Instead, set the property to Lax
:
<CookieProcessor sameSiteCookies="Lax" />
This supports OpenID top-level redirects while maintaining decent protection against cross-site request forgery (CSRF).
Before Magnolia 6.2.10, Lax
was only supported in setups that do not use HTTPS behind a proxy (MAGNOLIA-8112).
If that is your case, delete the following line from your Tomcat configuration to make sure that CookieProcessor
is not defined:
<CookieProcessor sameSiteCookies="…" />
This approach is less optimal in that there is risk that the effective policy is decided by more recent versions of the browsers themselves, which may lead to unexpected issues.