Articles: Apache Tomcat
Useful information about our platform

The following section is specific for "Apache Tomcat".

Initial service initialization via the dropdowns

The provided Tomcat versions are the stock ones - these are the ones available from the official Apache Tomcat website.
The modifications which are made to them are only in the config files:

conf/context.xml
conf/logging.properties
conf/server.xml

If a file is modified the original are kept with an .orig extension, e.g. conf/server.xml.orig . This is done in order the changes to be easily trackable by you or an operator.

Tomcat versions

There are pre-configured Tomcat versions which can be chosen when initializing the MyAppServer service.

If you need you can run any Tomcat version. If the required version is not already available on your hosting server you can upload it.

Note: It is a good idea to stop the service before changing the versions.

When you initialize the service with JVM/Tomcat versions from the dropdowns a directory structure like the following is created for you:

my_appserv/apache-tomcat-9.0.41/
my_appserv/default -> apache-tomcat-9.0.41

Here default is a symlink to apache-tomcat-9.0.41. To run a custom Tomcat version you can create a structure like this:

my_appserv/apache-tomcat-9.0.41/
my_appserv/apache-tomcat-10.0.3/
my_appserv/default -> apache-tomcat-10.0.3

In this example the old Tomcat version is kept and the default symlink is repointed to the new version.

Note that the stock service start/stop scripts might not work with some Tomcat versions. These startup/shutdown scripts are also symlinks:

my_appserv/bin/start -> /scm/plesk-myappserv/bin/user-start.sh
my_appserv/bin/stop -> /scm/plesk-myappserv/bin/user-stop.sh

If they don't work for some reason you can replace the symlinks with your custom start/stop scripts. Make sure to look at what the stock ones do though, as it might be a good idea to base your modifications on them. E.g. the default bin/start:

• generates conf/server.xml.lhs_generated
• starts the watchdog which notifies SystemD for successful service startup and does the WatchDog stuff ( keep-alive monitoring )

Tomcat modifications

As you might have already guessed - all custom modifications to Tomcat are allowed. E.g. you can:

• place JARs directly in Tomcat's lib directory if this is required (e.g. by your DB connection pooling code, resource definitions, etc. ),
• modify Tomcat startup scripts and configs
• add/delete/replace Tomcat files
• etc.

When initializing the service via the dropdowns Tomcat is pre-configured like this:

conf/server.xml -> server.xml.lhs_generated
conf/server.xml.lhs_generated

The bin/start script generates the file server.xml.lhs_generated which is based on the domains with activated MyAppServer support and the applications which are found in their directory structure.

If you need you can replace the conf/server.xml symlink with the modified server.xml which you need.

JVM versions

There are pre-configured JVM versions which can be chosen when initializing the MyAppServer service. Your Tomcat instance is then pre-configured to use the chosen JVM version.

If you need though you can run any JVM version. If it is not available on your hosting server you can upload it and edit the following files:

my_appserv/envdir/JAVA_HOME
my_appserv/envdir/JAVA_OPTS

These are symlinks by default, so you might need to remove them and create new files on their place.

Make sure to specify the full(absolute) path to the JVM, not a relative one.

JVM modifications

You can upload your own JVM and modify it as needed.
Modifications to the global JVMs ( those pre-installed on the server ) are not allowed.

Please note that some modifications might by denied by law - e.g. use of strong cryptography is not allowed in some countries. It is up-to you to obey such restrictions.

Type or number of deployed applications

You can run any number of Java web apps that you like.
All Java frameworks can be used and are supported.

Is this a private JVM ?

What this service offers can be considered a Private JVM or Private Tomcat . It actually offers more than what others include in these terms as My App Server is designed to be very flexible and can run anything, not just predefined versions of JVM/Tomcat .

Tomcat security manager

Tomcat's security manager is NOT enabled in the default configuration as its default security policy imposes some restrictions which prevent some applications from working correctly.

If you application recommends using a security manager you can enable it and customize the security policy.

DocumentRoot and appBase

