XWIKI HOSTING

We run Tomcat application server on Oracle JVM. Tomcat is run behind Apache HTTPd front-end so we could support additional environments - e.g. PHP.

We offer shared Tomcat hosting only. That is - one Tomcat running in one Java JVM hosts multiple web applications.

In order to provide isolation between applications of different customers Tomcat is started with its security manager enabled.

Tomcat calls the root directory of a domain or subdomain "application base" (appBase config option). Apache HTTPd calls it "document root" (DocumentRoot config option). In our environment Tomcat and Apache HTTPd virtual hosts are pointed to the same directory so DocumentRoot and appBase are the same thing.

A domain or subdomain can have Tomcat web apps deployed if it:

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

Additionally, the domain or subdomain DocumentRoot must be pointed to a directory which is directly under the subscription home directory. E.g.

• "/test" - (correct)
• "/httpdocs/test" - (NOT correct)

It is important to test your Tomcat web apps locally before requesting their deployment. The tests have to be done with Tomcat's security manager enabled. To enable the security manager locally open a terminal window and run:

# Linux/Unix/Mac:
cd $TOMCAT_HOME
./bin/catalina.sh run -security

# Windows:
cd %TOMCAT_HOME%
bin\catalina.bat run -security

We offer production environment for hosting your Tomcat web apps. This environment is not suitable for development or testing.

Tomcat web apps should you placed directly in the DocumentRoot. For a subscription's main domain DocumentRoot is pointed to /httpdocs by default.

Here's an example.
Let's say that you have a docs.mydomain.com subdomain pointed to /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 contexts can be deployed:

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/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

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.

WAR stands for Web application Archive .

To request a deployment go to the "Websites & Domains" section, find the domain/subdomain that should serve the web app and click its Tomcat button.

You will find a "Deployment request form" on the opened page.
This form contains:

• A list of deployable contexts
• A checkbox to request manual review of the web app META-INF/context.xml
• A text area where you can add additional information to the person who will process your request

The list of deployable contexts is generated by scanning the DocumentRoot. An entry in the list is created for:

• directories placed directly in the DocumentRoot and
• containing a subdirectory WEB-INF and
• having names which can be valid context path

META-INF/context.xml will be ignored even if it exists unless you check the checkbox. Please do so if you have custom Resource/Realm/etc definitions there. It will be reviewed and you will be able to see how it has been applied in the "Support reply" .

To Start/Stop/Reload web apps go to the "Websites & Domains" section, find the domain/subdomain containing the web app and click its Tomcat button. You will see the list in the "Deployed web applications" section. Started web apps can be stopped and stopped ones can be started. To reload a web app stop it first and then start it.

Our hosting servers are configured for production use. The automatic reloads which are usually enabled in the default Tomcat configuration are disabled. No automatic checks for JSP, class, JAR, web.xml, etc modifications are performed.

You need to manually reload your web apps after doing modifications.

Tomcat logs can be found in the /logs-tomcat directory which is placed in the subscription's home. The logs are rotated when they reach 1 MB and 10 old log files are preserved.

The STDOUT and STDERR streams of each application are redirected to these logs so e.g. System.out.println(..) and System.err.println(..) go there.

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

1. As usual they have to be defined in WEB-INF/web.xml
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://127.0.0.1:8009/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://127.0.0.1:8009/app1/$1 [NE,P,L]

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

RewriteEngine On
RewriteRule ^(.*)$ ajp://127.0.0.1:8009/$1 [NE,P,L]

Tomcat's security policy is defined in the file $TOMCAT_HOME/conf/catalina.policy.

Our policy grants all the permissions in the default catalina.policy distributed with Tomcat. It also grants several additional permissions commonly required by web apps. Some of them are:

• Each of your applications is granted read/write/delete permissions for all files and dirs under subscription's home dir
• Read permission is granted to all system properties
• New Socket connections are allowed
• Some additional package access is granted as well as Reflection permissions

If you find that a permission is required by your web app but it is not granted by our policy you could request it via the HelpDesk. Our administrators will review your request and grant the permission if it is appropriate.

Please note that requests for permissions that might affect the application isolation or the security of the other users' web apps will be denied.

The Tomcat security policy grants web apps read/write/delete permissions for all the files and dirs under the subscription home.

The file system permissions must also allow the system user "tomcat" to do the respective operation.

E.g. to create a directory which is writable by "tomcat" you can login via FTP and do:

mkdir docs/app1/store1
chmod a+rwx docs/app1/store1

You can also create dirs and manage permissions via Plesk File Manager .

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

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

"Tomcat management" page shows the actual DocumentRoot for the domain/subdomain.

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

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

mail.jar and activation.jar are pre-installed in $TOMCAT_HOME/lib so you don't need to put them in your web app's WEB-INF/lib .

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 is pre-installed in $TOMCAT_HOME/lib so you don't need to put it in your web app's WEB-INF/lib .

PostgreSQL drivers are not pre-installed. Neither are SQLite and HSQLDB drivers.

We do not recommend using connection pooling in our environment since the connection establishment to the DB is 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

• MySQL drivers - mysql-connector-java-bin.jar
• Java mail required JARs - mail.jar and activation.jar
• Standard libs that come in the default Tomcat distribution