Deploy GTD Excel Report Server App (WAR Package)

GTD Excel Report Server is implemented as a Web service. There are 2 distributions of GTD App.

• Stand-alone server (Web server + GTD App)
• WAR Package

In this page we talk about deployment of WAR, To learn more on installation of stand-alone server, please visit Install GTD Server

First, please make sure that what you downloaded is WAR. You will see gtdreport.war if you unzip the downloaded archiver.

GTD Excel Report Server is 100% pure java. You should have Java Runtime Environment (JRE) installed on your server before you install GTD Server.
If you have installed the JRE or JDK 1.5 or above, please ignore this section.

Fore moe information, please click here

The GTD WAR is deployed in the J2EE container. For example:

• Oracle Weblogic 9+
• Apache Tomcat
• IBM WebSphere
• JBoss

You should install J2EE container first. You can also try the GTD stand-alone server if you don't want to spend a long time on configuration of J2EE container.

You may need to customize your WAR to meet your production environment.

WAR to Folder

To alter the WAR, you should unzip the gtdreport.war first. If you are not familiar with JAR program, you can unzip it by WinZip or WinRar.

1. Rename gtdreport.ear to gtdreport.zip

2. Unzip the gtdreport.zip

Folder to WAR

If you have changed the web.xml or other files, and want to compress the GTD App to WAR. It is also simple.

1. Compress the directory to gtdreport.zip, make sure that WEB-INF and META-INF folder is in the root direcotry of the ZIP file.

2. Rename gtdreport.zip to gtdreport.war

There are 3 types of authenticators

• GTD Server + File System
• GTD Server + LDAP Server
• Container

For stand-alone server distribution, the users are authenticated by GTD Server by default.

The WAR distribution of GTD App is built using container-managed security by default. You can also setup GTD Server Managed Security.

You may need to check the web.xml and weblogic.xml etc, see how to configure your J2EE container to provide authentication/authorization for GTD App.

Container-managed authentication methods control how a user's credentials are verified when a web app's protected resource is accessed.

web.xml fragment

<security-constraint> <web-resource-collection> <web-resource-name>Areas with authentication required</web-resource-name> <url-pattern>*.do</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>user</role-name> <role-name>admin</role-name> <role-name>developer</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>NONE</transport-guarantee> </user-data-constraint> </security-constraint> <login-config> <auth-method>FORM</auth-method> <form-login-config> <form-login-page>/login.do</form-login-page> <form-error-page>/login.do</form-error-page> </form-login-config> </login-config> <security-role> <role-name>user</role-name> </security-role> <security-role> <role-name>admin</role-name> </security-role> <security-role> <role-name>developer</role-name> </security-role>

The GTD App supports 3 roles

• admin
• developer
• user

To allow a user to use GTD App, you should try one of the following solutions.

• Assign users to one of the 3 roles. You may need to create the 3 roles(admin/developer/user) in your authentication provider (J2EE container or LDAP server).
• Map existing roles to GTD predefined roles(admin/developer/user).

Mapping roles is recommended.

Map existing roles to GTD predefined roles

If there are roles and users managed by your J2EE container, and you don't want to create roles of GTD App, you can map roles of J2ee container to roles of GTD App.

Please edit the weblogic.xml. The file is located in WEB-INF folder.

1. Define roles of J2EE container. Sample code:

<security-role>
<description>Show you how to define your security role</description>
<role-name>role1</role-name>
</security-role>
<security-role>
<role-name>role2</role-name>
</security-role>
<security-role>
<role-name>role3</role-name>
</security-role>

There are 3 roles in the sample code above. They are role1/role2/role3.

2. Map roles of J2ee container to roles of GTD App. Sample code:

<servlet>
<servlet-name>action</servlet-name>
<servlet-class>org.apache.struts.action.ActionServlet</servlet-class>
<init-param>
<param-name>config</param-name>
<param-value>/WEB-INF/struts-config.xml</param-value>
</init-param>
<init-param>
<param-name>debug</param-name>
<param-value>3</param-value>
</init-param>
<init-param>
<param-name>detail</param-name>
<param-value>3</param-value>
</init-param>
<load-on-startup>0</load-on-startup>
<!-- ecurity role name used in a <role-link> must be defined in a <security-role> -->
<security-role-ref>
<role-name>admin</role-name>
<role-link>role1</role-link>
</security-role-ref>
<security-role-ref>
<role-name>developer</role-name>
<role-link>role2</role-link>
</security-role-ref>
<security-role-ref>
<role-name>user</role-name>
<role-link>role3</role-link>
</security-role-ref>
</servlet>

Mapping in above code.

• role1 -> admin
• role2 -> developer
• role3 -> user

Please login GTD Server using the username and password with the authentication realm of container, don't use username/password configured in GTD Server

Sample: WebLogic

Please edit the weblogic.xml. The file is located in WEB-INF folder.

You will see the sample code provided by the vendor.

<security-role-assignment>
<role-name>admin</role-name>
<principal-name>principal_name_1</principal-name>
<principal-name>principal_name_2</principal-name>
<principal-name>principal_name_3</principal-name>
</security-role-assignment>

The <principal-name> can map to
a) a user defined in any realm or
b) a group defined in any realm

You can change the principal-name according to the active realm of weblogic. For example

<security-role-assignment>
<role-name>admin</role-name>
<principal-name>mygroup1</principal-name>
</security-role-assignment>

<security-role-assignment>
<role-name>developer</role-name>
<principal-name>mygroup3</principal-name>
<principal-name>mygroup2</principal-name>
</security-role-assignment>

GTD Server Managed Security

The WAR distribution of GTD App is built using container-managed security by default. You can also setup GTD Server Managed Security.

However, container-managed security is strongly recommended.

1. To apply GTD Server Managed Security, you should set authenbycontainer=false first.

web.xml fragment

<init-param>
<param-name>authenbycontainer</param-name>
<param-value>false</param-value>
</init-param>

2. And then remove or comment out the following element in web.xml

• <security-role-ref>
• <security-constraint>
• <security-role>

web.xml fragment

<!-- <login-config>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>/login.do</form-login-page>
<form-error-page>/login.do</form-error-page>
</form-login-config>
</login-config> -->

3. And then restart the deployment. Now you can login the GTD Server using users managed by GTD Server.

1. Create directory for configuration files of GTD server

Please create directory for the configuration files of the server. Make sure that the directory is writable for user that starts GTD report server.

Recommended directory:

• c:\gtdserver\config\ (For Windows)
• /usr/local/gtdserver-data/config(For Linux)

This directory is named Configuration Directory in this document

2. Create directory for log files.

Please create directory for the log files. Make sure the directory is writable for user that starts GTD report server.

Recommended directory:

• c:\gtdserver\log\ (For Windows)
• /usr/local/gtdserver-data/log (For Linux)

This directory is named Logging Directory in this document

Please create a file named gtdreport.log in this directory, and make sure that GTD App can change the file.

The GTD App requires the following information when it is startting up.

1. The Configuration Directory. The server will save configuration files to the directory.
2. The path of the log files. You may want to server save log files on the Logging Directory.

How to tell GTD App the Configuration Directory? There are 2 ways.

1. Pass parameters by file

The GTD server will load the configuration file named gtdreport.properities from the root of classpath .

Sample file for Linux:

configDir=/usr/local/gtdserver-data/config
logFile=/usr/local/gtdserver-data/log/gtdreport.log

Sample file for Windows: ( Note: If you use backslashes, you must double them )

configDir=c:/gtdserver/config
logFile=c:\\gtdserver\\log\\gtdreport.log

So please create the file and put it to classpath. If there is not direcory in the classpath, you need to add a directory to classpath, and then restart the J2EE container(Weblogic etc).

2. Pass parameters by web.xml

You can edit the web.xml, setup the configDir and logFile parameter.

<init-param> <param-name>configDir</param-name> <param-value>c:/gtdserver/config</param-value> </init-param> <init-param> <param-name>logFile</param-name> <param-value>c:/gtdserver/log/gtdreport.log</param-value> </init-param>

Now you are ready to deploy the WAR.

You can also impletement the SSO by alter the Login Module defined in the web.xml.