Skip to content

Tomcat

It is advised to use 3 different tomcat instances: * one for the proxy and cas webapps * an other one dedicated to the geoserver webapp * the last one for the other webapps

Prerequisites

sudo apt install -y tomcat9 tomcat9-user

We will deactivate the default tomcat instance, just to be sure:

sudo service tomcat9 stop
sudo systemctl disable tomcat9

Keystore

To create a keystore containing a newly generated key, enter the following: 

sudo keytool -genkey \
    -alias georchestra_localhost \
    -keystore /etc/tomcat9/keystore \
    -storepass STOREPASSWORD \
    -keypass STOREPASSWORD \
    -keyalg RSA \
    -keysize 2048 \
    -dname "CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=FR"
... where STOREPASSWORD is a password you choose, and the dname string is customized.

CA certificates

If the geOrchestra webapps have to communicate with remote HTTPS services, our keystore/trustore has to include the remote CA certificates.

This will be the case, when e.g.:

  • the proxy has to relay an https service
  • geonetwork will harvest remote https nodes
  • geoserver will proxy remote https ogc services

In order to trust the default system certificates from the cacerts package into our previously created keystore:

sudo keytool -importkeystore \
    -srckeystore /etc/ssl/certs/java/cacerts \
    -destkeystore /etc/tomcat9/keystore

The password of the srckeystore is "changeit" by default.

SSL

To import the certificate used by Apache2 into our keystore, we shall issue the following command: 

keytool -import -alias cert_ssl -file /var/www/georchestra/ssl/georchestra.crt -keystore /etc/tomcat9/keystore

If you have a Let's Encrypt certificate using Certbot the file to import is : /etc/letsencrypt/live/[your_sdi_domain_name]/cert.pem. But since the LetsEncrypt root certificates were already trusted previously, it should not be necessary to do so.

LDAP SSL

In case the LDAP connection uses SSL (which is not the default in the geOrchestra template configuration), its certificate must be added to the keystore.

Here's how:

First get the public key. 

echo "" | openssl s_client -connect LDAPHOST:LDAPPORT -showcerts 2>/dev/null | openssl x509 -out /tmp/certfile.txt
... and then add it to the keystore: 
sudo keytool -import -alias cert_ldap -file /tmp/certfile.txt -keystore /etc/tomcat9/keystore

Finally,

verify the list of keys in keystore: 

keytool -keystore /etc/tomcat9/keystore -list

geOrchestra datadir

geOrchestra gets its configuration settings from specific directory, the "georchestra datadir", which is is usually located in /etc/georchestra.

To bootstrap a default datadir: 

sudo git clone -b BRANCH_NAME https://github.com/georchestra/datadir.git /etc/georchestra
... where BRANCH_NAME matches the geOrchestra release name (or master for development purposes)

Tomcat proxycas

Create the instance

We will now create an instance named tomcat9-proxycas:

sudo tomcat9-instance-create -p 8180 -c 8105 /var/lib/tomcat9-proxycas

As indicated in the parameters from the previous command-line, 8180 will be the HTTP port and 8105 the stop port.

Then: 

sudo cp -r /usr/share/tomcat9 /usr/share/tomcat9-proxycas
sudo mkdir /var/lib/tomcat9-proxycas/conf/policy.d
sudo touch /var/lib/tomcat9-proxycas/conf/policy.d/empty.policy
sudo rm -rf /var/lib/tomcat9-proxycas/logs
sudo ln -s /var/log/tomcat9 /var/lib/tomcat9-proxycas/logs
sudo mkdir -p /var/lib/tomcat9-proxycas/conf/Catalina/localhost
sudo chown -R tomcat:tomcat /var/lib/tomcat9-proxycas
sudo cp /lib/systemd/system/tomcat9.service /lib/systemd/system/tomcat9-proxycas.service
sudo cp /usr/libexec/tomcat9/tomcat-start.sh /usr/libexec/tomcat9/tomcat-proxycas-start.sh
sudo cp /etc/default/tomcat9 /etc/default/tomcat9-proxycas

Finally, edit the /lib/systemd/system/tomcat9-proxycas script and adapt to the created instance:

