Einführung
Dokumentation für Administratoren

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

Servlet-Engine Tomcat

Inhaltsverzeichnis

• server.xml

• web.xml

• tomcat-users.xml

• context.xml

• log4j.properties

• log4j2.xml

• logging.properties

• setenv.sh

• Starten / Stoppen

In folgender Konfiguration kann ein Apache Tomcat entweder auf demselben oder einem anderen Host als dem FirstSpirit-Server betrieben werden. Um eine bessere Lastverteilung bezüglich der Ressourcen CPU und RAM zu ermöglichen, bietet sich ein Betrieb auf einem anderen Host an.
Zur Lastverteilung auf mehreren Hosts siehe Seite Lastverteilung auf mehrere Servlet-Engines.

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. Ist Tomcat nicht über denselben Hostname und Port erreichbar wie der FirstSpirit Server, muss in der Datei firstspirit5/conf/fs-server.conf definiert werden, über welche URL der Tomcat aus Sicht der Clients später erreichbar sein soll, um beim Versand von Nachrichten außerhalb von aktiven Client-Verbindungen eine gültige URL zu generieren:

# URL-Parameter for workflow mail
URL=http://fs5server.domain.net:8080
fs.url.hostname=fs5server.domain.net
fs.url.httpport=8080

Falls https verwendet wird oder statt des http-Verbindungsmodus des FirstSpirit-Clients der Socket-Modus angewendet werden soll, siehe erweiterte Parameter zu fs.url unter Server-Konfiguration.

Die Installation von Tomcat (verwendet wird „Binary Distribution Core“ von http://tomcat.apache.org) erfolgt in diesem Beispiel nach /opt/tomcat.

server.xml

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 über die URL http://fs5.yourdomain.net:8080/manager/text als Benutzer „Admin“ verwenden zu können und das Deployment der WebApps automatisiert über FirstSpirit durchzuführen, in der Datei tomcat/conf/tomcat-users.xml ein Benutzerkonto für jede der Rollen „manager-gui“ und „manager-script“ 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>

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>

Außerdem 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. Die erhöhten Startzeiten können durch Konfigurationsanpassungen des JarScanFilters reduziert werden. 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-isolated-webrt.jar" 
     tldSkip="${tomcat.util.scan.StandardJarScanFilter.jarsToSkip},fs-isolated-webrt.jar" />   
 </JarScanner>

log4j.properties

Wichtig Ab FirstSpirit 2022.5 ist log4j2.xml zu benutzen.

Verfügbar bis FirstSpirit-Version 2022.4 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.

log4j2.xml

Wichtig Ab FirstSpirit 2024.3 ist die Tomcat-eigene Logging-Konfiguration zu nutzen.

Verfügbar bis FirstSpirit-Version 2024.2 Die Datei tomcat/lib/log4j2.xml mit folgendem Inhalt erstellen, um das Logging der FirstSpirit-Webanwendungen in eine eigene Datei umzuleiten:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="INFO">
   <Properties>
      <Property name="logdir">${sys:catalina.base}/logs</Property>
   </Properties>
   <Appenders>
      <RollingFile name="fs" 
         fileName="${logdir}/firstspirit.log"
         filePattern="${logdir}/firstspirit.log.%i.gz">
         <PatternLayout>
            <Pattern>[%d] %t %c %-5p - %m%n</Pattern>
         </PatternLayout>
         <Policies>
            <SizeBasedTriggeringPolicy size="1 MB"/>
         </Policies>
         <DefaultRolloverStrategy max="9"/>
      </RollingFile>
   </Appenders>
   <Loggers>
   <!-- change INFO in the following line to DEBUG for detailed FirstSpirit logging: --> 
      <Logger name="de.espirit" level="info" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Logger name="org.eclipse.jetty" level="warn" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Logger name="org.apache.catalina" level="info" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Logger name="org.apache.jasper" level="warn" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Logger name="org.apache.commons.httpclient" level="info" additivity="false">
          <AppenderRef ref="fs"/>
      </Logger>
      <Root level="info">
         <AppenderRef ref="fs"/>
     </Root>
   </Loggers>
</Configuration>
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.

logging.properties

Verfügbar ab FirstSpirit-Version 2024.3 Die Datei tomcat/conf/logging.properties mit folgendem Inhalt erstellen, um das Logging der FirstSpirit-Klassen und der Servlets einzelner Web-Anwendungen in eine eigene Datei umzuleiten:

handlers = 1catalina.org.apache.juli.AsyncFileHandler, 2localhost.org.apache.juli.AsyncFileHandler, 3manager.org.apache.juli.AsyncFileHandler, 4host-manager.org.apache.juli.AsyncFileHandler, 5firstspirit.org.apache.juli.AsyncFileHandler, java.util.logging.ConsoleHandler

.handlers = 1catalina.org.apache.juli.AsyncFileHandler, java.util.logging.ConsoleHandler

[...]

5firstspirit.org.apache.juli.AsyncFileHandler.level = FINE
5firstspirit.org.apache.juli.AsyncFileHandler.directory = ${catalina.base}/logs
5firstspirit.org.apache.juli.AsyncFileHandler.prefix = firstspirit.
5firstspirit.org.apache.juli.AsyncFileHandler.maxDays = 90
5firstspirit.org.apache.juli.AsyncFileHandler.encoding = UTF-8

[...]

org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/fs5preview].level = INFO
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/fs5preview].handlers = 5firstspirit.org.apache.juli.AsyncFileHandler

