The FlexDeploy™ Linux Installer Guide provides system requirements, required downloads and instructions for installing or upgrading FlexDeploy and its components.
About the automated Install/Migration tool
The flexdeployerinstaller.sh script is a new automated process that reduces customer efforts in installing or upgrading FlexDeploy, which will make staying up to date on FlexDeploy versions easier. The installer will take care of installation or upgrade of FlexDeploy with no manual intervention required. There is a configuration file which will need to be modified for your installation and then the installer can take over. There are three basic modes to the installer: 1) prerequisite checking with no installation or upgrade, 2) first time installation of FlexDeploy and 3) upgrading a current installation of FlexDeploy.
The apache-tomcat-flexdeploy folder will be cleaned up with each upgrade, so it is important not to place any supporting files in the apache-tomcat-flexdeploy folder. Place them in the flexdeploy home folder or another subfolder instead.
Versions / Release Notes
1.0.24 (12/4/2024)
FLEXDEPLOY-13468 - Corrupt zip files will no longer print error message "utils.sh: line 383: [: : integer expression expected"
FLEXDEPLOY-13673 - The installer now finds the correct database files to upgrade when upgrading to the newest 7.0 releases. Previously it was running the database files in an incorrect order / manner.
1.0.23 (10/31/2024)
FLEXDEPLOY-12786 - The installer now works with newer 8.0 and 9.0 versions of the docker image. Previously it failed with error message Failed to register in JMX: [javax.naming.NamingException: Unexpected exception resolving reference [Root exception is java.lang.NumberFormatException: For input string: "${MAX_ACTIVE_CONNECTIONS}"]
1.0.22 (10/10/2024)
FLEXDEPLOY-12825 - When you change the Java location in the installer’s config file, it now properly updates the java path in your setenvoverride.sh file.
1.0.21 (9/13/24)
FLEXDEPLOY-12704 - FlexDeploy 9.0 compatibility. FlexDeploy 9.0 must be installed with version 1.0.21 or higher. 1.0.21 also works with older versions of FlexDeploy.
1.0.20 (6/24/24)
FLEXDEPLOY-12432 - The Java Version check now works when _JAVA_OPTIONS are set.
1.0.19 (5/28/24)
FLEXDEPLOY-12312 - Resolved the 1.0.18 regression where installing with maintain set to 1 didn't start the new config files with the appropriate values.
1.0.18 (4/5/24)
FLEXDEPLOY-11883 - Resolved regression 11883 in installer 1.0.17 where the installer was requiring a JDK when a JRE may be sufficient.
FLEXDEPLOY-11617 - The installer now sets up influx more completely before starting FlexDeploy. This should reduce instances of customers upgrading and not getting influx setup because they cancel the installer before it completes.
FLEXDEPLOY-11887 - The installer no longer modifies the context or server xml files at all when maintain is set to 1. Previously, the database url, port, and password were updated, which caused issues for customers using Cyberark and other password management tools.
1.0.17 (3/12/24)
Known Issues
Installer 1.0.17 does not work with JRE. If you are using a JRE, do not use version 1.0.17.
FLEXDEPLOY-11081 - The installer now verifies that the Java version is at least 8.0.192.
FLEXDEPLOY-11236 - Add support for FlexDeploy 8.0+
Only FlexDeploy Installer 1.0.17 or later should be used with FlexDeploy 8.0+ 1.0.17 is also compatible with older FlexDeploy installs and upgrades.
The path of external jars (besides Oracle database driver jars) has changed from FLEXDEPLOY_HOME/apache-tomcat-flexdeploy/libext to FLEXDEPLOY_HOME/apiext.
This means that the update to 8.0 may require some changes to you custom CMS or ITS system code if you used a Java implementation.
1.0.16 (12/19/23)
FLEXDEPLOY-8076 - Add error handling to the oracle database backup functions so future errors should be more verbose.
1.0.15 (10/24/23)
FLEXDEPLOY-6232 - The installer now handles upgrading Postgres databases which were created to have different users instead of FD_ADMIN.
1.0.12 (8/10/23)
FLEXDEPLOY-9104 - The installer will now delete the artifacts backup file if the backup fails so that it will backup again the next time it is run. Previously the backup would be skipped on the second attempt.
1.0.11 (5/10/23)
FLEXDEPLOY-8052 - The installer will now clean up the apache-tomcat-flexdeploy/temp folder before backing up the apache-tomcat-flexdeploy folder.
1.0.10 (3/30/23)
FLEXDEPLOY-7606 - Allow using passwords with special characters for Oracle Databases. Now most special characters should work fine. The characters are not allowed Double Quote, Pipe, Forward Slash.
1.0.9 (3/25/23)
Update the Installer to be compatible with the Docker Image changes in 6.5.0.2 and 6.0.0.7.
Fix a variety of defects found when installing and upgrading FlexDeploy Docker Images.
FlexDeploy Docker images 6.0.07+ and 6.5.0.2+ must use installer version 1.0.9 or higher.
1.0.8 (3/10/23)
FLEXDEPLOY-7791 - Fix for installer failing with Exception Unable to get find a sql upgrade path from version... when there were no scripts to run in cases when no sql scripts were expected, for instance when upgrading a minor version.
FLEXDEPLOY-7585 - Fix for the checking and use of artifacts and working directories from the existing install during the upgrade process.
FLEXDEPLOY-7749 - Fix for to not check on latest version when it isn’t needed and add timeout to download commands so that the installer doesn’t hang when outbound traffic is dropped.
FLEXDEPLOY-7619 - Improved messages for the prompting of install / upgrade path
1.0.7 (3/3/23)
FLEXDEPLOY-7704 Fix issue with InfluxDB Retention days not being set.
FLEXDEPLOY-7731 Fix issue where the installer is not hiding database passwords properly in Installer version 1.0.6.
1.0.6 (2/24/2023)
FLEXDEPLOY-6426 Better checks for upgrade/install. Prompt after determining if the operation is an upgrade or install
FLEXDEPLOY-7590 Upgrade Oracle driver from 21.7 to 21.9 version. Resolves Oracle Bug 33312816 - java.lang.ClassCastException: class oracle.ucp.UniversalConnectionPoolException
Known issues:
FLEXDEPLOY-7731 The installer is not hiding database passwords properly in Installer version 1.0.6.
1.0.5 (2-13-2023)
FLEXDEPLOY-7504 Handle upgrading to and from versions of FlexDeploy with multiple digits in version number segments.
FLEXDEPLOY-6674 Ensure that influx won’t be installed twice
FLEXDEPLOY-7303 Fix for Oracle backup failing after prereqs worked.
FLEXDEPLOY-7419 Fail if apache-tomcat-flexdeploy is in the server.xml
FLEXDEPLOY-7322, FLEXDEPLOY-7380, FLEXDEPLOY-7478 Simplify configuration and make config more permanent
FLEXDEPLOY-7488 Don’t require the plugins folder as it wasn’t always there on older versions of FlexDeploy.
FLEXDEPLOY-7503 Handle multiple Tomcat or Influx installs on a single VM / host
1.0.4 (2/1/2023)
FLEXDEPLOY-6674 installer influx check may be wrong
Fix regression with Influx install from version 1.0.3.
FLEXDEPLOY-7304 Improved logging about backups
FLEXDEPLOY-7380 Remove the -n argument to make the install process easier and more clear. Now it checks the version available at Flexagon.com against the version that you have downloaded or requested in the Alternate Versions option.
1.0.3 (1/23/2023)
FLEXDEPLOY-7254 Installer - doesn't find pervious version when no upgrade was ever done
FLEXDEPLOY-6674 installer influx check may be wrong
Known issues:
Regression in 1.0.3 with Influx install bad choice for upgrading to 6.0+ from versions earlier than 6.0.
1.0.2 (1/19/2023)
Improved logic with potential database and influx issues
Overlay libext folder with provided Oracle driver if using Oracle Database, and then delete any older OJDBC drivers (for Java 6/7) to work with upgrades from older versions of FlexDeploy.
FLEXDEPLOY-6423 Installer should verify influx is stopped (like it does flexdeploy)
FLEXDEPLOY-6607 Influx - installation and setup options
FLEXDEPLOY-6674 installer influx check may be wrong
FLEXDEPLOY-7063 Installer fails to upgrade from older version that didn't have libext folder
1.0.1 (12/6/2022)
Improved logic with potential database and influx issues
Add checks for disk space
Changed the way that the database path is used for Oracle backups
1.0.0 (8-31-2022 through 11/14/2022)
Initial Release
Add support for Amazon RDS
better backup handling
Add configuration migration
Add aggregated error messages
This automated installer will handle
executing prerequisite checks to ensure the installation/upgrade will be successful
downloads of FlexDeploy software and influx database software if the VM has access to the Internet
installation of FlexDeploy for the first time
upgrading of FlexDeploy to a new version from version 5.2.0.5 or newer
backing up the current FlexDeploy installation, plugins, and optionally artifacts before upgrading
backing up the database before upgrading (optional)
creating or migrating the FlexDeploy database schemas
installation or configuration of the influx database which is used for reporting and dashboard data
This automated installer will not handle
downloads of software if the VM has no access to the Internet. In this case, the files need to be placed on the FlexDeploy server in locations specified by the installer
download of security wallets
upgrading from FlexDeploy versions older than 5.2.0.5
upgrading a Kubernetes installation
See FlexDeploy Architecture for architecture details.
Installer arguments
The Argument c must be the last argument specified.
The following arguments are available to be used:
-p run the installer in the prerequisite checking mode with no installation/upgrade occurring. The execution of this checking will not do anything with the current installation, so it can be run anytime. If the installer detects any issue(s), the issue will be reported to the logs and displayed on the screen. The prerequisites will also be run during the installation or upgrade process and may stop the process, which is why it is recommended to run this mode until there are no issues being reported. Each issue that is reported will have a possible resolution to the issue to assist you in resolving it. Some of the checks are: verify file system sizes to make sure all required directories have at least the minimum amount, flexdeployinstaller_config.txt file properties are set, java is at the right level, etc. Removing this argument will execute the install/upgrade.
-c/<path to>/flexdeployinstaller_config.txt points the installer to the flexdeployinstaller_config.txt file that contains the user configurations. The file should not be saved under the flexdeployinstaller folder. It is always required.
-s there are several passwords in the flexdeployinstaller_config.txt file and if a password field is left blank, in this scenario, a prompt for the password will happen (nothing will be stored) and the password is not shown on the screen, similar to other Linux password prompts. The -s option will show the password on the screen as you type.
-n Removed in version 1.0.4. Previously prevented Internet connections to download the necessary zip files.
-i skip the database backup. This can be done if you have an existing database backup.
-a skip the artifacts backup. This can be done if you have an existing backup of the artifacts folder or a snapshot of the VM.
-d Install as a docker container.
-w Specify that you are upgrading from a Weblogic install to a Tomcat install. Not compatible with the -d option.
Step by Step Guide to Using the installer
Step 0: System Requirements
See FlexDeploy System Requirements for details on software and hardware requirements
Step 1: Database Preparation (Installation Only)
Postgres
Install the Postgres binaries, and create a flexdeploy database. The automated installer will do the rest.
Either from the commandline with psql
createdb flexdeploy
or if you have sql access to the postgres database, and don’t have access to run createdb, you can connect to the postgres database and using sql
create database flexdeploy
Oracle
Install the Oracle Database binaries and find your jdbc connection string. The automated installer will create FD, FF, and FD_ADMIN schemas in the USERS tablespace.
Step 2: Get the Installer
Download flexdeployinstaller.zip and get it to the FlexDeploy server. You can wget it there directly if you have Internet access, or transfer the file from another machine.
wget -O flexdeployinstaller.zip https://flexagon.com/downloads/flexdeployinstaller
If you don’t have wget, and must use curl, use the -L argument like:
curl -L --max-redirs 5 https://flexagon.com/downloads/flexdeployinstaller --output flexdeployinstaller.zip
Once downloaded, select a directory (ex. /u01 or /u02) to unzip the flexdeployinstaller.zip.
Change directory to your selected directory and unzip the flexdeployinstaller.zip download. If this isn't the first time unzipping the installer, select [A]ll on the replacement question.
cd <FLEXDEPLOY_INSTALLER_HOME> unzip <path to flexdeployinstaller download>/flexdeployinstaller.zip
From the FLEXDEPLOY_INSTALLER_HOME directory, change directory to flexdeployinstaller_X.X.X to provide execution permission to the script.
Make sure the user that will run FlexDeploy has access to run the script. That user should execute the script.
cd flexdeployinstaller_X.X.X chmod +x flexdeployinstaller.sh
Step 3: Setup the Configuration File
Step 3.1: Save flexdeployinstaller_config.txt
This step is extremely important to preserve your configuration file from any potential installer upgrades. This step should only be done once: on a new installation or on a first time upgrade with this new process.
There is a configuration file (flexdeployinstaller_config.txt) that controls the actions of the installer. It is the most important file for the installer and needs to be saved to avoid being overlaid with any new flexdeployinstaller downloads as this would remove all of your entered configurations. There is a template file located in FLEXDEPLOY_INSTALLER_HOME/flexdeployinstaller. This template file must be copied to any other location, it could be placed in the FLEXDEPLOY_HOME and it would be safe from overlay and easier to find for the next upgrade.
cd <FLEXDEPLOY_INSTALLER_HOME>/flexdeployinstaller_X.X.X cp flexdeployinstaller_config.txt <FLEXDEPLOY_HOME>/ # this is one option to save but this can be saved to any other location. Just must be out of FLEXDEPLOY_INSTALLER_HOME/fledeployinstaller directory due to installer upgrades.
Step 3.2: Updating flexdeployinstaller_config.txt
Spaces are not supported in any directory and/or password values.
This step should only need to be done once, on a new installation or on a first time upgrade with this new process. Unless there is a change to any of the configuration properties.
Once copied, the file needs to be adjusted for your installation requirements (there are many default values in the file and they can stay defaulted). There are comments in the template file for each property but this guide will cover the properties that need to be updated.
FLEXDEPLOY_HOME is a key property as the flexdeployinstaller will determine based on this property if a current installation is running, make sure the directory location is correct (e.g. the FLEXDEPLOY_HOME would be the path up to, but not including, the apache-tomcat-flexdeploy directory. /u01/flexdeploy/apache-tomcat-flexdeploy would have a FLEXDEPLOY_HOME of /u01/flexdeploy.
Configuration Property | Required | Description |
|---|---|---|
FLEXDEPLOY_HOME | Yes | This is the directory location where FlexDeploy will be installed or is already installed, the default is /u01/flexdeploy. |
FLEXDEPLOY_JAVA_HOME | Yes | This is the path to Java JDK 8, it would be the path up to bin (not including bin) |
WORKING_DIRECTORY | No Defaults to ${FLEXDEPLOY_HOME}/application | This will be the directory location that FlexDeploy uses for temporary files to be transferred between the server and its endpoints. The default location is under FLEXDEPLOY_HOME and is named application. |
ARTIFACT_REPOSITORY_DIRECTORY | No Defaults to ${FLEXDEPLOY_HOME}/artifacts | this will be the directory location that FlexDeploy uses to store all build artifacts and retrieve deployment artifacts. The default location is under FLEXDEPLOY_HOME and is named artifacts. |
BACKUP_DATABASE_DIRECTORY | No | The directory where the database will be backed up to. This value is optional. If Oracle, this directory must already exist within the DBA_DIRECTORIES table and the DIRECTORY_PATH for the entry must exist on the file system on the Database Server. If Oracle, and BACKUP_DATABASE_DIRECTORY is blank, the DEFAULT data_pump directory is used if needed. If PostgreSQL, and BACKUP_DATABASE_DIRECTORY is provided, the database will be backed up to this local folder using the psql command, which must be available on this local host. If PostgreSQL, and BACKUP_DATABASE_DIRECTORY is blank, the database schemas will be backed up by cloning to another schema in the same database. |
SCM_TYPE | No | specify the primary SCM type that will be utilized. This isn’t part of the installation but there is a prerequisite check to make sure any necessary SCM clients are present. This check won’t stop the install, it is just informational. Not all SCM Types require clients. |
FLEXDEPLOY_DB_USER | Yes | The limited database user that will be used to run FlexDeploy |
FLEXDEPLOY_DB_PASSWORD | No | The password will be prompted if not specified. |
SYSTEM_DB_USER | Yes | Usually set to system for Oracle and postgres for Postgres. This user will create and update the schema definitions |
SYSTEM_DB_PASSWORD | No | This password is required to create and update schema definitions The password will be prompted if not specified. |
FLEXDEPLOY_PORT | No | Defaults to 8000 for standard installs, 8004 for Docker installs. |
MAINTAIN_EXISTING_CONTEXT_FILE | No Defaults to 0 | If 0, then the installation process will use the newly downloaded context.xml file and adjust the properties accordingly. If 1, then the installation process will save the existing context.xml and replace it after the upgrade so there are no changes to it. Set to 1 if you have changes to the context.xml file that you wish to maintain such as using a password manager for your database password in context.xml. |
MAINTAIN_EXISTING_SERVER_FILE | No Defaults to 0 | If 0, then the installation process will use the newly downloaded server.xml file and adjust the properties accordingly. If 1, then the installation process will save the existing server.xml and replace it after the upgrade so there are no changes to it. |
INFLUX_DB_DIRECTORY | No Defaults to ${FLEXDEPLOY_HOME}/influxdb | Deprecated. Don’t use. |
INFLUX_DB_URL | No Defaults to http://localhost:8086 | Deprecated. Don’t use. |
INFLUX_DB_BUCKET | No Defaults to flexbucket | Deprecated. Don’t use. |
INFLUX_DB_ORG | No Defaults to flexdeploy | Deprecated. Don’t use. |
INFLUX_DB_USER | No Defaults to flexuser | Deprecated. Don’t use. |
INFLUX_DB_PASSWORD | Yes | Only used on the first install / upgrade to 6.0+. |
INFLUX_DB_TOKEN | Yes | This token is required for FlexDeploy to communicate with the influx database. Enter any arbitrary string that will be saved in FlexDeploy and used for the influxdb installation. Only used on the first install / upgrade to 6.0+. |
ALTERNATE_FLEXDEPLOY_SOFTWARE_VERSION | No | Filling in this property will tell the installation process that you don't want the latest version of the software, if the process can get through to the internet to auto download the software. Must be a valid FlexDeploy version e.g. 6.5.0.0 e.g. 5.7.0.12 |
DATABASE_URL | Yes | Adjust the appropriate connection string for the FlexDeploy database, Oracle or Postgres. Verify that your DATABASE_URL line isn’t commented out (# at the beginning of the line) and that all other DATABASE_URL lines are commented out. Several examples are listed in the config file. |
CONTAINER_NAME | No Only used for Docker Defaults to flexdeploy | If installing FlexDeploy through Docker you can set the name of the container that will be created by editing the variable below. Defaults to 'flexdeploy' |
At the completion of updating and saving the flexdeployinstaller_config.txt file, run the following command at any time, to source in the properties from the flexdeployinstaller_config.txt file and make them available to be used for navigation.
cd <FLEXDEPLOY_INSTALLER_HOME>/flexdeployinstaller_X.X.X source ./setEnv.sh <path to saved flexdeployinstaller_config.txt>
Step 4: Download any Additional Software
If you don’t have Internet access, all software downloads noted below must reside on the FlexDeploy VM before you can install or migrate. The prerequisite checks will validate if Internet access to the needed locations is available.
If you have Internet access, but choose to place the files manually.
Step 4.1: FlexDeploy software (conditional)
If your FlexDeploy VM has access to the Internet, the flexdeployinstaller.sh will pull the latest FlexDeploy software from the Flexagon Support Site and no manual download will be needed.
If your FlexDeploy VM doesn't have access to the Internet, the FlexDeploy software can be downloaded from the Flexagon Support Site and the downloaded zip file must be saved to FLEXDEPLOY_INSTALLER_HOME/downloads/software (don't unzip).
cp /path to FlexDeploy software download/Tomcat_Complete-*.zip ${FLEXDEPLOY_INSTALLER_HOME}/downloads/software
Step 4.2: Influx database (conditional)
If you are installing/upgrading FlexDeploy with version 6.0+ and your FlexDeploy VM has access to the Internet, the flexdeployinstaller.sh will pull the required version of the software and client from the influx data website.
If you are installing/upgrading FlexDeploy with version 6.0+ and your FlexDeploy VM doesn't have access to the Internet, the software and the client must be downloaded from the influx data website using the embedded links. The 2 downloaded gzip files must be saved to FLEXDEPLOY_INSTALLER_HOME/downloads/influxdb (don't extract them). This only needs to be downloaded once.
cp /path to influx database download/influxdb2*tar.gz ${FLEXDEPLOY_INSTALLER_HOME}/downloads/influxdb
Step 5: Check the Prerequisites
Step 5.1: Execution
Now that the downloads that are needed are completed and the flexdeployinstaller_config.txt file is updated, the prerequisite checks should be executed outside of the install/upgrade process. The prerequisite checking process is designed to be run multiple times until all reported issues are resolved. Any issue that is found will be displayed on the screen in the form of the issue and the potential resolution.
Run the installer as the user that you want to own and execute the FlexDeploy Tomcat process.
cd ${FLEXDEPLOY_INSTALLER_HOME}/flexdeployinstaller_X.X.X
./flexdeployinstaller.sh -p -c <path to saved config file>/flexdeployinstaller_config.txt
08/26/2022 12:01:20 PM Error occurred
############################### ISSUE 105 ##########################################################
ISSUE: The FLEXDEPLOY_JAVA_HOME configuration property is not set. This must be set and
must meet the FlexDeploy requirements of at least 1.8 but not greater than 1.8.
RESOLUTION: Please update the flexdeployinstaller_config.txt file for the installation.
####################################################################################################
Step 5.2: Resolution
With the list of issues on the screen, and in the logs (FLEXDEPLOY_HOME/upgrade/logs), each issue must be resolved before continuing. Each issue will provide some level of resolution that can assist in clearing up the given issue.
If there are any issues that are not resolved, the next step will fail as it will call the prerequisites also. The prerequisites need to be run on every execution but could stop the process, thus running the prerequisites independently will ensure a clean install/upgrade.
Step 6: Complete the Installation/Upgrade
Now that we have everything validated from a prerequisite check, we can start the installer process. As stated earlier, the same process will handle the installation and any upgrade. The installer will use the flexdeployinstaller_config.txt properties to detect if there is a current installation. Start the installer process by running the below command.
cd ${FLEXDEPLOY_INSTALLER_HOME}/flexdeployinstaller_X.X.X
./flexdeployinstaller.sh -c <path to saved config file>/flexdeployinstaller_config.txt
The process will take a few minutes, longer if the downloads haven’t been performed ahead of time.
Additional Information
Continuing an Upgrade after Database Migration Failure
When executing an upgrade with the installer you may run into a failure during the Database Migration scripts. In that case you will need to manually resolve the issue that was encountered and continue the specific migration script to completion. The execution logs for the upgrade will contain information on the last successfully run SQL statement as well as the error that occurred during execution. Once the issue is resolved we will find the location of the last successful SQL statement in the migration script and execute the remaining SQL statements one by one.
Below is an example of a log file where an exception occurred while upgrading from v5.7.0.2 to v6.0.0.0. As you can see we ran into an error when creating the FD.USER_FAVORITE table and the last successful statement was delete FROM FD.REL_SNAPSHOT_VERSION where REQUEST_ALL_FILES='Y' AND PACKAGE_NAME IS NOT NULL.
10/18/2022 14:47:19 Exception occured while executing /u01/flexdeployinstaller_1.0.1/../temp/software/database/oracle/upgrade/v5.7.0.2-to-v6.0.0.0/migration.sql 10/18/2022 14:47:19 Last successful statement executed: delete FROM FD.REL_SNAPSHOT_VERSION where REQUEST_ALL_FILES='Y' AND PACKAGE_NAME IS NOT NULL 10/18/2022 14:47:19 Script execution failed on statement: CREATE TABLE FD.USER_FAVORITE
After fixing the issue we encountered while creating the FD.USER_FAVORITE table we will find the location of the last successfully executed statement in the migration script. For this specific example we can see that the last successful statement is on line 4. We will then execute the remaining SQL statements (Line 7 and beyond) one by one until all SQL statements have been executed for this migration script.
-- 6.0.0.0
insert into FD.FD_FLEXDEPLOY_VERSION values('6.0.0.0',null,current_date,'SYSTEM',current_date,'SYSTEM',1);
delete FROM FD.REL_SNAPSHOT_VERSION where REQUEST_ALL_FILES='Y' AND PACKAGE_NAME IS NOT NULL;
-- user fav - start
CREATE TABLE FD.USER_FAVORITE
(
...
Finally, we can then attempt the upgrade again through the installer by following the instructions.