Upgrading to Ephesoft Transact 2019.1 – Single-Server – Linux

System Upgrade Information

This document provides the guidelines, best practices, and steps involved in upgrading to Ephesoft Transact version 2019.1 from version 4.5.x.x.

Note: If performing an upgrade to Ephesoft Transact 2019.1 from any version other than Ephesoft Transact 4.5.x.x, it may be necessary to upgrade the server or servers to a supported operating system before performing the upgrade to Ephesoft Transact 2019.1. Also, a new license will be required if upgrading to version 2019.1 or 4.5.x.x from any release prior to version 4.5.x.x.

Upgrades are an essential part of a software solution and a major event in their life cycle. Upgrades are part of the original “total cost of ownership” and vital to increasing total ROI, particularly with a rapidly evolving software solution like Ephesoft Transact.

This document explains an upgrade approach that provides additional risk management and protection from downtime during an Ephesoft Transact upgrade. In an incremental, parallel upgrade, the previous version remains available in a known working configuration. If a problem occurs, users can easily revert to the previous version. The goal of an incremental, parallel Ephesoft Transact upgrade is to reduce risk by ensuring that operations continue without interruption during the upgrade process.

Risk of Traditional Upgrades

Most upgrades must occur in a very limited timeframe. At the end of a shift, critical systems are taken off line to remove legacy versions and deploy new versions as a lengthy series of partially practiced, often undocumented, and difficult to verify configuration steps. This approach is very optimistic, hoping that all integrated components will work correctly in the next production window. If anything goes wrong, a significant negative impact on the business can result.

Incremental or Parallel Upgrades

Ephesoft is documenting, recommending and supporting an incremental, parallel upgrade process. This powerful concept entails upgrading only a few components of a solution at a time, reducing the number and scope of risks.

Functionality During an Upgrade

Ephesoft Transact is a thin client solution. One or more servers provide support for all users (operators and administrators) via a web browser. During the upgrade, Ephesoft Transact will be temporarily unavailable. As such, the timing of the upgrade must be considered. As no thick clients exists, the upgrade of the Ephesoft Transact application server(s) is the only concern.

If an Ephesoft Transact cluster (two or more Ephesoft Transact servers in one environment) is being used, all servers must be on the same version.

Also, the SharedFolders on one server must be configured in Ephesoft Transact 2019.1 prior to configuring SharedFolders during the upgrade to release 2019.1 on additional servers.

API Support

API calls that are deprecated will be noted in the release notes for each version of Ephesoft Transact. Please check the release notes before installing any upgrade.

Custom Script Support

A customer or Ephesoft can develop any customization using custom scripts for Ephesoft Transact 2019.1.

  • Ephesoft provides support only for custom scripts developed by Ephesoft for the appropriate version of Ephesoft Transact.
  • Ephesoft does not provide support for such scripts in subsequent releases.
  • If you have custom scripts developed by someone other than the Ephesoft, please make sure to test these scripts, as we do not provide Support unless otherwise agreed.

Before upgrading to Ephesoft Transact 2019.1, Ephesoft highly recommends testing any custom scripts in a test or development environment before upgrading your production environment.

If you need any assistance with custom script creation, upgrading your environment(s) or a consulting session, please contact your Ephesoft Sales Manager.

System Requirements and Platform Support

Please reference the following resources for the latest information about Ephesoft Transact 2019.1, supported operating systems, supported databases and more:

Note: If performing an upgrade to Ephesoft Transact 2019.1 from any version other than Ephesoft Transact 4.5.x.x, it may be necessary to upgrade the server or servers to a supported operating system before performing the upgrade to Ephesoft Transact 2019.1.

Testing the Upgrade

Ephesoft recommends testing any software upgrade with an existing application before moving the upgrade into production. This is an essential approach to the success of the upgrade process. This approach is particularly important if the software being upgraded is integrated with any other applications, systems, or workflows.

Please ensure that you have a complete backup of the system prior to any upgrade.

Prerequisites

Please complete the following steps prior to starting the upgrade:

1. Upgrade any necessary hardware or software on the current servers. Refer to System Requirements and Platform Support for additional information.

2. Complete all in-flight batches.

3. Perform a complete backup of the databases (main Ephesoft database and reporting database).

4. Back up all batch classes (export from Batch Class Management).

5. Back up the Ephesoft SharedFolder directory.

6. Run all reports and ensure they are complete and in synch.

7. Document Tomcat memory settings (if changed from default) so that they can be restored after the upgrade. For additional information, please refer to the following article:

  • Configuring Tomcat Memory Settings

https://ephesoft.com/docs/ephesoft-optimal-memory-settings/

8. Verify registry information with the following command:

/etc/.java/.systemPrefs/com/ephesoft/license/core/annotation

The path for sharedFolderDir must match the SharedFolders path currently being used by Ephesoft Transact.

The Server.xml and registry DB entries must match before starting an upgrade. Check the registry settings to ensure proper configuration for your database upgrade.

9. Edit the SelectedDb entry in the registry so that it reflects the correct database type being used.

  • Enter the appropriate number in the Value data field in the registry setting to match the database type number that you are using.
  • The options are as follows:
    • MariaDB Server (MySQL compatible)
    • Oracle Database Server