[...]

de.espirit.level = FINE
de.espirit.handlers = 5firstspirit.org.apache.juli.AsyncFileHandler

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.

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) müssen entsprechend des verfügbaren RAMs angepasst werden.

Wichtig Die nachfolgende Konfiguration dient als Beispiel. JVM-Parameter sind abhängig vom eingesetzten JDK, Tomcat-Parameter von der jeweiligen Tomcat-Version. Die Vielzahl an möglichen Konfigurationen dieser Fremdkomponenten kann hier nur begrenzt abgebildet werden.
Crownpeak empfiehlt, die Konfiguration in Abhängigkeit von den Anforderungen und Bedürfnissen von produktiven Kunden-Installationen zu optimieren. Dazu sollte Beratung durch Java-Experten, betreuende Partner-Unternehmen oder Crownpeak Technology GmbH selbst in Anspruch genommen werden. Allgemeingültige Empfehlungen können nicht gegeben werden. 

Beispiel (Konfiguration setenv.sh):

# use same umask as given in /opt/firstspirit5/conf/fs-wrapper.isolated.conf
# with parameter wrapper.umask
umask 0027

# use same JVM path as given in /opt/firstspirit5/conf/fs-wrapper.isolated.conf
# with parameter wrapper.java.command
JAVA_HOME="$FS_JAVA_HOME"

# Tomcat Heapsize settings
# set Xmx and Xms to max of 75% of available RAM, max 10000M
# Change jmxremote port to any free availble port
# and consider activiated jmx password security.
CATALINA_OPTS="$CATALINA_OPTS -Xmx4000M"
CATALINA_OPTS="$CATALINA_OPTS -Xms4000M"
CATALINA_OPTS="$CATALINA_OPTS -XX:InitialCodeCacheSize=128M"
CATALINA_OPTS="$CATALINA_OPTS -XX:ReservedCodeCacheSize=128M"
CATALINA_OPTS="$CATALINA_OPTS --add-exports=java.base/sun.security.util=ALL-UNNAMED"
CATALINA_OPTS="$CATALINA_OPTS --add-exports=java.desktop/sun.awt.image=ALL-UNNAMED"
CATALINA_OPTS="$CATALINA_OPTS --illegal-access=permit"
CATALINA_OPTS="$CATALINA_OPTS -XX:+UseCompressedOops"
CATALINA_OPTS="$CATALINA_OPTS -Djava.awt.headless=true"
CATALINA_OPTS="$CATALINA_OPTS -Dfile.encoding=UTF-8"
CATALINA_OPTS="$CATALINA_OPTS -Xshare:off"
CATALINA_OPTS="$CATALINA_OPTS -Djava.net.preferIPv4Stack=true"
CATALINA_OPTS="$CATALINA_OPTS -Djava.io.tmpdir=work"
CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote"
CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false"
CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"
CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.port=8006"
CATALINA_OPTS="$CATALINA_OPTS -Xlog:gc*,gc+age=trace,safepoint,heap*,phases*:/opt/tomcat/logs/tomcat-gc.log"
CATALINA_OPTS="$CATALINA_OPTS -Djava.security.auth.login.config=/opt/firstspirit5/conf/fs-jaas.conf"
CATALINA_OPTS="$CATALINA_OPTS -Djava.security.policy=/opt/firstspirit5/conf/fs-server.policy"

CATALINA_PID="/opt/tomcat/work/catalina.pid"

# JPDA configuration
JPDA_OPTS="-agentlib:jdwp=transport=dt_socket,address=127.0.0.1:8002,server=y,suspend=n"
# permanent debugging
#CATALINA_OPTS="$CATALINA_OPTS $JPDA_OPTS"
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.
Wichtig Für den Webserver Apache Tomcat sollten beim Betrieb mit Java 17 (oder neuer) dieselben --add-opens-Parameter verwendet werden, die für FirstSpirit in der firstspirit5/conf/fs-wrapper-vendor.conf Datei hinterlegt sind.
Beim Einsatz kundenspezischer Module kann es notwendig sein, weitere --add-opens-Parameter zu definieren.
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 firstspirit5/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 zu starten, die Datei /etc/init.d/tomcat mit folgendem Inhalt erstellen, Dateizugriffsrechte über chmod a+rx /etc/init.d/tomcat definieren und je nach Betriebssystem über insserv, update-rc.d oder chkconfig der Systemstartumgebung hinzufügen:

