SAMO 9 Tomcat Deployment

Overview

This guide covers the complete deployment of SAMO 9 platform using Apache Tomcat. Follow these steps carefully to ensure a successful deployment.

Prerequisites

Apache Tomcat 9.0.100 installed and extracted
Java 17 - Eclipse Temurin OpenJDK 17.0.7.7
Database configured (Oracle or PostgreSQL)
Elasticsearch 8.17.4 installed and running (ES8)
JDBC drivers for your database
SAMO 9 WAR files

info

Throughout this guide, <TOMCAT_HOME> refers to your Tomcat installation directory (e.g., C:\apache-tomcat-9.0.100).

Configuration Steps

1. Configure Tomcat Users

Configure admin access to the Tomcat management console.

Edit the file <TOMCAT_HOME>\conf\tomcat-users.xml and add the following roles and user:

<tomcat-users>
  <role rolename="admin"/>
  <role rolename="admin-gui"/>
  <role rolename="manager-gui"/>
  <user username="administrator" password="your_password" roles="admin,admin-gui,manager-gui"/>
</tomcat-users>

warning

Replace your_password with a strong password for security purposes.

2. Configure Tomcat Port

By default, Tomcat runs on port 8080. You may want to change this port.

Edit the file <TOMCAT_HOME>\conf\server.xml and find the Connector element:

<!-- A "Connector" represents an endpoint by which requests are received
     and responses are returned. Documentation at :
     Java HTTP Connector: /docs/config/http.html (blocking & non-blocking)
     Java AJP Connector: /docs/config/ajp.html
     APR (HTTP/AJP) Connector: /docs/apr.html
     Define a non-SSL HTTP/1.1 Connector on port 8080
-->
<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443" />

Change the port to your desired value (e.g., 9500):

<Connector port="9500" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443" />

3. Add JDBC Drivers

Download and install the appropriate JDBC driver for your database.

For Oracle Database

Download Oracle JDBC driver from Oracle JDBC Downloads
Copy the following JAR files to <TOMCAT_HOME>\lib\:
- ojdbc8.jar (or appropriate version for your Oracle database)
- orai18n.jar (for internationalization support)

For PostgreSQL Database

Download PostgreSQL JDBC driver from PostgreSQL JDBC Downloads
Copy the JAR file to <TOMCAT_HOME>\lib\:
- postgresql-42.x.x.jar (e.g., postgresql-42.2.2.jar)

4. Configure JDBC Connection Pool

Edit <TOMCAT_HOME>\conf\server.xml and add the database connection pool configuration inside the <GlobalNamingResources> element.

For Oracle Database

<GlobalNamingResources>
  <!-- Other resources... -->
  
  <Resource name="jdbc/SAMOdemo9"
            auth="Container"
            type="javax.sql.DataSource"
            driverClassName="oracle.jdbc.OracleDriver"
            url="jdbc:oracle:thin:@your-db-host:1521:orcl"
            username="SAMO_USER"
            password="SAMO_PASSWORD"
            maxTotal="20"
            initialSize="0"
            minIdle="0"
            maxIdle="8"
            maxWait="10000"
            timeBetweenEvictionRunsMillis="30000"
            minEvictableIdleTimeMillis="60000"
            testWhileIdle="true"
            poolPreparedStatements="false"
            maxOpenPreparedStatements="100"
            validationQuery="SELECT 1 FROM DUAL"
            maxAge="600000"
            rollbackOnReturn="true"/>
</GlobalNamingResources>

For PostgreSQL Database

<GlobalNamingResources>
  <!-- Other resources... -->
  
  <Resource name="jdbc/SAMOdemo9"
            auth="Container"
            type="javax.sql.DataSource"
            driverClassName="org.postgresql.Driver"
            url="jdbc:postgresql://your-db-host:5432/samo_database"
            username="SAMO_USER"
            password="SAMO_PASSWORD"
            maxTotal="20"
            initialSize="0"
            minIdle="0"
            maxIdle="8"
            maxWait="10000"
            timeBetweenEvictionRunsMillis="30000"
            minEvictableIdleTimeMillis="60000"
            testWhileIdle="true"
            poolPreparedStatements="false"
            maxOpenPreparedStatements="100"
            validationQuery="SELECT 1"
            maxAge="600000"
            rollbackOnReturn="true"/>