--- tomcat9.service 2019-06-13 21:26:12.000000000 +0000
+++ tomcat9-proxycas.service    2020-01-20 13:19:10.728000000 +0000
@@ -11,14 +11,14 @@

 # Configuration
 Environment="CATALINA_HOME=/usr/share/tomcat9"
-Environment="CATALINA_BASE=/var/lib/tomcat9"
+Environment="CATALINA_BASE=/var/lib/tomcat9-proxycas"
 Environment="CATALINA_TMPDIR=/tmp"
 Environment="JAVA_OPTS=-Djava.awt.headless=true"

 # Lifecycle
 Type=simple
 ExecStartPre=+/usr/libexec/tomcat9/tomcat-update-policy.sh
-ExecStart=/bin/sh /usr/libexec/tomcat9/tomcat-start.sh
+ExecStart=/bin/sh /usr/libexec/tomcat9/tomcat-proxycas-start.sh
 SuccessExitStatus=143
 Restart=on-abort

@@ -35,7 +35,7 @@
 CacheDirectoryMode=750
 ProtectSystem=strict
 ReadWritePaths=/etc/tomcat9/Catalina/
-ReadWritePaths=/var/lib/tomcat9/webapps/
+ReadWritePaths=/var/lib/tomcat9-proxycas/
 ReadWritePaths=/var/log/tomcat9/
 RequiresMountsFor=/var/log/tomcat9

And reload the systemd configuration:

sudo systemctl daemon-reload

Customize the Java runtime and options

In /etc/default/tomcat9-proxycas, we will adapt the JAVA_HOME & JAVA_OPTS environment variables to suit our needs:

JAVA_HOME=/usr/lib/jvm/adoptopenjdk-11-hotspot-amd64

And later add these lines (change the STOREPASSWORD string): 

JAVA_OPTS="$JAVA_OPTS \
              -Dgeorchestra.datadir=/etc/georchestra"

JAVA_OPTS="$JAVA_OPTS \
              -Xms1G \
              -Xmx1G"

JAVA_OPTS="$JAVA_OPTS \
              -Djavax.net.ssl.trustStore=/etc/tomcat9/keystore \
              -Djavax.net.ssl.trustStorePassword=STOREPASSWORD"

If your connection needs to pass through a proxy, you should also add the relevant options, as follows:

JAVA_OPTS="$JAVA_OPTS \
              -Dhttp.proxyHost=proxy.mycompany.com \
              -Dhttp.proxyPort=XXXX \
              -Dhttps.proxyHost=proxy.mycompany.com \
              -Dhttps.proxyPort=XXXX"

Finally, make sure the variables are exported at the end of the script:

export JAVA_HOME
export JAVA_OPTS

Configure connectors

In /var/lib/tomcat-proxycas/conf/server.xml, find the place where the HTTP connector is defined, and check that the port is correctly set: 

    <Connector port="8180" protocol="HTTP/1.1"
               connectionTimeout="20000"
               URIEncoding="UTF-8"
               redirectPort="8443"
                />

... which should have been done by the tomcat9-instance-create script.

Start the instance

Finally, we make the instance start by default with the OS:

systemctl enable tomcat9-proxycas

and check if we can now start it:

service tomcat9-proxycas start

In case of issues, one can consult the logs using the following command:

journalctl -xe

Tomcat geOrchestra

Create the instance

The same procedure as before is followed, we will only adapt names and ports. 

sudo tomcat9-instance-create -p 8280 -c 8205 /var/lib/tomcat9-georchestra
sudo cp -r /usr/share/tomcat9 /usr/share/tomcat9-georchestra
sudo mkdir /var/lib/tomcat9-georchestra/conf/policy.d
sudo touch /var/lib/tomcat9-georchestra/conf/policy.d/empty.policy
sudo rm -rf /var/lib/tomcat9-georchestra/logs
sudo ln -s /var/log/tomcat9 /var/lib/tomcat9-georchestra/logs
sudo mkdir -p /var/lib/tomcat9-georchestra/conf/Catalina/localhost
sudo chown -R tomcat:tomcat /var/lib/tomcat9-georchestra
sudo cp /lib/systemd/system/tomcat9.service /lib/systemd/system/tomcat9-georchestra.service
sudo cp /usr/libexec/tomcat9/tomcat-start.sh /usr/libexec/tomcat9/tomcat-georchestra-start.sh
sudo cp /etc/default/tomcat9 /etc/default/tomcat9-georchestra

