View source for Adding the Tomcat Virtual Platform to a gHN

[[Category:Administrator's Guide]]
==== Installation ====

The Tomcat Virtual Platform can be deployed on a gHN by uncompressing the related archive inside the ''$GLOBUS_LOCATION//virtual-platforms'' folder:
<pre>
tar -zxvf org.gcube.vre-management.virtualplatform-tomcat-X.tar.gz
</pre>

This will create a ''$GLOBUS_LOCATION//virtual-platforms/Tomcat6'' folder with the resources needed to enable the Tomcat 6 platform. Afterwards, the ''tar.gz'' archive and the ''doc'' folder (also created by the command above) should be removed.

==== gHN Configuration ====

[http://archive.apache.org/dist/tomcat/tomcat-6/ Download], [http://tomcat.apache.org/tomcat-6.0-doc/index.html install and configure] a  [http://tomcat.apache.org/index.html Tomcat] 6.0.X instance (tests have been made with version 6.0.32). 

Then next step is to add a user with the privileges needed to perform deployments on the instance. This is done by adding the following lines to the ''$CATALINA_HOME/conf/tomcat-users.xml'' file:
<source lang="xml">
<tomcat-users>

 <!-- other config settings -->

 <role rolename="manager-gui"/>
 <role rolename="manager"/>
 <role rolename="manager-script"/>
 <user username="USERNAME" password="PASSWORD" roles="manager-gui,manager,manager-script"/>
</tomcat-users>
</source>

where USERNAME and PASSWORD are chosen by the Site Manager. 

After the configuration, the instance must be started with the following command:

<pre>
$CATALINA_HOME/bin/startup.sh
</pre>

Do note that the Tomcat 6 instance can be hosted on any machine, not only on the one hosting the Tomcat Virtual Platform. This is because the interaction between the two are performed with a network protocol (HTTP).

==== Platform Configuration ====
The final step is to configure the Tomcat Virtual Platform for interacting with the Tomcat 6 instance.

In the ''$GLOBUS_LOCATION//virtual-platforms/Tomcat6'' folder, the ''Tomcat.properties'' file has to be edited for a proper configuration. Some of the settings reported in the file do not be touched and left with their default values, other must be filled.

The parameters to set are:

* '''BaseURL''': the host and port on which the Tomcat instance to bridge has configured to run
* '''User''': a valid username holding the roles of ''manager-gui'', ''manager'' and ''manager-script''
* '''Password''': the password for that username

The following example shows an example of configured file:

<pre>
Name=TOMCAT
Version=6
PlatformClass=org.gcube.vremanagement.virtualplatform.tomcat.Container
Resources=
DedicatedClassLoader=true
BaseURL=http://node16.d.d4science.research-infrastructures.eu:9000
User=manuele
Password=tomcat
</pre>

==== Verifying the Installation ====

If everything was properly configured, following a gHN restart, the gHN profile reports the availability of the Tomcat Platform as follows:

<source lang="xml">
    <Profile>
        <Infrastructure>gcube</Infrastructure>
        <GHNDescription>
            <Name>node16.d.d4science.research-infrastructures.eu:9001</Name>
            <ActivationTime>2011-07-04T19:06:43+02:00</ActivationTime>
            <Status>certified</Status>
            <Type>Dynamic</Type>

            <AvailablePlatforms>
                <Platform>
                    <Name>TOMCAT</Name>
                    <Version>6</Version>
                    <MinorVersion>0</MinorVersion>
                </Platform>
            </AvailablePlatforms>
     <!-- ... -->

    </Profile>
</source>

==== Troubleshooting ====

* If the platform does not appear in the gHN profile, possible causes are:
** the Tomcat instance is down
** the Tomcat instance is running on a different port than the one indicated in the ''Tomcat.properties''
** the hostname is wrongly reported in the ''Tomcat.properties''


* If the deployment of web applications with gCube does not work, double check the hostname and password of the privileged user. They can be verified by logging in the Manager Service of the Tomcat instance available at ''http://BaseURL/manager/html''


* Troubles with deployments and undeployments with gCube can be verified in the Manager Service of the Tomcat instance available at ''http://BaseURL/manager/html''. Here available web apps are listed and can be managed. However, it is strongly not recommended to manage applications from the Manager Service as this may cause misalignment with the gHN local state.