</GlobalNamingResources>

warning

Update the following parameters according to your environment:

name: JDBC resource name (must match the JNDI name used in your application)
url: Your database connection URL
username: Your database username
password: Your database password

Map JDBC Resource in Context

After configuring the global JDBC resource, you need to link it in the application context.

Edit <TOMCAT_HOME>\conf\context.xml and add the <ResourceLink> element inside the <Context> element:

<Context>

    <!-- Default set of monitored resources. If one of these changes, the    -->
    <!-- web application will be reloaded.                                   -->
    <WatchedResource>WEB-INF/web.xml</WatchedResource>
    <WatchedResource>${catalina.base}/conf/web.xml</WatchedResource>

    <!-- Uncomment this to disable session persistence across Tomcat restarts -->
    <Manager pathname="" />

    <JarScanner scanManifest="false"/>
    
    <!-- JDBC Resource Link -->
    <ResourceLink name="jdbc/SAMOdemo9" 
                  global="jdbc/SAMOdemo9" 
                  type="javax.sql.DataSource"/>

</Context>

info

The name attribute in <ResourceLink> must match:

The name attribute in the <Resource> element in server.xml (step 4)
The JNDI name expected by your SAMO application

If you used a different resource name in step 4, update it accordingly here.

5. Configure JVM Memory Settings

Configure Java Virtual Machine memory settings for optimal performance.

Windows

Edit <TOMCAT_HOME>\bin\setenv.bat:

set "JAVA_OPTS=-Xms512m -Xmx1024m -XX:MaxNewSize=500m -XX:+UseG1GC -Dfile.encoding=UTF-8 ^
--add-opens=java.base/java.lang=ALL-UNNAMED ^
--add-opens=java.base/java.util=ALL-UNNAMED ^
--add-opens=java.base/java.io=ALL-UNNAMED ^
--add-opens=java.base/java.lang.reflect=ALL-UNNAMED ^
--add-opens=java.base/jdk.internal=ALL-UNNAMED ^
--add-opens=java.management/javax.management=ALL-UNNAMED ^
--add-opens=java.management/javax.management.openmbean=ALL-UNNAMED ^
--add-opens=java.naming/com.sun.jndi.ldap=ALL-UNNAMED ^
--add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED ^
--add-opens=java.xml.crypto/org.jcp.xml.dsig.internal.dom=ALL-UNNAMED ^
--add-exports=java.desktop/sun.awt.image=ALL-UNNAMED ^
-Dmail.mime.splitlongparameters=false ^
-Dmail.mime.encodeparameters=true ^
-Dmail.mime.decodeparameters=true ^
-Dmail.mime.encodefilename=true ^
-Dmail.mime.decodefilename=true ^
-Dmail.mime.decodetext.strict=false"

info

If you encounter issues starting Tomcat, verify that the Java endorsed standards property is not set. The former property -Djava.endorsed.dirs=[tomcat root]\endorsed must be replaced by -Dignore.endorsed.dirs=[tomcat root]\endorsed.

Linux

Edit <TOMCAT_HOME>/bin/setenv.sh:

#!/bin/sh
export JAVA_OPTS="-Xms512m -Xmx1024m -XX:MaxNewSize=500m -XX:+UseG1GC -Dfile.encoding=UTF-8 \
--add-opens=java.base/java.lang=ALL-UNNAMED \
--add-opens=java.base/java.util=ALL-UNNAMED \
--add-opens=java.base/java.io=ALL-UNNAMED \
--add-opens=java.base/java.lang.reflect=ALL-UNNAMED \
--add-opens=java.base/jdk.internal=ALL-UNNAMED \
--add-opens=java.management/javax.management=ALL-UNNAMED \
--add-opens=java.management/javax.management.openmbean=ALL-UNNAMED \
--add-opens=java.naming/com.sun.jndi.ldap=ALL-UNNAMED \
--add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED \
--add-opens=java.xml.crypto/org.jcp.xml.dsig.internal.dom=ALL-UNNAMED \
--add-exports=java.desktop/sun.awt.image=ALL-UNNAMED \
-Dmail.mime.splitlongparameters=false \
-Dmail.mime.encodeparameters=true \
-Dmail.mime.decodeparameters=true \
-Dmail.mime.encodefilename=true \
-Dmail.mime.decodefilename=true \
-Dmail.mime.decodetext.strict=false"