Tomcat calls the root directory of a domain or subdomain "application base" ( appBase config option of a Host element in server.xml ).

Apache HTTPd calls it "document root" ( DocumentRoot config option ).

In the default configuration of My App Server Tomcat and Apache HTTPd virtual hosts are pointed to the same directory so DocumentRoot and appBase are the same thing.

Note: This description is for the unmodified configuration of My App Server. You are free to modify the service as needed.

Where should you place your Tomcat web apps

Tomcat web apps should you placed directly in the DocumentRoot.

For the main domain of a subscription the DocumentRoot is pointed to the /httpdocs directory by default.

Here's an example.
Let's say that you have a docs.mydomain.com subdomain pointed to the /docs directory with the following structure:

1. /docs/WEB-INF
2. /docs/app1/WEB-INF
3. /docs/app2/WEB-INF

With this layout the following application contexts will be created:

1. docs.mydomain.com/
2. docs.mydomain.com/app1/
3. docs.mydomain.com/app2/

Each Tomcat context represents a separate web app with its own classes, libraries, JSP files, etc. E.g:

• /docs/app1/META-INF/context.xml
• /docs/app1/WEB-INF/web.xml
• /docs/app1/WEB-INF/lib/jar1.jar
• /docs/app1/WEB-INF/lib/jar2.jar
• /docs/app1/WEB-INF/classes/Class1.class
• /docs/app1/WEB-INF/classes/package1/subpackage1/OtherClass.class

Note: This description is for the unmodified configuration of My App Server. You are free to modify the service as needed.

Application context scanner

The default scanner creates a new Context for each directory that:

• is placed directly in the DocumentRoot ( first level child of DocumentRoot )
• contains a first level child subdirectory named WEB-INF
• has a name which validates as a context path

An example has been provided in the sections above.

Manager and HostManager Tomcat apps

These are not enabled by default.

If you need them you can enable them by either:

• editting server.xml or
• copying the apps to your DocumentRoot

You might need to make some changes to the app config files also. E.g. the login credentials in conf/tomcat_users.xml and access limits in the app's META-INF/context.xml . The required changes depend on the chosen Tomcat version and the shipped version of the app.

WAR files

WAR stands for Web application ARchive .

WAR files must be extracted in order to be deployed. E.g. the contents of test.war should be placed in a directory named test.

Note: This description is for the unmodified configuration of My App Server. You are free to modify the service as needed.

You can provide a custom server.xml to support deployments from WAR files.

While Tomcat can run an app directly from a WAR without unpacking it we strongly advise against such configuration as it is very likely that it will lead to a vastly degraded performance.

Tomcat can auto extract your WARs if you set unpackWARs="true" for the respective Host .

Default Host configuration

Each Host element in Tomcat's server.xml config file is configured like this by default:

deployXML="true" - customizations in META-INF/context.xml are supported
deployOnStartup="false" - Do not do application discovery on startup. Only apps configured in server.xml are deployed.
autoDeploy="false" - No deployment of new apps placed in appBase while Tomcat is running.
unpackWARs="false" - Do not extract WAR files automatically

This are settings which are suitable for production use.

As already mentioned you can provide your own server.xml if e.g. you insist on deploying from WAR files.

Tomcat logs

Tomcat logs can be found in my_appserv/default/logs directory:

catalina.out - STDOUT & STDERR of the start script are redirected to this log
catalina.stop - STDOUT & STDERR of the stop script are redirected to this log
watchdog.log - STDOUT & STDERR of the WatchDog are redirected to this log

Note: This description is for the unmodified configuration of My App Server. You are free to modify the service as needed.

Deployment of new web applications

• Stop the service
• Upload your application
• Start the service

If you upload your application while the service is running its contents might be available via the ROOT context.

Note: This description is for the unmodified configuration of My App Server. You are free to modify the service as needed.

Application reloads

