OPENWGA HOSTING

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

Switch to a different version of the application server / JVM

• Stop the service
• Delete the my_appserv directory structure
• Use Service initialization to create the directory structure for the new versions.
• Start the service

Note: If you have made some modifications under my_appserv, e.g.:

• start/stop/watchdog script modifications
• application server files
• environment files
• etc.

remember to keep the modified files somewhere BEFORE deleting the my_appserv directory tree.

Note: Your applications and files are kept outside of my_appserv directory tree in My App Server default configuration. Thus removing my_appserv directory will not remove your data. Consider your changes if you have made modifications to the default configs.

Note: It is also possible that some applications are integrated with the application server and are storing data under its directory structure. Consider this BEFORE removing my_appserv directory tree.

Remember it is a backend server

This service accepts connections on a private interface only. Thus it can not be directly contacted by external hosts.

Typically a frontend web server ( Apache HTTPd ) is configured to pass the required requests to the backend.

The frontend might handle some of the requests that it receives on its own. E.g. requests for:

• static resources - HTML/CSS/JS/Image files
• CGI scripts
• SSI ( Server Side Includes )
• PHP files ( handled by mod_php )

and pass other requests to different backends. E.g certain parts of the URL space might be mapped to:

• JSP/Servlet engine - Tomcat which is configure to run via MyAppServer
• PHP-FPM backend providing specific PHP version support

See the section Servlet/filter mappings for an example on how to define the needed proxying rules .

It's a service suitable for production deployments

My App Server offers a production environment for hosting your services.

Development and testing should be done locally, not on this service.

See Restart Limits for some restrictions which apply.

"My Application Server" allows you to run your own backend application server (a daemon process) on the web hosting hardware.
E.g. (just on the Java side) you can run:

• Apache Tomcat
• Jetty
• GlassFish
• JBoss

and more.

Node.js (JavaScript) and Phusion Passenger (Python, Ruby and more) are also supported by this control panel via different extensions, but you can run them via MyAppServer too.

Strictly speaking - MyAppServer allows you to run any long running program that is supported on the server hardware and the running Linux kernel. Yes, this means that you can run a program written in any language, either compiled (e.g. C/C++) or interpreted (e.g. PHP, Perl, Python) with or without a virtual machine (e.g. JVM).

In order to run your custom application server you should:

• Upload the version of the application server which you intend to run with all its required dependencies.
• Initialize the service by choosing Tocat/JVM versions from the dropdowns
• Take a look at bin/start and bin/stop scripts. Replace those with a modified version which suits your needs. Search for "bin/" in this doc for additional information.
• you might need to override what the WatchDog does or replace it with your own version. Search for "WatchDog" in this doc for more info.

If a new stable version of a JVM or an AppServer ( the product should be available in the dropdowns ) has been released you might open a ticket and our admins can make it available for easy installation via this interface.

Memory

The subscription's hosting plan comes with a defined memory limit. Your software must be able to fit within this limit. If you find that the limit is too low you can upgrade to a plan with more memory.

Please note that it is likely that some hosting plans do not include any memory for MyAppServer at all. Thus it can NOT be used on such plans.

Timeouts

START - The service must be able to start within 90 seconds.
STOP - The service must be able to stop within 60 seconds.

Restart limits

The service can be started at most 3 times within 10 minutes. Subsequent attempts to start it in this interval will put it in failed state. Once the interval passes it can be started again.

This limit is imposed in order to prevent a failing service to consume excessive system resources(CPU/Memory/IO).

Network

Network bandwidth is typically not limited. If an excessive use is observed though we might be forced to impose some limits. This won't happen without a notification to you though.

Some external connections might be blocked by a firewall. E.g. SMTP connections to external hosts are not allowed in an attempt to prevent spamming. Outgoing mail should be routed via the local mail queue.

Other resources/process limits

Limits might be imposed on some other resources too. E.g.:

• Number of open files
• Maximum number of processes/tasks
• CPU time
• IO operations / bandwidth

ToS / AUP Limits

Please also consult the "Acceptable Use Policy" and "Terms of Service" of the service which you have subscribed to.

Some limits might be defined there which your service running via MyAppServer should/must comply.

What if MyApp does not fit in some of the limits

We might be able to help you. E.g.:

• Increase a timeout
• Provide public network port or public IP address
• Provide a plan with custom resource limits (e.g. memory)