Make the script executable:

chmod +x <TOMCAT_HOME>/bin/setenv.sh

JVM Parameters Explained

Memory Settings:

-Xms512m: Initial heap size (512 MB)
-Xmx1024m: Maximum heap size (1024 MB) - can be increased to 1536m for larger projects
-XX:MaxNewSize=500m: Maximum young generation size (should be approximately half of -Xmx)
-XX:+UseG1GC: Use G1 Garbage Collector (recommended for Java 17)

Java 9+ Module Access (Required for SAMO 9):

The --add-opens and --add-exports options are required for Java 9+ to allow deep reflection access to internal JDK packages that SAMO 9 needs:

Opens various java.base packages for reflection (lang, util, io, reflect)
Opens management and naming packages for JMX and LDAP operations
Opens RMI and XML crypto packages for remote operations and XML processing
Exports AWT image package for image processing capabilities

JavaMail Attachment Support:

These options enable support for email attachment filenames longer than 60 characters:

-Dmail.mime.splitlongparameters=false: Prevents splitting long parameters
-Dmail.mime.encodeparameters=true: Enables parameter encoding
-Dmail.mime.decodeparameters=true: Enables parameter decoding
-Dmail.mime.encodefilename=true: Enables filename encoding
-Dmail.mime.decodefilename=true: Enables filename decoding
-Dmail.mime.decodetext.strict=false: Allows non-strict text decoding

tip

For larger projects or higher load, you can increase the values:

-Xms1024m -Xmx2048m -XX:MaxNewSize=1024m

Monitor your application's memory usage and adjust accordingly. If you encounter java.lang.OutOfMemoryError: Java heap space, increase the -Xmx value.

6. Deploy WAR Files

Copy your SAMO 9 application WAR files to the Tomcat webapps directory:

copy samo-application.war <TOMCAT_HOME>\webapps\

The WAR files will be automatically deployed when Tomcat starts.

7. Install Tomcat as a Service (Recommended)

Open Command Prompt as Administrator
Navigate to <TOMCAT_HOME>\bin
Run the following command:

service.bat install [serviceName]

-- replace [serviceName] with your desired service name, e.g., Tomcat9

Configure the service by running:

tomcat9w.exe

This opens the Tomcat service configuration GUI where you can:

Set the service to start automatically
Configure JVM memory settings
Set the Java version to use

8. Install PSI Probe (Optional - Monitoring Tool)

PSI Probe is a web application monitoring tool for Tomcat.

Download probe.war from PSI Probe Releases
Copy the WAR file to <TOMCAT_HOME>\webapps\
Tomcat will automatically deploy it
Access it at http://localhost:9500/probe/ (adjust port as configured)
Login with the Tomcat admin credentials configured in step 1

Starting Tomcat

Using Scripts

<TOMCAT_HOME>\bin\startup.bat

Using Service

net start Tomcat9

Or use the Windows Services console.

Verification

Check Tomcat Status

Open a web browser and navigate to:
- Tomcat: http://localhost:9500/ (adjust port as configured)
- Manager App: http://localhost:9500/manager/html
- SAMO Application: http://localhost:9500/samo-application/ (adjust context path)

Check Logs

View the log file:

type <TOMCAT_HOME>\logs\catalina.out

Or monitor in real-time using PowerShell:

Get-Content <TOMCAT_HOME>\logs\catalina.out -Wait -Tail 50

Or just open the files located at <TOMCAT_HOME>\logs\ in a text editor.

Expected Log Output

Look for successful deployment messages such as:

INFO: Deployment of web application archive [samo-application.war] has finished in [X] ms
INFO: Server startup in [X] ms

Common Issues

Issue	Solution
Port already in use	Change the port in `server.xml` or stop the conflicting service
OutOfMemoryError	Increase JVM memory settings in `setenv.bat`
Database connection fails	Verify JDBC driver is in `lib/` and connection pool configuration is correct
WAR not deploying	Check `logs/catalina.out` for errors and verify WAR file integrity

Post-Deployment Configuration

After successful deployment, complete these essential steps to finalize your SAMO 9 installation.

1. Configure New Licenses

SAMO 9 requires license model version 40 and License Server 5.0.7 or higher.

Client applications require specific licenses in your license file:

License Type	Purpose
`SAMOWEBCLIENT.APPRUN`	Dashboard and category dashboard modules
`SAMOWEBCLIENT.DOCMAN`	Document Management System (DMS)
`SAMOWEBCLIENT.WORKPLAN`	Planning board functionality
`SAMOLIDSBROWSER.APPRUN`	SAMO LIDS Browser
`SAMOMOBILE.APPRUN`	LIDS Mobile (Android/iOS), Mobile WFM
`LIDSPBS.APPRUN`	LIDS Publishing Server

info

LIDS Edit and LIDS Explorer do not require new licenses.

To obtain new licenses:

Contact your SAMO license administrator
Request license model version 40 with the required application licenses
Install the new license file in your SAMO installation
Restart the application server

2. Synchronize Database

Update the SAMO system tables to version 9:

Navigate to SAMO Administration Console
Go to Database → Lids synchronization
Execute the creation of the changelist and synchronize the required database objects

info

The LIDS_DBCHANGELOG table column MD5SUM will be updated from 8: values to 9: values.

3. Synchronize Security Database

Update the security schema:

Navigate to SAMO Administration Console
Go to Database → Security synchronization
Execute the security database synchronization

4. Reindex Elasticsearch

Rebuild all Elasticsearch indexes:

Navigate to SAMO Administration Console
Go to Search
Select all indexes
Click Reindex Selected
Monitor the reindexing progress

warning

Reindexing can take considerable time depending on the size of your data. Plan accordingly and perform this during a maintenance window if possible.

6. Verify Application Functionality

After completing all configuration steps:

Test User Login: Verify users can authenticate
Test Database Connection: Confirm database operations work correctly
Test Elasticsearch: Verify search functionality
Check Application Logs: Review logs for any errors or warnings
Test Key Features: Validate core functionalities of the SAMO application

Additional Configuration

Set Up SSL/TLS (Recommended for Production)

For production environments, configure HTTPS:

Obtain an SSL certificate
Configure the HTTPS connector in <TOMCAT_HOME>\conf\server.xml
Update application URLs to use HTTPS
Configure Elasticsearch for SSL if needed

Configure Backup Strategy

Establish regular backups of:

Tomcat configuration files (<TOMCAT_HOME>/conf/)
Application data and logs
Database (using database-specific backup tools)
Elasticsearch data directory
License files

Overview​

Prerequisites​

Configuration Steps​

1. Configure Tomcat Users​

2. Configure Tomcat Port​

3. Add JDBC Drivers​

For Oracle Database​

For PostgreSQL Database​

4. Configure JDBC Connection Pool​

For Oracle Database​

For PostgreSQL Database​

Map JDBC Resource in Context​

5. Configure JVM Memory Settings​

Windows​

Linux​

JVM Parameters Explained​

6. Deploy WAR Files​

7. Install Tomcat as a Service (Recommended)​

8. Install PSI Probe (Optional - Monitoring Tool)​

Starting Tomcat​

Using Scripts​

Using Service​

Verification​

Check Tomcat Status​

Check Logs​

Expected Log Output​

Common Issues​

Post-Deployment Configuration​

1. Configure New Licenses​

2. Synchronize Database​

3. Synchronize Security Database​

4. Reindex Elasticsearch​

6. Verify Application Functionality​

Additional Configuration​

Set Up SSL/TLS (Recommended for Production)​

Configure Backup Strategy​

Additional Resources​

Overview

Prerequisites

Configuration Steps

1. Configure Tomcat Users

2. Configure Tomcat Port

3. Add JDBC Drivers

For Oracle Database

For PostgreSQL Database

4. Configure JDBC Connection Pool

For Oracle Database

For PostgreSQL Database

Map JDBC Resource in Context

5. Configure JVM Memory Settings

Windows

Linux

JVM Parameters Explained

6. Deploy WAR Files

7. Install Tomcat as a Service (Recommended)

8. Install PSI Probe (Optional - Monitoring Tool)

Starting Tomcat

Using Scripts

Using Service

Verification

Check Tomcat Status

Check Logs

Expected Log Output

Common Issues

Post-Deployment Configuration

1. Configure New Licenses

2. Synchronize Database

3. Synchronize Security Database

4. Reindex Elasticsearch

6. Verify Application Functionality

Additional Configuration

Set Up SSL/TLS (Recommended for Production)

Configure Backup Strategy

Additional Resources