#!/usr/bin/bash

### BEGIN INIT INFO
# Provides: tomcat
# Required-Start: $local_fs $network
# Should-Start: $netdaemons $named $syslog $remote_fs sendmail
# Required-Stop: $local_fs $network
# Should-Stop: $netdaemons $named $syslog $remote_fs sendmail
# Default-Start: 2 3 5
# Default-Stop: 0 1 6
# Short-Description: FirstSpirit-Tomcat
# Description: FirstSpirit-Tomcat
# chkconfig: 235 95 05
### END INIT INFO

TCUSER=tomcat
TCDIR=/opt/tomcat

case "$1" in

start)
  su - $TCUSER -c "$TCDIR/bin/catalina.sh start" \
  && touch /var/lock/subsys/tomcat_$TCUSER
  ;;

stop)
  su - $TCUSER -c "$TCDIR/bin/catalina.sh stop -force" \
  && rm /var/lock/subsys/tomcat_$TCUSER
  ;;

restart)
  $0 stop
  $0 start
  ;;

*)
  echo "Usage: $0 { start | stop | restart }"
  exit 1
  ;;
esac

Im FirstSpirit ServerManager unter Server-Eigenschaften muss nun ein Webserver des Typs „Tomcat“ angelegt werden, beispielsweise mit dem Namen „PreviewTomcat“ (siehe Hinzufügen eines Tomcat-Webservers ).

Parameter:

  • Webserver-URL: In dieses Feld muss die Basis-URL des Tomcat eingetragen werden, z. B. http://tomcat:8080. Diese URL wird beispielsweise benötigt, um die Verweise für die FirstSpirit-Webanwendungen auf der Startseite anzupassen.
  • Webverzeichnis: leer lassen
  • Tomcat-Benutzer: siehe „username“ bei der Rolle „manager-script“ in der Datei tomcat/conf/tomcat-users.xml
  • Tomcat-Passwort: das dem zuvor eingetragenen Benutzer gehörende Passwort, siehe in der Datei tomcat/conf/tomcat-users.xml
  • Tomcat-Manager-URLs:
    http://tomcathost:8080/manager/text
    (lokaler Hostname des Tomcat-Servers, wie er vom FirstSpirit-Server aus erreichbar ist, sowie Tomcat-HTTP-Port. Werden mehrere Tomcat-Instanzen eingesetzt, werden die URLs kommasepariert eingegeben.)

In den Server-Eigenschaften müssen für die FirstSpirit-Web-Applikationen der „PreviewTomcat“ ausgewählt und die jeweiligen Webanwendungen über die Schaltfläche „Installieren“ auf dem Tomcat-Server installiert werden. Diese Installation erfolgt über das zuvor eingetragene Skript automatisch. Der FirstSpirit-Server erkennt, wenn die Web-Applikationen auf dem Tomcat nicht aktuell sind und sorgt dann für eine Aktualisierung.

Falls projektlokale Web-Applikationen verwendet werden, müssen diese ebenso auf „PreviewTomcat“ installiert werden.

Nach der Konfiguration und Installation des externen Webservers (hier Tomcat) liegt zwar die Webanwendung auf dem externen Webserver, nicht aber die generierten FirstSpirit-Inhalte. Falls der Staging-Bereich des FirstSpirit-Redaktionssystems im Projekt verwendet wird, um Redakteuren die generierte Website zur Ansicht über einen Webbrowser unter der URL http://fshostname.domain/fs5staging bereitzustellen, bevor sie mittels Deployment auf einen Live-Webserver übertragen wird, sind weitere, projektspezifische Anpassungen notwendig. Zunächst muss sichergestellt werden, dass der externe Webserver Zugriff auf die von FirstSpirit generierten Inhalte erhält. Eine Möglichkeit ist, die generierten Inhalte auf das Fremdsystem zu übertragen (A), z. B. via CRC-Tansfer oder rsync. Eine weitere Möglichkeit ist, den direkten Zugriff aus dem Fremdsystem auf die Generierungsverzeichnisse des FirstSpirit-Servers zu konfigurieren (B), z. B. via nfs-mount. Diese Lösungen müssen projektspezifisch konfiguriert werden.

Druckversion | Seitenanfang

© 2005 - 2024 Crownpeak Technology GmbH | Alle Rechte vorbehalten. | FirstSpirit 2024.13 | Datenschutz