Adapt the script in libexec, so that it will source the expected file in /etc/default:

# Load the service settings
. /etc/default/tomcat9-georchestra

Finally, we need to adapt the systemd unit file for this instance:

--- tomcat9.service 2019-06-13 21:26:12.000000000 +0000
+++ tomcat9-georchestra.service 2020-01-20 13:34:21.760000000 +0000
@@ -11,14 +11,14 @@

 # Configuration
 Environment="CATALINA_HOME=/usr/share/tomcat9"
-Environment="CATALINA_BASE=/var/lib/tomcat9"
+Environment="CATALINA_BASE=/var/lib/tomcat9-georchestra"
 Environment="CATALINA_TMPDIR=/tmp"
 Environment="JAVA_OPTS=-Djava.awt.headless=true"

 # Lifecycle
 Type=simple
 ExecStartPre=+/usr/libexec/tomcat9/tomcat-update-policy.sh
-ExecStart=/bin/sh /usr/libexec/tomcat9/tomcat-start.sh
+ExecStart=/bin/sh /usr/libexec/tomcat9/tomcat-georchestra-start.sh
 SuccessExitStatus=143
 Restart=on-abort

@@ -35,7 +35,7 @@
 CacheDirectoryMode=750
 ProtectSystem=strict
 ReadWritePaths=/etc/tomcat9/Catalina/
-ReadWritePaths=/var/lib/tomcat9/webapps/
+ReadWritePaths=/var/lib/tomcat9-georchestra/
+ReadWritePaths=/opt/geonetwork_data_dir/
+ReadWritePaths=/opt/extracts/
 ReadWritePaths=/var/log/tomcat9/
 RequiresMountsFor=/var/log/tomcat9

Note: the ReadWritePaths parameters above should be set in the tomcat unit files accordingly. Here we assumed that GeoNetwork (which requires RW access to /opt/geonetwork_data_dir) will be deployed in this instance.

Reload the systemd configuration:

sudo systemctl daemon-reload
sudo systemctl enable tomcat9-georchestra

Customize Java runtime & options

In /etc/default/tomcat9-georchestra, we need to adapt the JAVA_HOME & JAVA_OPTS variables as well: 

JAVA_HOME=/usr/lib/jvm/adoptopenjdk-11-hotspot-amd64

And later add these lines (change the STOREPASSWORD string): 

JAVA_OPTS="$JAVA_OPTS \
              -Dgeorchestra.datadir=/etc/georchestra"

JAVA_OPTS="$JAVA_OPTS \
              -Xms6G \
              -Xmx6G"

JAVA_OPTS="$JAVA_OPTS \
              -Djavax.net.ssl.trustStore=/etc/tomcat9/keystore \
              -Djavax.net.ssl.trustStorePassword=STOREPASSWORD"

JAVA_OPTS="$JAVA_OPTS \
              -Djava.util.prefs.userRoot=/tmp \
              -Djava.util.prefs.systemRoot=/tmp"
This allocates 6GB of your server RAM to all geOrchestra webapps (except proxy, cas and geoserver, which are located in other tomcat instances).

GeoNetwork 3.x (geOrchestra 15.12 and above)

If GeoNetwork 3.x is deployed, some extra java environment variables will be required, because almost everything related to the configuration and the geOrchestra integration has been exported outside of the webapp, into the geOrchestra datadir.

GeoNetwork also comes with its own "datadir", to store specific materials related to its own operation (to store uploaded content for example). One can create the directory using the following commands:

sudo mkdir /opt/geonetwork_data_dir
sudo chown -R tomcat /opt/geonetwork_data_dir

Customize the /etc/georchestra/geonetwork/geonetwork.properties, so that the geonetwork.dir reflects the path created during the previous step, e.g. /opt/geonetwork_data_dir.

Then ensure your tomcat has the following environment variable set:

JAVA_OPTS="$JAVA_OPTS \
              -Dgeonetwork.jeeves.configuration.overrides.file=/etc/georchestra/geonetwork/config/config-overrides-georchestra.xml"

Note: You can also override every geonetwork sub-data-directories by modifying the /etc/georchestra/geonetwork/geonetwork.properties file for convenience.