Just open a trouble ticket and we will tell you if your demand can be fulfilled. There is no guarantee though.

SystemD

MyAppServer allows you to create a service for your software which is registered with the operating system service supervisor (SystemD).

Service control

Once created this service can be controlled by yourself. You can start/stop/restart it or send a TERM/KILL signal to its process group.

Service supervision

If your service exits My App Server has configured SystemD to restart it, no matter what the exit reason is:

• Normal (0) exit code
• Unclean exit code
• Unclean signal (e.g. SIGABRT, SIGKILL, etc.)
• Timeout during start/stop
• Failure to send a WatchDog signal

Service monitoring

Once started the service is constantly monitored.

E.g. in the default configuration HTTP requests are sent to each of the configured domains landing pages. If any of the requests fails the service is restarted.

Also, if the service fails to send a READY notification within a configured start timeout it is also considered as failed and a restart is tried.

To disable the service monitoring you can:

# Only do a "connect" check to the AJP port:
echo '[{"name":"CONNECT"}]' > my_appserv/envdir/MAS_WD_VHOSTS
# Do not do any checks, even the connect . Only send READY and KEEP-ALIVE signals to SystemD:
echo '[]' > my_appserv/envdir/MAS_WD_VHOSTS

Note that you can also make changes to the WatchDog or completely replace it with your own implementation if your service requires it.

Runs with your system user

The service runs with the privileges of your system user. This means that it has full access to all the resources in your web hosting account - files, databases, network connections, mailboxes, etc.

Own network

A private dedicated IP address is allocated to your service. Thus it can accept connections to any Network port that is available to your system user.

Under Linux, ports 1-1024 are typically reserved for privileged users. The rest are available for your use. It is guaranteed that the whole range of ports ( 1024 - 65536 ) is available for your use (TCP, UDP, etc.).

Auto-Start on server reboot

If this option is enabled the service will be started on server reboot.

Clean work directory on service start

If this option is enabled the default start script will remove default/work/*

Remove old logs on service start

If this option is enabled the default start script will remove default/logs/*

Service actions

Start

The START action attempts to start the service.

SystemD waits for a READY notification in order to consider the service started.

The default WatchDog configuration sends the READY signal when the landing pages of all the configured domains start to return non-error HTTP status codes.

See the rest of this documentation for ways to override the WatchDog behavior.

The START action executes my_appserv/bin/start . It can be changed to fit your service needs. Search for "bin/start" in this doc for more info.

See Limits for Start/Stop timeouts.

Stop

The STOP action attempts to stop the service gracefully. It waits for the main process of the service to exit.

In case that the stop command timeouts SystemD sends TERM & CONT signals to all the processes in the service group.

If there are remaining processes after the TERM signal the processes are killed with KILL & CONT signals . The KILL signal is non maskable and the Linux Kernel terminates processes which receive it. There are some very specific cases in which blocked processes can not be killed even with a KILL signal.

The STOP action executes my_appserv/bin/stop . It can be changed to fit your service needs. Search for "bin/stop" in this doc for more info.

See Limits for Start/Stop timeouts.

Restart

RESTART does a STOP followed by a START, so the descriptions of those two apply.

Reload

RELOAD usually does a configuration reload without restarting the whole daemon process.

This action is not implemented in the default scripts since Tomcat does not support a reload operation. So it is normal to fail if you execute it.

If your custom application server supports the reload operation you can create a bin/reload script which will be executed when this action is triggered. It is up-to you to decide what to do with this action.

Send SIGTERM / SIGKILL

Those allow to send the signals to all the processes in the service group. Those signals usually TERMinate or KILL the service.

Normally, those two actions should not be used.

Note that SystemD will restart the service if you kill it with one of those signals while it was in active state.

Service initialization

This action creates the my_appserv directory structure when it is missing. The directory structure will be initialized with the chosen Application server and JVM versions .

My App Server domains

A domain/subdomains can have My App Server support activated/deactivated if it:

• has its web hosting enabled
• is active, e.g. it is not suspended or disabled

This active/disabled state is used in the default configuration:

• by the bin/start script to generate the needed configuration files
• by the WatchDog to monitor the landing pages of the active domains

If you run a customized version of an application server or have modified the default start/stop/watchdog scripts you are free to ignore the activation status. E.g. you can have a default catchall VHost configured on the backend.