Tersus: Tersus Server Installation Instructions

Tersus Server Installation InstructionsDate: Mar 10, 2021Tags:Configuration,Deployment,HSQLDB,Linux,Mac,MySQL,PostgreSQL,TomcatIn order to deploy Tersus applications you must first set up a deployment environment which includes the following components:

Java Runtime Environment (JRE) 8

Application server with Java Servlet support - Apache Tomcat 7.0.x

Database server - HSQLDB, PostgreSQL, MySQL (Commercial DBMSs such as Microsoft SQL Server, DB/2, Oracle are supported by our commercial enterprise version)

Tersus Server

Once a deployment environment has been set up, you may deploy your tersus applications by copying your project from the studio environment to the server environment and creating an application-specific context file.1. Setup the Tersus Deployment EnvironmentInstall a Java Runtime Environment (JRE)Versions tested: 8

Go to the Java SE Downloads page.

Scroll down to the Java Runtime Environment (JRE) 8unnn section.

Download the Server JRE

Install the JRE as per the Installation Instructions.

Make a note of the JRE installation directory, we shall refer to it later as [JRE root].

Install JavaMail

Versions tested: 1.6

Go to the JavaMail API page
Click the Download JavaMail Release link
Click the javax.mail.jar link to download the jar file
Copy javax.mail.jar to [JRE root]/lib/ext.

Install Java Advanced Imaging (JAI) API

Versions tested: 1.1.2_01

Go to the Java Media APIs page
Click on the Java Advanced Imaging link
Click on the Java Advanced Imaging API 1.1.2_01 link
Locate the CLASSPATH Install matching your platform (for Mac OSX, use the the Linux version), and click the download link next to it
Accept the license agreement
Press the Download button
Sign in if prompted
Execute or extract the download and copy the contents of the lib/ subdirectory (JARs and DLLs/SOs) to [JRE root]/lib/ext.

Install Apache TomcatVersions tested: 7.0.x

Go to the Apache Tomcat 7 download page.

Scroll down to the Binary Distributions -> Core section.

Windows users should download the Windows Service Installer.
Users of other platforms should download the .tar.gz or .zip.

See the Tomcat documentation for details on installing, running, and configuring Tomcat to start on boot.
Make a note of the directory into which you installed Tomcat, we shall refer to it later as [Tomcat root].

Windows-specific instructions:

By default, the installer will install & start the Apache Tomcat service and load the Monitor Tomcat utility.

To configure the Apache Tomcat service to start automatically at boot, do the following:

Double-click the Apache Tomcat icon in the Windows taskbar notification area, to open the Apache Tomcat Properties window.
In the General tab, set the Startup type to Automatic, and click OK.
Verify that the installation was completed successfully by pointing a local browser at http://localhost:8080; this should open the default Tomcat home page.

Note that the Tomcat Monitor utility (displaying the Apache Tomcat notification area icon) is not required for regular operation of the Apache Tomcat service. You will want to keep it running while you perform the following steps, but once deployment is complete you may close it by right-clicking the icon, and selecting Exit.

Install Database Server and DriverTersus supports any of the database servers listed below.If you do not know which database server to install, we suggest installing HSQLDB, as it is a lightweight, pure-Java, open-source database engine, which is actually used by Tersus Studio's embedded application server. Deploying HSQLDB is as simple as copying a single jar file (which comprises both the server and driver), and will allow you to deploy the application together with the data entered while testing the application in Tersus Studio's embedded application server.Notes:

The versions specified for each database are those which we have tested against, newer versions will usually work as well. See the 3rd-Party Component Versions page for more details.

It is possible for different applications deployed in the same server to use different databases - therefore, you may install more than one database.

HSQLDB

Database Server and Driver

Download (Also available in [Tersus Server root]/WEB-INF/lib/)

Versions tested: 2.0

To install, extract the downloaded archive and copy hsqldb/lib/hsqldb.jar to [Tomcat root]/lib (or [JRE root]/lib/ext).

PostgreSQL

Database Server

Download

Version tested: 8.3

To install follow the PostgreSQL installation instructions available in the relevant download page for your platform.

Driver (PosgtreSQL JDBC 3)

Download (also available in [Tersus Server root]/WEB-INF/lib/)

Version tested: 8.1 (newer versions are not currently supported).

To install, copy postgresql-8.1-[nnn].jdbc3.jar to [Tomcat root]/lib (or [JRE root]/lib/ext).