Configure connector

Normally, the tomcat9-instance-create should have correctly set the listening port accordingly ; but we want to check the connector parameters:

In /var/lib/tomcat9-georchestra/conf/server.xml:

    <Connector port="8280" protocol="HTTP/1.1"
               connectionTimeout="20000"
               URIEncoding="UTF-8"
               scheme="https"
               proxyName="georchestra.mydomain.org"
               proxyPort="443"
               redirectPort="8443" />
Set proxyName to your service's fqdn.

Start the instance

sudo service tomcat9-georchestra start

Tomcat GeoServer

Create the instance

sudo tomcat9-instance-create -p 8380 -c 8305 /var/lib/tomcat9-geoserver0
sudo cp -r /usr/share/tomcat9 /usr/share/tomcat9-geoserver0
sudo mkdir /var/lib/tomcat9-geoserver0/conf/policy.d
sudo touch /var/lib/tomcat9-geoserver0/conf/policy.d/empty.policy
sudo rm -rf /var/lib/tomcat9-geoserver0/logs
sudo ln -s /var/log/tomcat9 /var/lib/tomcat9-geoserver0/logs
sudo mkdir -p /var/lib/tomcat9-geoserver0/conf/Catalina/localhost
sudo chown -R tomcat:tomcat /var/lib/tomcat9-geoserver0
sudo cp /lib/systemd/system/tomcat9.service /lib/systemd/system/tomcat9-geoserver0.service
sudo cp /usr/libexec/tomcat9/tomcat-start.sh /usr/libexec/tomcat9/tomcat-geoserver0-start.sh
sudo cp /etc/default/tomcat9 /etc/default/tomcat9-geoserver0

Adapt the /usr/libexec/tomcat9/tomcat-geoserver0-start.sh so that it sources the /etc/default/tomcat9-geoserver0 file instead:

# Load the service settings
. /etc/default/tomcat9-geoserver0

And adapt the previously created systemd unit file in /lib/systemd/system/tomcat9-geoserver0.service:

--- tomcat9.service 2019-06-13 21:26:12.000000000 +0000
+++ tomcat9-geoserver0.service  2020-01-20 13:46:12.968000000 +0000
@@ -11,14 +11,14 @@

 # Configuration
 Environment="CATALINA_HOME=/usr/share/tomcat9"
-Environment="CATALINA_BASE=/var/lib/tomcat9"
+Environment="CATALINA_BASE=/var/lib/tomcat9-geoserver0"
 Environment="CATALINA_TMPDIR=/tmp"
 Environment="JAVA_OPTS=-Djava.awt.headless=true"

 # Lifecycle
 Type=simple
 ExecStartPre=+/usr/libexec/tomcat9/tomcat-update-policy.sh
-ExecStart=/bin/sh /usr/libexec/tomcat9/tomcat-start.sh
+ExecStart=/bin/sh /usr/libexec/tomcat9/tomcat-geoserver0-start.sh
 SuccessExitStatus=143
 Restart=on-abort

@@ -35,7 +35,7 @@
 CacheDirectoryMode=750
 ProtectSystem=strict
 ReadWritePaths=/etc/tomcat9/Catalina/
-ReadWritePaths=/var/lib/tomcat9/webapps/
+ReadWritePaths=/var/lib/tomcat9-geoserver0/
+ReadWritePaths=/opt/geoserver_data_dir
+ReadWritePaths=/opt/geowebcache_cache_dir
 ReadWritePaths=/var/log/tomcat9/
 RequiresMountsFor=/var/log/tomcat9

Enable the instance:

sudo systemctl daemon-reload
sudo systemctl enable tomcat9-georchestra

Locate tomcat's conf/context.xml and update the <Context> tag in order to set useRelativeRedirects to false, eg:

<Context useRelativeRedirects="false">
    <WatchedResource>WEB-INF/web.xml</WatchedResource>
    <WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>
</Context>

See #1857 for the motivations behind setting this parameter.

Customize Java runtime & options

In /etc/default/tomcat9-geoserver0: 

JAVA_HOME=/usr/lib/jvm/adoptopenjdk-11-hotspot-amd64

And later add these lines: 

