Einführung
Einführung

Einführung / Konfiguration des FirstSpirit-Servers / Einbinden in externen Webserver / Servlet-Engine Tomcat

Servlet-Engine Tomcat

Inhaltsverzeichnis

Der in FirstSpirit integrierte Webserver Jetty bietet als Standards Servlet API 3.1 und JSP API 2.3.1 und ist nicht vollständig kompatibel zu AJP. Falls in FirstSpirit-Projekten Webanwendungen den vollständigen J2EE-Standard benötigen oder AJP zur Anbindung eines HTTP-Servers oder Loadbalancers, bietet es sich an, Apache Tomcat zu verwenden, dessen Konfiguration für FirstSpirit auf dieser Seite beschrieben wird.

Tomcat kann

Tomcat wird in dieser Konfiguration auf demselben Host wie der FirstSpirit-Server betrieben und benötigt lesenden und schreibenden Zugriff auf das Verzeichnis firstspirit5/web. Weil gleichzeitig der Prozess des FirstSpirit-Server Lese- und Schreibzugriff auf demselben Ordner benötigt, muss Tomcat unter demselben Benutzerkonto betrieben werden, wie der FirstSpirit-Server, also in der Standardinstallation unter Benutzerkonto „fs5“.

Falls aus Sicherheitsgründen unbedingt Tomcat unter einem anderen Benutzerkonto betrieben werden muss, sollte die unter Servlet-Engine Tomcat auf dediziertem Host beschriebene Variante verwendet werden, die auch auf demselben Host einsetzbar ist.

Tomcat kann entweder eigenständig mit dem in Tomcat integrierten HTTP-Server betrieben werden oder zusätzlich um den Apache HTTP-Server ergänzt werden, wie unter Apache HTTP-Server mit Servlet-Engine Tomcat beschrieben.

Bevor Tomcat konfiguriert wird, ist die FirstSpirit-Konfiguration zu ändern. In der Datei firstspirit5/conf/fs-server.conf müssen folgende Parameter definiert werden, um Jetty zu deaktivieren und die Standard-Webanwendung zu definieren, die beim Aufruf der FirstSpirit-Startseite über Tomcat, beispielsweise http://fs5.yourdomain.net:8080, verwendet wird:

INTERNAL_SERVLET_ENGINE=0
WEBAPP_ROOT_PATH=${WEB_DIR}/ROOT

Anschließend den FirstSpirit-Server herunterfahren, das Verzeichnis firstspirit5/web/fs5root entfernen und den FirstSpirit-Server wieder starten.

