Child pages
  • _TBL Installation
Skip to end of metadata
Go to start of metadata

$ProductAbbrevName Server Installation

$ProductFullName runs on Web Application servers that support the 2.4 release of the Java Servlet specification. The following sections detail specific instructions for running TopBraid servers on Tomcat.

Tomcat Installation Instructions

The instructions give details for Tomcat, and may need variation depending on local setup. The details vary with other Web Application Servers and between different versions of Tomcat. Manual editing of the web.xml file is no longer supported. The following steps will create a correct web.xml file. Manual edits made for other applications are outside of the scope of this document, and not supported by TopQuadrant.

    1. Copy the downloaded zip archive file named TopBraid$ProductAbbrevName-[NNN].zip to any location.

      The WAR file $ProductAbbrevLowercase.war included in the zip is to be deployed on the Web Application Server. These instructions assume you do not rename this file.

    2. Undeploy any current $ProductAbbrevLowercase.war instance.

      • If hot deploy is enabled, delete $ProductAbbrevLowercase.war from the deployment directory and Tomcat will do the rest. The file to delete will be:


        These paths may be different if your Tomcat installation is configured with a different deployment directory.

      • Without hot deploy, or if hot deploy fails, you may need to stop the server and then manually undeploy:

        For Tomcat, remove the following:

        • $TOMCAT_HOME/webapps/$ProductAbbrevLowercase.war

        • the directory $TOMCAT_HOME/webapps/$ProductAbbrevLowercase

        • the directory $TOMCAT_HOME/work/Catalina/[server_name]/$ProductAbbrevLowercase

    3. In a separate terminal or window, open the log file for Tomcat in $TOMCAT_HOME/logs/catalina.out. This is the log file that prints startup messages for Tomcat.

    4. Copy $ProductAbbrevLowercase.war to the deployment directory: $TOMCAT_HOME/webapps.

    5. Check the log file. At this stage, relevant messages will include:

      Deploying web application archive $ProductAbbrevLowercase.war
    6. Open the $ProductAbbrevLowercase console by directing a browser to the $ProductFullName server being installed: http://[Web-application-server-host]:[Web-application-server-port]/$ProductAbbrevLowercase. A window similar to the following will appear:

      1. $ProductAbbrevName uses Secure Storage to save passwords that it uses (e.g., for databases). If you provide a Master password (recommended), $ProductAbbrevName will use it to encrypt its stored passwords. Otherwise, $ProductAbbrevName only uses Base64 encoding (i.e., unencrypted). Saving the Master password in the $ProductAbbrevName web.xml simply uses plain text, so you must ensure that access to the web.xml is restricted. Alternatively, instead of using the web.xml to save the Master password, it can be manually entered by an administrator each time the server is started: see $ProductAbbrevName AdministrationAccess Control: Provide secure storage password.

      2. Fill in the details on this page and "Submit".

      3. A web.xml file will be generated and either displayed by your browser or saved to your local file system.

    7. Stop Tomcat. Replace the $TOMCAT_HOME/webapps/$ProductAbbrevLowercase/WEB-INF/web.xml with the web.xml generated in the previous step.

    8. Start Tomcat.

Accessing the $ProductAbbrevName application

For access to the $ProductAbbrevName Console, send your browser to the URL http://[Web-application-server-host]:[Web-application-server-port]/$ProductAbbrevLowercase/tbl/