Tomcat might pick some changes automatically. E.g. new or updated JSP or class files. It usually decides which files have been updated by checking their modified time . E.g. if a JSP page has a newer modified time than its corresponding pre-compiled class file Tomcat re-compiles it.

If some changes are not picked up you might need to restart the service.
Note that some changes might be ignored even on Tomcat restart. If this happens to you you might want to switch on the option "Clean work directory on service start" and retry the restart.

Servlet/filter mappings

When a My App Server support is switched on for a domain, custom rules are added to the Apache HTTPd frontend to pass all the requests to JSP files to the backend server via the AJP protocol.

Typical web applications require additional mappings though. E.g. mappings for Servlets or Filters.

In order your app mappings to work as expected two things must be done:

1. As usual they have to be defined in your application ( e.g. in WEB-INF/web.xml or via an annotation )
2. Apache HTTPd frontend has to be configured to pass them to the Tomcat backend.

The second step is done via .htaccess files. Here's an example. Let's say you have the following context:

http://docs.mydomain.com/app1/

and this web app has:

/docs/app1/WEB-INF/web.xml

which contains:

<servlet-mapping>
    <servlet-name>MyServlet</servlet-name>
    <url-pattern>/myservlet/action1</url-pattern>
</servlet-mapping>

You have to create the file:

/docs/.htaccess

which contains:

RewriteEngine On
RewriteRule ^app1/myservlet/action1$ ajp://mas-YOUR_SYS_USERNAME/app1/myservlet/action1 [NE,P,L]

You can also map all requests for the app1 web app to Tomcat like this:

RewriteEngine On
RewriteRule ^app1/(.*)$ ajp://mas-YOUR_SYS_USERNAME/app1/$1 [NE,P,L]

Or you can even forward all requests for this subdomain to the Tomcat backend:

RewriteEngine On
RewriteRule ^(.*)$ ajp://mas-YOUR_SYS_USERNAME/$1 [NE,P,L]

Read/Write/Delete files on the file system

You should be extra carefull when using relative paths. They can be relative to something different than what you expect.

In order to check a relative path you can place a code like this in e.g. test.jsp:

<%@page contentType="text/plain; charset=UTF-8" pageEncoding="UTF-8"%>
<%
java.io.File f = new java.io.File(".");
out.println( "path: " + f.getAbsolutePath() );
%>

The directories which you see when you login via FTP or in the Plesk File manager are relative to the subscription home dir.

Here's an example of an absolute path:

/var/www/vhosts/mydomain.com/docs/WEB-INF/uploads/file1.txt

If you encounter:

java.security.AccessControlException: access denied (java.io.FilePermission /SOME/PATH)

the usual causes are:

1. Wrong paths
2. Wrong file system permissions

A file or directory can have the required read/write/execute permissions removed.
You can manage permissions via Plesk File Manager or the chmod command.

Java mail

In order to send mail from your Tomcat web app you can use the following settings:

Hostname: localhost
TCP port: 25
Username: [email protected]
Password: mailbox's password

You might need to place mail.jar and activation.jar in your webapp's WEB-INF/lib depending on the mail API implementation that you use.

Connecting to a database from your Tomcat web app

Here's an example for MySQL which you can place in e.g. test.jsp:

<%@page language="java" import="java.sql.*" contentType="text/plain; charset=UTF-8" pageEncoding="UTF-8"%>
<%
Class.forName( "com.mysql.jdbc.Driver" );
java.sql.Connection con = DriverManager.getConnection(
    "jdbc:mysql://localhost/DBNAME",
    "USERNAME",
    "PASSWORD"
);
out.println( con.toString() );
%>

The MySQL driver should be placed in your webapp's WEB-INF/lib .

Database connection pooling

We do not recommend using connection pooling in our environment since the connection establishment to the DB is very lightweight process.

Just close the DB connections when you're finished with them and reopen them when needed.

A request scope is an excellent lifespan for a DB connection.

Be especially careful when reusing pooled connections since the RDBMS might be configured to timeout inactive connections and you might encounter:

java.sql.SQLException: No operations allowed after connection closed