Die Installation von Tomcat (verwendet wird „Binary Distribution Core“ von http://tomcat.apache.org) erfolgt in diesem Beispiel nach /opt/tomcat. Falls die Installation in ein anderes Verzeichnis erfolgt, muss im nachfolgenden Konfigurationsbeispiel an allen Stellen die relative Pfadangabe „${catalina.home}/../“ durch die absolute Angabe /opt/tomcat/ ersetzt werden.

server.xml

In tomcat/conf/server.xml den Abschnitt <Host> wie folgt ändern (xmlValidation="false" und xmlNamespaceAware="false" ergänzen):

<Host name="localhost" appBase="webapps" unpackWARs="true" 
autoDeploy="true" xmlValidation="false" xmlNamespaceAware="false">

In tomcat/conf/server.xml die Kodierung für URI-Parameter auf UTF-8 einstellen, dazu bei den bereits vorhandenen HTTP- und AJP-Konnektoren den Parameter URIEncoding hinzufügen:

<Connector port="8080" protocol="HTTP/1.1" URIEncoding="UTF-8" />
<Connector port="8009" protocol="AJP/1.3" URIEncoding="UTF-8" />

web.xml

In der Datei tomcat/conf/web.xml das Überprüfen und Kompilieren der JSP-Dateien bei jeder Änderung ohne Verzögerung aktivieren. Dazu die folgenden bereits vorhandenen Zeilen der Datei

<servlet>
<servlet-name>jsp</servlet-name>
<servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
<init-param>
<param-name>fork</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>xpoweredBy</param-name>
<param-value>false</param-value>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>

durch folgende Zeilen ersetzen:

<servlet>
<servlet-name>jsp</servlet-name>
<servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
<init-param>
<param-name>fork</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>xpoweredBy</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>development</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>modificationTestInterval</param-name>
<param-value>0</param-value>
</init-param>
<load-on-startup>3</load-on-startup>
</servlet>

Falls die Möglichkeit des Auflistens der Verzeichnisinhalte zur Entwicklung von Webanwendungen im Staging-Bereich des FirstSpirit-Servers benötigt wird, in derselben Datei die Zeilen

<servlet>
<servlet-name>default</servlet-name>
<servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>listings</param-name>
<param-value>false</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>

durch folgende Zeilen ersetzen:

<servlet>
<servlet-name>default</servlet-name>
<servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>listings</param-name>
<param-value>true</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>

tomcat-users.xml

Um den Tomcat-Manager zur Status-Überwachung zu aktivieren, in der Datei tomcat/conf/tomcat-users.xml ein Benutzerkonto für die Rolle „manager“ des Tomcat-Managers einfügen:

<?xml version='1.0' encoding='utf-8'?> 
<tomcat-users>
<role rolename="manager-gui"/>
<role rolename="manager-script"/>
<user username="Admin" password="tomcat-password" roles="manager-gui"/>
<user username="fsdeploy" password="deploy-password" roles="manager-script"/>
</tomcat-users>

manager.xml

Die Datei tomcat/conf/Catalina/localhost/manager.xml mit folgendem Inhalt zum Aktivieren des Tomcat-Managers anlegen:

<Context docBase="${catalina.home}/webapps/manager"
privileged="true" antiResourceLocking="false"
antiJARLocking="false">

<ResourceLink name="users" global="UserDatabase"
type="org.apache.catalina.UserDatabase"/>
</Context>

context.xml

Die vorhandene Datei tomcat/conf/context.xml durch folgenden Inhalt ersetzen, um das sofortige Prüfen auf Dateiänderungen (HTML) zu aktivieren. Über den bei „firstspirit.host“ angegebenen Hostnamen oder die IP-Adresse muss von Tomcat aus der FirstSpirit-Server im lokalen Netz erreichbar sein. Die Angabe bei „firstspirit.port“ muss mit dem Port des FirstSpirit-Servers, wie in firstspirit5/conf/fs-server.conf über Parameter SOCKET_PORT definiert, übereinstimmen. Zusätzlich wird das Speichern persistenter Session-Informationen deaktiviert, weil die FirstSpirit-Webanwendungen dies nicht unterstützen:

<?xml version='1.0' encoding='utf-8'?>
<Context useHttpOnly="true">

<WatchedResource>WEB-INF/web.xml</WatchedResource>
<WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>

<!-- disable session persistence across Tomcat restarts --> <Manager pathname="" />

<Resources cachingAllowed="false" />

<Parameter name="firstspirit.host" value="fs5server" override="false" />
<Parameter name="firstspirit.port" value="1088" override="false" />

</Context>

Darüber hinaus ist folgende Änderung in tomcat/conf/context.xml notwendig. Hintergrund: Tomcat durchsucht beim Start des Application-Servers standardmäßig alle Jar-Dateien der WebApps (fs5root, fs5webedit, ...) auf bestimmte Klassen und TLDs. Dies führt zu erhöhten Startzeiten, die durch Konfigurationsanpassungen des JarScanFilters reduziert werden können. Zusätzlich kann das parallele Starten von WebApps konfiguriert werden, um eine weitere Verbesserung der Startzeiten zu erreichen:

  <JarScanner>   
<JarScanFilter pluggabilitySkip="${tomcat.util.scan.StandardJarScanFilter.jarsToSkip},
fs-webrt.jar"
tldSkip="${tomcat.util.scan.StandardJarScanFilter.jarsToSkip},fs-webrt.jar" />
</JarScanner>

catalina.properties

In tomcat/conf/catalina.properties den Eintrag zu „common.loader“ um fs-webrt.jar und shared/lib der FirstSpirit-Installation erweitern (alles ohne Leerzeichen in eine Zeile schreiben):

common.loader=${catalina.home}/lib,${catalina.home}/lib/*.jar, 
${catalina.home}/../firstspirit5/data/fslib/fs-webrt.jar,
${catalina.home}/../firstspirit5/shared/lib/*.jar

Soll statt ${catalina.home} unter Windows ein anderer Pfad verwendet werden, muss folgende kleingeschriebene Schreibweise der Laufwerksbuchstaben verwendet werden (alles ohne Leerzeichen in eine Zeile schreiben):

common.loader=${catalina.home}/lib,${catalina.home}/lib/*.jar,
d:/Programme/FirstSpirit5/data/fslib/fs-webrt.jar,
d:/Programme/FirstSpirit5/shared/lib/*.jar

log4j.properties

Die Datei tomcat/lib/log4j.properties mit folgendem Inhalt erstellen, um das Logging der FirstSpirit-Webanwendungen in eine eigene Datei umzuleiten:

log4j.rootCategory=INFO, fs

# change INFO in the following line to DEBUG
# for detailed FirstSpirit logging:
log4j.logger.de.espirit=INFO

log4j.logger.org.eclipse.jetty=WARN
log4j.logger.org.apache.catalina=INFO
log4j.logger.org.apache.jasper=WARN
log4j.logger.org.apache.log4j.jmx=ERROR
log4j.logger.org.apache.commons.httpclient=INFO

log4j.appender.fs=org.apache.log4j.RollingFileAppender
log4j.appender.fs.File=${catalina.home}/logs/firstspirit.log
log4j.appender.fs.MaxFileSize=10MB
log4j.appender.fs.MaxBackupIndex=9
log4j.appender.fs.layout=org.apache.log4j.PatternLayout
log4j.appender.fs.layout.ConversionPattern=[%d] %t %c %-5p - %m%n
Wichtig Für alle Webanwendungen, für die kein Log4j zur Verfügung steht (z. B. Module ohne entsprechende Abhängigkeit), ist diese Konfiguration nicht nötig, da Tomcat keine Log4j-Implementierung beinhaltet.

Unabhängig von der gewählten Logging-Implementierung kann in der Datei tomcat/conf/catalina.properties der Wert für das Loglevel angepasst werden. Sollen umfangreichere Logausgaben erfolgen, kann das Loglevel z. B. auf sysout.loglevel=INFO gesetzt werden.

Wichtig Bei der Verwendung von Tomcat statt Jetty wird an allen Stellen im ServerManager (in den Server-Eigenschaften vgl. Webserver und Web-Applikationen, in den Projekt-Eigenschaften vgl. Web-Komponenten) sowie in der Datei fs-server.conf überall „InternalJetty“ als Bezeichner des Webservers angezeigt, da aus der Sicht des FirstSpirit-Servers der Tomcat-Server genau die gleichen Dateien an derselben Stelle verwendet wie der Jetty-Webserver.

setenv.sh

Für die von Tomcat verwendete Java-VM gelten die Anforderungen an die Konfiguration eines Application-Servers. Bei Tomcat erfolgt die Konfiguration über die Datei tomcat/bin/setenv.sh mit dem folgenden Inhalt, der den JVM-Parametern aus firstspirit5/conf/fs-wrapper.conf entspricht. Die Angaben für die Java-Heapsize (Xmx, Xms, Xmn) müssen entsprechend des verfügbaren RAMs angepasst werden.

#export JAVA_OPTS="-Xmx3072m"
#export LC_CTYPE=de_DE.UTF-8
#CATALINA_OPTS="-Djava.security.auth.login.config=/opt/firstspirit5/conf/fs-jaas.conf"

# use same JVM path as given in firstspirit5/conf/fs-wrapper.conf
# with parameter wrapper.java.command
JAVA_HOME==/opt/java/jdk-11.0.4
# Tomcat Heapsize settings
# set Xmx and Xms to max of 75% of available RAM, max 10000M
# set Xmn to 40% of Xmx
# Change jmxremote port to any free availble port
# and consider activiated jmx password security.
CATALINA_OPTS="\
-Xmx4096M -Xms4096m -Xmn1664m \
-XX:PermSize=500m -XX:MaxPermSize=500m \
-XX:InitialCodeCacheSize=128m \
-XX:ReservedCodeCacheSize=128m \
-XX:SurvivorRatio=1 \
-XX:SoftRefLRUPolicyMSPerMB=1 \
-XX:+NeverTenure \
-XX:-UseLargePages \
-XX:+UseParNewGC \
-XX:+UseConcMarkSweepGC \
-XX:+CMSParallelRemarkEnabled \
-XX:+CMSClassUnloadingEnabled \
\
-Djava.awt.headless=true \
-Dfile.encoding=UTF-8 \
-Djava.net.preferIPv4Stack=true \
-Djava.security.auth.login.config=/opt/firstspirit5/conf/fs-jaas.conf \
-Djava.security.policy=/opt/firstspirit5/conf/fs-server.policy \
-Xshare:off \
-Djava.net.preferIPv4Stack=true \
-Djava.io.tmpdir=work \
\
-Dcom.sun.management.jmxremote \
-Dcom.sun.management.jmxremote.ssl=false \
-Dcom.sun.management.jmxremote.authenticate=false \
-Dcom.sun.management.jmxremote.port=8006 \
\
-verbose:gc \
-XX:+PrintGCTimeStamps \
-XX:+PrintGCDateStamps \
-XX:+PrintGCDetails \
-Xloggc:/opt/tomcat/logs/tomcat-gc.log \
"

CATALINA_PID=/opt/tomcat/work/catalina.pid
Wichtig Die Parameter -XX:SurvivorRatio=1 und -XX:+NeverTenure sollten ab Java 9 nicht mehr verwendet werden, da sie negative Auswirkungen auf die Gesamtperformance des Systems haben.
Wichtig Der Parameter -Xmn sollten ab Java 9 nicht mehr verwendet werden, da er negative Auswirkungen auf die Garbage Collection G1 (Garbage-First) hat.

Zur Umstellung auf eine GarbargeCollector-Logdateirotation siehe Konfiguration der Java-VM von Oracle.

Wichtig Der Metaspace (ein weiterer, nativer Speicherbereich neben dem Heap) wird von der Java-VM automatisch verwaltet. Eine abweichende Konfiguration, z. B. über die Parameter MetaspaceSize bzw. MaxMetaspaceSize wird ausdrücklich nicht empfohlen.

Starten / Stoppen

In der Datei /opt/tomcat/bin/catalina.sh die Zeile

FORCE=0

in

FORCE=1

ändern, um Tomcat definiert beenden zu können, ohne dass ein Prozess „hängenbleibt“. Falls catalina.sh nicht geändert werden soll, ist bei jedem Herunterfahren der Parameter „-force“ hinzuzufügen, also „catalina.sh stop –force“.

Tomcat wird nun über folgende Zeile gestartet:

/opt/tomcat/bin/catalina.sh start

Zum Beenden:

/opt/tomcat/bin/catalina.sh stop

Um Tomcat automatisch beim Systemstart gleichzeitig mit FirstSpirit zu starten, in /etc/init.d/fs5 folgende Zeile im Bereich „start)“ hinzufügen

su - $FSUSER -c "$FSDIR/../../tomcat/bin/catalina.sh start"

und folgende Zeile im Bereich „stop)“:

su - $FSUSER -c "$FSDIR/../../tomcat/bin/catalina.sh stop"

Um einen reibungsfreien Start von Tomcat, FirstSpirit-Server und FirstSpirit-Webanwendungen zu gewährleisten, sollte darauf geachtet werden, dass der Start des Tomcat per Script (Zeile su - $FSUSER -c "$FSDIR/../../tomcat/bin/catalina.sh start") vor dem des FirstSpirit-Servers liegt. Siehe dazu auch Hinweis zur Startreihenfolge.

Weitere Konfiguration per FirstSpirit ServerManager

Nach erfolgter Konfiguration des Tomcat muss dieser FirstSpirit bekannt gemacht werden. Siehe dazu Seite Webserver.

© 2005 - 2020 e-Spirit AG | Alle Rechte vorbehalten. | FirstSpirit 2020-09 | Datenschutz | Impressum | Kontakt