(This corresponds to TopBraid Composer ME's http://localhost:8083/$ProductAbbrevLowercase/ .)

NOTE: Until $ProductAbbrevName completes the license registration step, only one administrator may log in.

On the first visit, TopBraid Live itself is initialized, and you should see entries like the following added to the log:

  09-Sep-2016 13:06:36.478 INFO [main] org.apache.catalina.startup.VersionLoggerListener.log Server version: Apache Tomcat/8.0.33
  09-Sep-2016 13:06:36.479 INFO [main] org.apache.catalina.startup.VersionLoggerListener.log Server built: Mar 18 2016 20:31:49 UTC
  09-Sep-2016 13:06:36.480 INFO [main] org.apache.catalina.startup.VersionLoggerListener.log Server number:
  <etc., etc.>
  09-Sep-2016 13:07:13.371 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-apr-8080"]
  09-Sep-2016 13:07:13.384 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["ajp-apr-8009"]
  09-Sep-2016 13:07:13.395 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 36001 ms

If there are permission problems with the workspace, this step will not work. If the workspace does not exist, or is an empty directory, it will be created and populated.

The project and several others will be created in the workspace. If not, there were initialization problems and the TopBraid server will not work properly. In a Linux installation, the most common source of problems are folder permissions for the process running the Web Application Server. Try removing the workspace folder and reloading web.xml, making sure that the process has write access to the parent folder of the workspace folder.

License registration

After these steps, log into the $ProductAbbrevName server. A message will appear that point to the registration page, as shown in the following screen shot:

  1. Click on the Registration Page link. A page will appear stating that there are "No currently registered products!"
  2. Click on the Change or Update Registration Information link. Use the Choose File button to choose the license file (.lic file) sent by TopBraid support when the license was issued.

A dialog will appear, verifying that the license was updated. The licenses and their expiration date will be displayed. This page is always available through the Server Administration tab and choosing the Server Administration then the Product Registration links.

TopBraid GUI apps require persistence configuration: Application data storage

For GUI applications (excluding TopBraid Live), an administrator must configure the persistence installation for graph data, following these steps: Teamwork Platform Parameters: Application data storage.

The $ProductAbbrevName server-based application does not include the sample data that is included in TopBraid Composer-Maestro Edition (TBC-ME). If desired, the examples can be deployed from TBC-ME to the server by clicking on the sample project in TBC-ME's Navigator window and choosing Export... > TopBraid Composer > Deploy Project to TopBraid Live Server. Permission will default to "Administrator" for the sample project. Please update this in the role management page if needed.

Configuring authentication

The web.xml file created in the Tomcat Installation Instructions contains configuration settings based on how you filled out the form at installation. Use either the tomcat-users configuration, here, or the LDAP configuration, below. If using In Memory / User Database, please ensure that your <TOMCAT_ROOT>/conf/tomcat-users.xml is setup and users belong to appropriate roles.  An example is below:

   <role rolename="Admin"/>
   <role rolename="Manager"/>
   <role rolename="Editor"/>
   <role rolename="Viewer"/>
   <user username="Admin_user" password="password32" roles="Admin,Manager"/>
   <user username="Editor_user" password="password54" roles="Editor"/>
   <user username="Guest" password="password76" roles="Viewer"/>

It is imperative that your web.xml security roles match the roles defined in this tomcat-users.xml file.

The LDAP Configuration section of this installation guide has information on using TopBraid Live with the LDAP.

Reloading a modified web.xml

With Hot Deploy

If hot deploy is enabled, then this step is already done. A Tomcat log file will show something like the following:

May 23, 2009 2:13:23 PM org.apache.catalina.startup.HostConfig checkResources
INFO: Undeploying context [/tbl]
May 23, 2009 2:16:28 PM org.apache.catalina.startup.HostConfig deployWAR
INFO: Deploying web application archive $ProductAbbrevLowercase.war
osgi> May 23, 2009 2:18:26 PM org.apache.catalina.startup.HostConfig checkResources
INFO: Reloading context [/tbl]
May 23, 2009 2:18:26 PM org.apache.catalina.core.StandardContext stop
INFO: Container org.apache.catalina.core.ContainerBase.
   [Catalina].[localhost].[/tbl] has not been started
osgi> May 23, 2009 2:18:29 PM org.apache.catalina.core.StandardContext start
INFO: Container org.apache.catalina.core.ContainerBase.
   [Catalina].[localhost].[/tbl] has already been started

This may take a couple of minutes.

Other Web Application Servers will report the same behavior in different ways.

Without Hot Deploy

Go to the console for Tomcat or the equivalent if using another WebApplication Server. Find the $ProductAbbrevLowercase application and either Reload or Stop and then start the application.

Advanced Equinox Features

Many other Equinox features can be accessed by adjusting the Equinox command line or the config.ini file. (See below for more on this.) Many different options for Eclipse are documented. Some of them may be useful in $ProductFullName. However, very few have been tested. Please contact TopQuadrant support ( if you would like more information about using any of these options with $ProductFullName.

Modifying the configuration area

Equinox, like Eclipse, uses a configuration area to store some system files. By default this is created in a temporary area inside the Web Application Server. It can be deleted and recreated using the Equinox redeploy option from the $ProductFullName Administration menu. Using Tomcat, a possible path for the configuration area is:


To use a configuration area other than the default it is necessary to modify web.xml and initialize the new configuration area. (This is done automatically if using the default configuration.)

Using a custom configuration area is useful if, for example:

  • You wish to customize the initialization of the configuration.

  • There are difficulties using the configuration area within the temporary files provided by the web application server. For example, a lock file is used in the configuration area, which is incompatible with certain NFS arrangements.

The Steps

  1. Initialize New Config Area.
    1. Create a new directory.

    2. Copy webapps/$ProductAbbrevLowercase/WEB-INF/eclipse/configuration/config.ini into the new directory.

    3. Verify that the permissions and owner are appropriate. (The process running the web application server must be able to both read and write the configuration area.)

  2. Modify the commandline param of the $ProductFullName web.xml to include the -configuration option pointing to the new directory. For example:

 -data /var/lib/ontologies
 -configuration /var/lib/config320


You will find a sample web.xml file with the name web-config.xml in the installation directory of your $ProductFullName distribution zip file.

Configure Logging

If you encounter server startup problems, the following settings in Apache Tomcat's conf/ file can give you a better picture of what's going on:

handlers =,,,, 
  5$, java.util.logging.ConsoleHandler  
5$ = FINE 
5$ = ${catalina.base}/logs
5$ =$ProductAbbrevLowercase.  
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/$ProductAbbrevLowercase].level = INFO 
org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/$ProductAbbrevLowercase].handlers = 5$

Keep in mind that:

  • The handlers setting would replace the existing one. It is shown as three lines above, but should be one line in your file.

  • TopBraid Suite messages, including those related to startup issues, are sent to their own tomcat log file in $TOMCAT_HOME/logs/$ProductAbbrevLowercase.log.

Tomcat settings - other

A tomcat SSL connector, without an exclusion rule will require some characters be encoded where a flat http connector will not. This can cause problems with embedded links. 

The relaxedQueryChars exclusion rule can be set to relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;"



  • No labels