MySQL

Database Server

Download

Versions tested: 5.0.51

To install follow the MySQL installation instructions available in the MySQL Documentation pages.

Driver (MySQL Connector/J)

Download

Version tested: 3.1.8a

To install, extract the Connector/J archive and copy mysql-connector-java-3.1.8/mysql-connector-java-3.1.8-bin.jar to [Tomcat root]/lib (or [JRE root]/lib/ext).

Install Tersus ServerDownload
First, make sure the server version matches your development environment version.To install the server, extract the contents of the server archive into an empty directory. The recommended location is: /tersus-server/Make a note of the installation directory, we shall refer to it later as [Tersus Server root].The Tersus Server components are configured by default to enforce Tomcat BASIC authentication of users. If the application you are deploying does not require authentication (i.e., it does not use the Authorization module - see the note below), you should do the following:

Rename [Tersus Server root]/WEB-INF/web.xml as [Tersus Server root]/WEB-INF/web.xml.authenticated

Rename [Tersus Server root]/WEB-INF/web.xml.not_authenticated as [Tersus Server root]/WEB-INF/web.xml

Notes:

Tersus provides 2 Authorization templates.
One is the Authorization template in the Palette's Modules category, usually added to an existing application, and based on BASIC (= non-modeled) authentication, meaning the above rename should not be performed.
The other is the Authorization application template specified when creating a project via File > New > Tersus Project, which demonstrates modeled authentication, which does not trigger Tomcat's BASIC authentication, and therefore requires the above rename to be performed.

It is possible for different applications deployed in the same server to use both authentication modes, by installing 2 copies of the server in separate directories.

2. Deploy a Tersus ApplicationOnce the deployment environment is set up, you may deploy multiple applications by copying them from the studio to the server environment, and creating an application-specific context file for each.Copy the Application to the Deployment EnvironmentThe application project files are located by default on your development machine in [Tersus Studio root]/workspace/[Application Project name]/. We shall refer to this location as [Application Development root].Create a new directory on your deployment server. The recommeded location is: /tersus-applications/[Application Project name]/. We shall refer to this location as [Application Deployment root].Copy the following files and driectories from [Application Development root] to [Application Deployment root]:

.project

.timestamp

models/

web/ (if exists)

database/ (optional - this directory contains the HSQLDB database created by the studio, and should be copied if you are deploying using HSQLDB and wish to access the data entered during modeling. If you are copying this directory, first make sure the application is not running in the Studio's embedded application server)

Notes:

In the Studio, use File -> Export to create an archive of your project which can then be copied to the deployment server and extracted to [Application Deployment root].

If the deployment environment has access to [Application Development root] then you may decide not to copy your application. Doing so should be avoided in production scenarios, as changes performed in the Studio will be deployed immediately.

Create an Application Context FileThe application context file is an XML file which specifies various parameters required by Tomcat in order to be able to load the application.You can use this application to create a context file, or download the application context file template from here, and replace the parameters (which are in the format $‍{parameter_name}) as follows:

$‍{General.Application_Name} - The name of the application. This name will appear in the url (which will be in the format http://hostname:8080/$‍{Application_Name}. If possible use the project name.

$‍{General.Tersus_Server_Root} - The root directory for Tersus Server (= [Tersus Server root])

$‍{General.Application_Root} - The root deployment directory of your application (= [Application Deployment root])

$‍{General.Root_System} - The path to the root system model (= the refId property of the model used as the starting point of your application). Usually (and by default) this is $‍{General.Application_Name}/$‍{General.Application_Name})

$‍{General.Initialize_Database} - Set this parameter to true, if you wish Tersus Server to synchronize changes in your model's Database Record elements with the existing database schema, set it to false otherwise.

$‍{General.Check_Database} - Set this parameter to true, if you wish Tersus Server to compare your model's Database Record elements with the existing database schema, set it to false otherwise.

$‍{General.Use_SQL_Quoted_Identifier} - Set this parameter to true, if you wish to access the database in quoted-identifier mode, allowing access to database schema (column/table/view) names containing non-English characters. Set to false (the default) if you wish all names to be sql-ized (i.e. all characters except English letters and digits are converted to underscores, and the name is considered case insensitive).

$‍{General.Development_Mode} - Set this parameter to true, if you wish Tersus Server to run the application in developer mod, allowing the creation of trace files, set it to false otherwise.

$‍{Database.Driver} - The JDBC driver class name for your chosen database and version
HSQLDB - org.hsqldb.jdbcDriver
PostgreSQL - org.postgresql.Driver
MySQL - com.mysql.jdbc.Driver)

