.. include:: /includes.rst.txt

.. comments - headings

   # with overline, for parts
   * with overline, for chapters
   = for sections
   - for subsections
   ^ for subsubsections
   " for paragraphs
   * for H5
   + for H6

.. _tomcat_configuration:

Configuring Tomcat for TopBraid EDG
-----------------------------------

To run TopBraid EDG, an instance of Apache Tomcat must be provisioned and appropriately configured.

Supported Tomcat versions
^^^^^^^^^^^^^^^^^^^^^^^^^

See :ref:`edg_server_platform_considerations`.

.. _catalina_opts:

Configuring ``CATALINA_OPTS``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. warning::
  This is required for EDG to work.

The ``CATALINA_OPTS`` environment variable must be set to pass additional command-line options to the Java executable when Tomcat is started.

If you placed your setup file in a different location, then adjust the path after ``-Dedg.setup=`` accordingly.
See also: :ref:`Setup File: Location <setup_file_location>`.

On Debian-based Linux distributions:
  Edit ``/etc/default/tomcat10`` and add:

  .. code-block:: bash

    CATALINA_OPTS="$CATALINA_OPTS -Dedg.setup=/var/lib/tomcat10/edg-setup.properties"
    CATALINA_OPTS="$CATALINA_OPTS --add-opens=java.base/java.util.concurrent.locks=ALL-UNNAMED"

On other Linux distributions and macOS:
  Edit/create Tomcat’s ``<CATALINA_BASE>/bin/setenv.sh`` file and add:

  .. code-block:: bash

    CATALINA_OPTS="$CATALINA_OPTS -Dedg.setup=/var/lib/tomcat10/edg-setup.properties"
    CATALINA_OPTS="$CATALINA_OPTS --add-opens=java.base/java.util.concurrent.locks=ALL-UNNAMED"

On Windows:
  Edit/create Tomcat's ``<CATALINA_BASE>\bin\setenv.bat`` file and add:

  .. code-block:: bat

    set "CATALINA_OPTS=%CATALINA_OPTS% -Dedg.setup="C:\Program Files\Apache Software Foundation\Tomcat 10.1\edg-setup.properties""
    set "CATALINA_OPTS=%CATALINA_OPTS% --add-opens=java.base/java.util.concurrent.locks=ALL-UNNAMED"

For more information on setting ``CATALINA_OPTS``, see the Tomcat documentation: `Using the "setenv" script`_


Including usernames in the Tomcat access log
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To include the EDG username in :ref:`Tomcat's access log <tomcat_access_log>`, edit
``<CATALINA_BASE>/conf/server.xml`` and modify the ``AccessLogValve``
entry (typically located at the bottom of the file).
Replace ``%u`` with ``%{username}s``. That is,

.. code-block:: xml

 pattern="%h %l %u %t &quot;%r&quot; %s %b"

should be changed to this:

.. code-block:: xml

 pattern="%h %l %{username}s %t &quot;%r&quot; %s %b"

This change is necessary because EDG does not use Tomcat's built-in authentication service.
See the
`Tomcat Access Log documentation <https://tomcat.apache.org/tomcat-10.1-doc/config/valve.html#Access_Log_Valve>`_
for more information.