JAVA_OPTS="$JAVA_OPTS \
            -DGEOSERVER_DATA_DIR=/opt/geoserver_data_dir \
            -DGEOWEBCACHE_CACHE_DIR=/opt/geowebcache_cache_dir"

JAVA_OPTS="$JAVA_OPTS \
            -Dfile.encoding=UTF8 \
            -Djavax.servlet.request.encoding=UTF-8 \
            -Djavax.servlet.response.encoding=UTF-8"

JAVA_OPTS="$JAVA_OPTS \
            -Xms2G -Xmx2G"

JAVA_OPTS="$JAVA_OPTS \
            -server \
            -XX:+UseParNewGC \
            -XX:ParallelGCThreads=2 \
            -XX:SoftRefLRUPolicyMSPerMB=36000 \
            -XX:+UseConcMarkSweepGC"
This allocates 2GB of your server RAM to GeoServer.

The /opt/geoserver_data_dir directory should be owned by tomcat, and created by checking out this repository georchestra/geoserver_minimal_datadir:

sudo git clone -b master https://github.com/georchestra/geoserver_minimal_datadir.git /opt/geoserver_data_dir
sudo chown -R tomcat /opt/geoserver_data_dir
sudo mkdir -p /opt/geowebcache_cache_dir
sudo chown -R tomcat /opt/geowebcache_cache_dir
Note that this data dir holds several branches: please refer to the repository README in order to choose the correct one.

As before (change the STOREPASSWORD string): 

JAVA_OPTS="$JAVA_OPTS \
              -Djavax.net.ssl.trustStore=/etc/tomcat9/keystore \
              -Djavax.net.ssl.trustStorePassword=STOREPASSWORD"

In case your connection to the internet needs to pass through a proxy, you should also add the -Dhttp.proxyHost=xxxx -Dhttp.proxyPort=xxxx options here.

Note for geofence users

If geofence is activated in our geoserver, one will require some specific environment variables set. in the /etc/default/tomcat9-geoserver0 file, consider adding:

JAVA_OPTS="$JAVA_OPTS \
           -Dgeofence-ovr=file:/etc/georchestra/geoserver/geofence/geofence-datasource-ovr.properties"

Note for geowebcache users

GeoWebCache can be used either as a standalone webapp or integrated to GeoServer. If we want to go for the first option, we will also require the following JAVA_OPTS options:

JAVA_OPTS="$JAVA_OPTS
           -DGEOWEBCACHE_CONFIG_DIR=/opt/geowebcache_datadir \
           -DGEOWEBCACHE_CACHE_DIR=/opt/geowebcache_tiles"

Exporting Java variables

Finally, do not forget to export the variables at the end of the script:

export JAVA_HOME
export JAVA_OPTS

Configure the connector

For GeoServer, it is advised to lower the number of simultaneous threads handling incoming requests. By default Tomcat assumes 200 threads, but experiments show that 20 is a better value.

It is also required to set the scheme, proxyPort & proxyName parameters, as follows in /var/lib/tomcat9-geoserver0/conf/server.xml: 

    <Connector port="8380" protocol="HTTP/1.1"
               connectionTimeout="20000"
               URIEncoding="UTF-8"
               maxThreads="20"
               minSpareThreads="20"
               scheme="https"
               proxyName="georchestra.mydomain.org"
               proxyPort="443"
               redirectPort="8443" />
... where proxyName is set to your service's fqdn.

Start the instance

sudo service tomcat9-geoserver0 start

In case of troubles with the GeoServer UI

While testing the following setup guide, we stumbled upon a strange behaviour of the geoserver UI. If you are encountering some strange response from GeoServer ("400 Bad Request"), it might be due to the following upstream issue.

As described in the issue, this can be solved by changing geoserver's web.xml file, and adding the following context variable:

<context-param>
  <param-name>GEOSERVER_CSRF_WHITELIST</param-name>
  <param-value>georchestra.mydomain.org</param-value>
</context-param>

As described in the official GeoServer documentation, you should also be able to use a JAVA_OPTS environment variable (eg -DGEOSERVER_CSRF_WHITELIST=georchestra.mydomain.org) instead of the previous modification.

Of course you will have to adapt the parameter to suit your setup. Setups based on the Jetty Servlet Container do not seem to be affected.