Tomcat9 README.Debian

Migrating from previous Tomcat packages
---------------------------------------

  * Refer to the upstream migration guides for application compatibility
    and configuration changes:
    - http://tomcat.apache.org/migration-7.html
    - http://tomcat.apache.org/migration-8.html
    - http://tomcat.apache.org/migration-85.html
    - http://tomcat.apache.org/migration-9.html

  * Before the version 9 the Debian packages for Tomcat each created their
    own tomcat<n> users. You may need to recursively update your application
    directories to be owned by the tomcat user. This user will no longer
    change for the future upgrades.


Getting started
---------------

  * After installing the tomcat9 package, the server should be accessible
    at http://localhost:8080/

  * The default port 8080 can be changed by modifying the port of the
    connector in /etc/tomcat9/server.xml. Privileged ports (such as 80 or 443)
    can be used with no extra configuration.

  * If you install tomcat9-admin, you have to define an admin account to
    access the manager interface. Edit /etc/tomcat9/tomcat-users.xml and
    follow the instructions in the comments. The Tomcat manager will be
    accessible at http://localhost:8080/manager/html

  * Tomcat is not running under a Java security manager by default. If you
    expose your Tomcat instance to the internet, please consider editing
    your /etc/default/tomcat9 file and set SECURITY_MANAGER="true", then
    adjust policy files in /etc/tomcat9/policy.d/ as explained in
    https://tomcat.apache.org/tomcat-9.0-doc/security-manager-howto.html

  * Tomcat is sandboxed by systemd and only has write access to the following
    directories:
    - /var/lib/tomcat9/conf/Catalina (actually /etc/tomcat9/Catalina)
    - /var/lib/tomcat9/logs          (actually /var/log/tomcat9)
    - /var/lib/tomcat9/webapps
    - /var/lib/tomcat9/work          (actually /var/cache/tomcat9)

    If write access to other directories is required the service settings
    have to be overridden. This is done by creating an override.conf file
    in /etc/systemd/system/tomcat9.service.d/ containing:

      [Service]
      ReadWritePaths=/path/to/the/directory/

    The service has to be restarted afterward with:

      systemctl daemon-reload
      systemctl restart tomcat9

  * To run more than one Tomcat instance on your server, install the package
    tomcat9-user and run the tomcat9-instance-create utility.
    You should remove the tomcat9 package if you don't want Tomcat to
    start as a daemon at boot time.