$‍{Database.Username} - The database username (sa for the HSQLDB database created by the Tersus Studio, for other databases see their repsective installation/documentation)

$‍{Database.Password} - The database password (no password defined for an HSQLDB database created by the Tersus Studio, for other databases see their repsective installation/documentation)

$‍{Database.URL} - The jdbc url for your chosen database and version
HSQLDB - jdbc:hsqldb:file://$‍{General.Application_Root}/database/$‍{General.Application_Name}. (for the database created by the Tersus Studio)
PostgreSQL - jdbc:postgresql://$‍{Database.Hostname}/$‍{Database.Name}
MySQL - jdbc:mysql://$‍{Database.Hostname}/$‍{Database.Name}

$‍{Database.Hostname} - The hostname (and optionally port) on which the database server is running - if the database server is installed on the same machine as Tersus Server, localhost should work. (Note this parameter does not appear directly in the context file template refered to above, but rather in $‍{Database.URL} for certain databases).

$‍{Database.Name} - The name of the database containing the schema the application will be using. (Note this parameter does not appear directly in the context file template refered to above, but rather in $‍{Database.URL} for certain databases).

$‍{Database.Validation_Query} - A valid SQL statement, executed when the application is started to verify that the database is accessible. This parameter is optional - you can use a trivial select statment (for instance select now()).

If your application does not implement basic/tomcat authentication, the <Realm…/> element at the end of the file, should be removed or commented out (surrounding it with ).Save the Application Context FileName the application context file created in the previous step $‍{Application_Name}.XML and save it to [Tomcat root]/conf/Catalina/localhost/.Test the Deployed Application

Restart Tomcat.

Open the Tomcat Web Application Manager, by pointing your browser at http://localhost:8080/manager/html.

When prompted, enter the User/Password specified during installation (the default user is admin, password is empty).

The application manager will display a list of all applications Tomcat is currently running (not just Tersus-based applications). /$‍{Application_Name} should appear as one of the Paths in the list, with Tersus as the Display Name.

If the Running column shows false, click the Start link. The application list should reload and a message should appear at the top acknowledging the application has been started.

If the application does not start, review the context file, and the contents of the log files located at [Tomcat root]/logs, which are likely to include the relevant error messages.

Once the application has started, click /$‍{Application_Name} to view the application.

Enter your user credentials if prompted (i.e. if you configured the application in previous steps to require authentication).

Note that users should access the application directly, by using the URL: http://[hostname]:8080/$‍{Application_Name}.

3. Performance & Security ConsiderationsIn order to simplify deployment, this document makes use of installation defaults which are well known. Once basic deployment is complete, these defaults should be addressed in order to improve performance and secure your applications.

Enable compression of HTTP message content to improve Tomcat’s overall performance. This feature is supported by all modern browsers by default. To enable compression, do the following:

Open [Tomcat root]/conf/server.xml in a text editor

Edit the definition of the HTTP Connector on port 8080, adding the text in bold:

<Connector port="8080" protocol="HTTP/1.1"  connectionTimeout="20000" redirectPort="8443" 
compression="on|force" compressableMimeTypes="text/html, text/xml,text/plain,text/javascript,text/css"
compressionMinSize="2048" noCompressionUserAgents="gozilla, traviata"  />

Save server.xml and restart Tomcat in order for changes to take effect.

Specify memory allocation parameters for Tomcat. You should specify Initial (-Xms) and Maximum (-Xmx) values. Also specify the -XX:+CMSClassUnloadingEnabled option to improve memory management while restarting applications.
On Windows, these parameters can be set through the Tomcat Monitor utility (Java tab).
On Linux, these parameters should be provided on the command line, using the vmargs switch.
As a rule of thumb set allocations to a ¼ (Initial) and ½ (Maximum) of the physical memory.

If you are installing Tomcat on Windows, please note that by default the Windows installer creates a user admin with no password and permissions to access the Tomcat Administration and Tomcat Manager web applications. This should be changed for secure deployment. See the Tomcat documentation for more details.

If your application incorporates Authorization to authenticate users, you should remove the default user id Super, or at least change its password. See the Authorization module documentation for more details.