Performing the Upgrade

Complete the following steps to upgrade to Ephesoft Transact 2019.1 on Linux, after meeting all prerequisites described earlier in this document.

Note: If upgrading to Ephesoft Transact version 2019.1 from a release prior to version 4.5.x.x, it is important to upgrade to a supported operating system, and a new license will be required. For more information, refer to System Requirements and Platform Support.

1. Launch the update by running the proper command for your environment:

  • RHEL/CentOS:
    • sudo yum update
  • Ubuntu:
    • sudo apt-get update && sudo apt-get upgrade
Running the update

 

2. Make a directory for the Ephesoft installation files. This example uses the following directory:

  • /home/user/Downloads/Ephesoft
Creating a directory for the installation files

 

3. Download the zip file for the installer. Extract the files from the Ephesoft_linux.zip to the following folder:

  • unzip Ephesoft_linux.zip -d ~/Downloads/Ephesoft

If unzip is not installed, use one of these commands:

  • RHEL/CentOS: sudo yum install unzip
  • Ubuntu: sudo apt-get install unzip
Downloading the zip file for the installer

 

Viewing extraction results

 

4. Navigate to the directory where you have unzipped the Ephesoft installer.

  • cd ~/Downloads/Ephesoft
Navigating to the installer directory

 

5. Make all files in the directory executable using this command:

  • sudo chmod -R 777 *
Making all files in this directory executable

 

6. Change to root user for installation with the following commands:

su root

Enter password

If you have not set a root password, do that now.

Always talk to your system administrator before doing this.

sudo passwd

Enter password twice

7. Launch the installer with the following command:

  • ./install
Launching the installer

 

The installer will ask if your distribution is RHEL, CENTOS or Ubuntu.

Press Enter if it is correct. (This demo uses RHEL so it is correct.)

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-14_16_22-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Entering the Linux version

 

8. Enter the path where you would like to install Ephesoft Transact:

  • /opt is the common directory in which to install third party applications.
  • /opt is the Ephesoft recommendation.

Never install Ephesoft in the /home directory for a user or in the /root, /bin, /etc, /sbin, /usr, or /boot directories.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-14_19_05-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Setting the installation directory

 

9. Ephesoft Transact moves the installation files to the target directory.

The installer then asks if the user wants to use an existing SharedFolders directory. This is for multi-server installations and requires that SharedFolders already be installed from another server installation of the same version of Ephesoft Transact.

The installer now asks where to install SharedFolders. If the user would like to define another folder, answer y here and the user will be asked where to have it installed. Otherwise, leave n and click Enter.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-14_20_33-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Installing the SharedFolders

 

10. Ephesoft for Linux is only available with MySQL instances. The installer now prompts you about whether you would like to install a new MySQL instance. Use the default setting here unless this is a multi-server installation.

You will be asked which database port to use.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-14_44_40-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Setting the database port

 

11. For a standard installation, use the default port provided by the system. You will be asked to enter a password for the root user. This is for the root user of the MySQL instance.

  • Write this down as it cannot be changed after created.
  • You will be asked for the database names: ephesoft, report and report_archive.

12. Press Enter through all of these and do not change the names of the databases.

  • The installer will check to see if you want to change any of the MySQL settings.

13. Press Enter to use the default value of n.

  • Make sure to only include alphanumeric characters while writing the name of Application DB when using the existing database instance.
  • Avoid the use of special characters, except _ .
https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-14_46_31-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Entering database and user information

 

14. Select the appropriate Authentication Mode and desired application protocol.

15. Select the appropriate User Connectivity Settings.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-14_50_55-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Configuring the User Connection settings

 

16. Enter your Ephesoft registration information.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-14_52_22-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Entering registration information

 

The Installer will install the MySQL instance.

The installer then continues to install other applications used by Ephesoft such as LibreOffice, Ghostscript, ImageMagick.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-14_58_06-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Installing components of Ephesoft Transact — illustration 1

 

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-15_12_40-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Installing components of Ephesoft Transact — illustration 2

 

The installer continues to install applications used by Ephesoft, such as Nuance and Poco.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-15_20_33-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Installing components of Ephesoft Transact — illustration 3

 

The installer displays the message Ephesoft installed successfully once the installer has completed all processes.

Ephesoft has now been installed on your server.

Perform the following steps to apply a license to your Ephesoft installation before starting Ephesoft for the first time.

Licensing the Upgrade from Version 4.5.x.x to Version 2019.1

This topic describes how to upgrade to Ephesoft Transact 2019.1 from Ephesoft Transact 4.5.x.x.

Note: If upgrading to Ephesoft Transact 2019.1 or 4.5.x.x from a release prior to version 4.5.x.x, a new license will be required. Also, additional steps must be performed for licensing. In this case, contact Ephesoft Technical Support to verify the documentation to be used for your upgrade and licensing activity.

For additional information about licensing Ephesoft Transact 2019.1, refer to the following article:

  • Licensing Ephesoft Transact 2019.1

https://ephesoft.com/docs/2019-1/installing-upgrading/licensing/licensing-licensing-ephesoft-transact-2019-1/

Perform the following steps to license the upgrade to Ephesoft Transact 2019.1.

1. Navigate to /opt/Ephesoft/Dependencies/licensing and send the details and Properties file to licenses@ephesoft.com.

  • Be sure to note that your installation is a Linux installation and advise the Ephesoft licensing team of the number of CPU cores on the server.
  • If you are not sure how many CPU cores your server has, type nproc in the terminal and it will display the number of cores as an output.
Using the nproc command to display the number of cores

 

2. The Ephesoft licensing team will send you a file named ephesoft.lic. Place this file in the following folder:

/opt/Ephesoft/Dependencies/license-util/ephesoft-license-installer

Placing the ephesoft.lic file into the target folder

 

3. While you are still root user and the ephesoft.lic file has been copied to the correct folder, run the following command in the folder mentioned above.

  • ./install-license.sh

To ensure that the license was installed correctly, we encourage you to run this command a second time.

  • ./install-license.sh
https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-15_31_50-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Running the ./install-license.sh twice

 

4. Now that the license has been installed, you can change back to your normal user account instead of the root user. Use the su -username command. This command also puts you back in the home directory for your user account.

5. You can start Ephesoft for the first time. Run the following command to start Ephesoft Transact.

  • sudo /opt/Ephesoft/JavaAppServer/bin/startup.sh

This command must be run with sudo rights.

Ephesoft is now started.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-15_33_29-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Starting Ephesoft Transact

 

6. Open a web browser on the workstation and browse to http://localhost:8080/dcma/home.html. This brings the user to the home menu for Ephesoft.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-15_52_47-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Home screen for Ephesoft Transact

 

7. Click any option from under the Administrator or Operator icon to display the login screen. The username is ephesoft and the password is demo.

https://ephesoft.com/docs/wp-content/uploads/sites/11/2019/01/2019-01-29-15_53_57-LinuxOracle-Running-Oracle-VM-VirtualBox.png
Ephesoft Transact 2019.1 Login Screen

 

Troubleshooting

  • If the Ephesoft installer stops with an error during any step of the installation process. Please send the following files to Ephesoft Support at tickets@ephesoft.com and include the distribution and version of Linux on which you are installing.
    • /var/log/install-ephesoft.log
    • /etc/Ephesoft/ephesoft.conf

(Only the root user has access to this folder. If file does not exist, send only first file.)

  • If you do not have root or sudo permissions on the server, please contact your system administrator for permissions and/or instructions.
  • If installing the SharedFolders directory on a remote server/NAS/SAN, please advise your system administrator to mount the share locally to your server and use the path they provide during the install. You can contact Ephesoft Support for assistance if you run into issues with this. Persistent mount of the share on the local server will be necessary for Ephesoft to function.

Installation Notes

  • Although Ephesoft Transact may support other Ubuntu and RHEL based distributions, we have not tested them all. Please contact support at tickets@ephesoft.com before attempting an installation so that we can advise you of any changes that may need to be made during the install process.
  • In Ubuntu, Ephesoft installation will turn the Firewall(ufw) on after install. At the end of the install, if you want ufw turned off, please remember to turn it off again with the command sudo ufw disable.
  • When shutting down the Ephesoft service in Ubuntu, use the command sudo /opt/Ephesoft/JavaAppServer/bin/shutdown.sh.
  • After you install Ephesoft, before you run Ephesoft for the first time, run the following commands(dos2unix is installed by Ephesoft):

Sudo dos2unix /opt/Ephesoft/JavaAppServer/conf/*

Sudo dos2unix /opt/Ephesoft/JavaAppServer/bin/*

Post-Upgrade Health Check

Use WinMergeto compare settings from [backed up pre-upgrade] and [post-upgrade] META-INF config *.properties files and config *.xml files.

Download WinMergeto from the following location:

http://winmerge.org/

Expect new line items in the config files if upgrading to a new major version of Ephesoft Transact.

Adjust customized settings as found.

  • Examples of lines you would not change would be completely new config lines that exist in new config files but not in old ones. These configuration files are primarily the *.properties files that are found in:

<Ephesoft Installation Directory>:\Ephesoft\Application\WEB-INF\classes\META-INF\

  • An example of acceptable differences between files would be changes to paths of the database, SharedFolder, or computer names (if you moved these parts of the environment to various locations).
  • An example of a configuration that may have changed is the imagemagick.properties file, which contains different compression settings for TIF and PDF files. If these were previously changed from the default values, they may have reverted back to the default settings.
  • In some config files, such as user-connectivity properties, config entries that used to have separate lines for LDAP and AD may have consolidated config lines that are now used for both. In these cases, careful consideration should be made before making changes.
  • For clustered environments, closely check the workflow and reporting properties files against the backup files for consistency across cron expressions.
  • Restore any custom Tomcat memory settings.

Completing the Upgrade

Once all upgrade steps have been completed and the latest version of Ephesoft Transact is successfully running, Ephesoft recommends making a complete backup of the latest version of Ephesoft Transact.