Installing FlexDeploy on existing Tomcat

These instructions are for installing FlexDeploy on an existing Tomcat server.  If you are installing a new server, see Installing FlexDeploy with included Tomcat for a simplified installation which includes the Tomcat 8.5.11 server.  If you wish to use an existing Tomcat server, or to use a different version of Tomcat, please continue with this installation.

Requirements 

Tomcat Setup

If FlexDeploy is being installed for first time, setup Tomcat server and a Data Source as explained in following steps. If only updating new war file, skip to Installing WAR Installation.

Install library jar files to Tomcat lib

Some jars are needed to support running an ADF application on Tomcat. Please download the following and put in the lib folder inside where you downloaded Tomcat.

    • Extract zip files in flat structure using unzip -j (works on Windows and UNIX)
      • cd <TOMCAT_HOME>/lib
      • unzip -j <path to temp folder>/adf-essentials.zip
      • unzip -j <path to temp folder>/adf-essentials-client-ear.zip
    • You should see a large number of jars now in the <TOMCAT_HOME>/lib folder.
    • ADF Essentials comes with the JDBC driver for Oracle 11g database (ojdbc6dms.jar).  If you are using Oracle 12c database, you can download the driver from the Oracle Technology Network site.
      • Oracle 12c drivers

        If adding another JDBC driver, be sure to remove the default one which comes with the ADF Essentials libraries (ojdbc6dms.jar).  If you leave multiple JDBC drivers in the lib folder, you could encounter the following exception on startup:

        java.lang.SecurityException: sealing violation: package oracle.jdbc is sealed

                        at java.net.URLClassLoader.getAndVerifyPackage(Unknown Source)

                        at java.net.URLClassLoader.definePackageInternal(Unknown Source)

                        at java.net.URLClassLoader.defineClass(Unknown Source)

                        at java.net.URLClassLoader.access$100(Unknown Source)

                        at java.net.URLClassLoader$1.run(Unknown Source)

  • Copy following jar files from Tomcat_Complete.zip/apache-tomcat-flexdeploy/lib folder and place them in <TOMCAT_HOME>/lib.
    • jta-1.1.jar
    • jackson-core-lgpl-1.9.13.jar
    • jersey-bundle-1.18.jar
    • asm-3.3.1.jar
    • mail-1.4.7.jar
    • ant-salesforce.jar - If you will be using the Salesforce integration.
    • If using PostgreSQL, also copy postgresql-42.2.5.jre7.jar
    • If using MySQL, also copy mysql-connector-java-8.0.13.jar

Configure context.xml

Open context.xml for editing. It is located in the <TOMCAT_HOME>/conf folder. Update context.xml depending on your database, see examples below. Replace URL and Password with the actual values.

Example JDBC URL (CONNECT_STRING)

  • Oracle
    • Localhost XE connection will look like this. jdbc:oracle:thin:@localhost:1521:XE
    • SID based JDBC URL Syntax - jdbc:oracle:thin:@HOSTNAME:PORT:SID
    • Service Name based JDBC URL Syntax - jdbc:oracle:thin:@//HOSTNAME:PORT/SERVICENAME
Oracle
<Resource name="jdbc/flexdbDS" auth="Container"
    type="oracle.jdbc.pool.OracleDataSource"
    factory="oracle.jdbc.pool.OracleDataSourceFactory"
    
    url="**CONNECT_STRING**"
    user="fd_admin"
    password="**FD_ADMIN_PASSWORD**"
    
    connectionCachingEnabled="true"
    connectionCacheProperties="{InitialLimit=0, MinLimit=0, MaxLimit=100, ConnectionWaitTimeout=60, InactivityTimeout=60, AbandonedConnectionTimeout=60, PropertyCheckInterval=30}"
    
    validationQuery="select 1 from dual"
    testOnBorrow="true"
    
    useLocalSessionState="true"
    defaultAutoCommit="false"/>
Postgresql
<Resource name="jdbc/flexdbDS" auth="Container"
    type="javax.sql.DataSource"
    factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
    driverClassName="org.postgresql.Driver"
    
    url="**CONNECT_STRING**"
    username="fd_admin"
    password="**FD_ADMIN_PASSWORD**"
    
    maxTotal="100"
    maxIdle="20"
    
    validationQuery="select 1"
    testOnBorrow="true"
    
    defaultTransactionIsolation="READ_COMMITTED"
    useLocalSessionState="true"
    defaultAutoCommit="false"/>
MySQL
<Resource name="jdbc/flexdbDS" auth="Container"
    type="javax.sql.DataSource"
    factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
    driverClassName="com.mysql.jdbc.Driver"
    
    url="**CONNECT_STRING**"
    username="fd_admin"
    password="**FD_ADMIN_PASSWORD**"
    
    maxTotal="100"
    maxIdle="10"
    initialSize="10"
    
    validationQuery="SELECT 1"
    testOnBorrow="true"
    
    defaultTransactionIsolation="READ_COMMITTED"
    useLocalSessionState="true"
    defaultAutoCommit="false"/>

Configure Tomcat Environment

Windows

Create file setenv.bat in the <TOMCAT_HOME>/bin folder. Edit the file to have following lines. Update location of JAVA_HOME as appropriate.

setenv.bat
set JAVA_HOME=C:/installs/Java/jdk1.8.0_121
set CATALINA_OPTS=%CATALINA_OPTS% -verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xms1024m -Xmx4096m -Xloggc:%CATALINA_BASE%/logs/gc.log -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=5 -XX:GCLogFileSize=2M -Doracle.mds.cache=simple -Dorg.apache.el.parser.SKIP_IDENTIFIER_CHECK=true -Dflexagon.fd.repository.root=/opt/flexdeploy/repository -Dflexagon.fd.install.root=/opt/flexdeploy/application -Djava.awt.headless=true

Unix

Create file setenv.sh in the <TOMCAT_HOME>/bin folder. Edit the file to have following line. Update location of JAVA_HOME as appropriate.

setenv.sh
JAVA_HOME=/usr/jdk1.8.0_60
CATALINA_OPTS='-verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xms1024m -Xmx4096m -Xloggc:$CATALINA_BASE/logs/gc-%t.log -Doracle.mds.cache=simple -Dorg.apache.el.parser.SKIP_IDENTIFIER_CHECK=true -Dflexagon.fd.repository.root=/opt/flexdeploy/repository -Dflexagon.fd.install.root=/opt/flexdeploy/application -Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom'

Please make sure to modify the arguments for Server working directory (-Dflexagon.fd.install.root) and Artifacts repository (-Dflexagon.fd.repository.root) as per your installation. Be careful in copying details from browser due to potential character changes.

Setup Logger Configuration

Follow these steps to implement custom format for FlexDeploy logs in Tomcat. All necessary files should be available in Tomcat_Complete.zip.

  • Copy Tomcat_Complete.zip/apache-tomcat-flexdeploy/bin/FDLogFormatter.jar to <Tomcat Home>/bin folder.
  • For Windows
    • Update <Tomcat Home>/bin/setenv.bat file, add following on first line.

      set CLASSPATH=%CLASSPATH%;%CATALINA_HOME%\bin\FDLogFormatter.jar
  • For Linux
    • Update <Tomcat Home/bin/setenv.sh file, add following on first line.

      export CLASSPATH=$CLASSPATH:$CATALINA_HOME/bin/FDLogFormatter.jar
  • Copy Tomcat_Complete.zip/apache-tomcat-flexdeploy/conf/logging.properties file to <Tomcat Home>/conf folder. You should take back up of existing logging.properties file. This is configured to have 10 backups each 10MB, you can adjust it as appropriate.

Copy Additional Libraries

From the FlexDeploy Tomcat distribution, copy /apache-tomcat-flexdeploy/lib/FlexDeployAPI.jar into <TOMCAT_HOME>/lib.

FlexDeploy Application Setup

Install WAR

  • Copy Tomcat_Complete.zip/apache-tomcat-flexdeploy/webapps/flexdeploy.war file into <TOMCAT_HOME>/webapps folder.

Copy Plugins

At startup, FlexDeploy will upload and activate all the plugins. Perform these steps for auto upload of plugins.

  • Create a folder called plugins inside your FlexDeploy working directory.
  • Copy all the jar files from <Tomcat Complete Zip>/application/plugins to FLEXDEPLOY_WORKING_DIR/plugins.

Start Tomcat

  • Unix
    • cd <tomcat install>/bin
    • ./startup.sh
  • Windows
    • Double click startup.bat in the <tomcat install>\bin folder.

Launch Application

  • Launch FlexDeploy in your browser
    • http://<hostname>:<port>/flexdeploy
    • You will need to complete Initial Registration process, where you will create admin user for login.
  • Now that you have installed FlexDeploy, let's get start with configuration. You can do this in matter of minutes by using Blueprints concept, which is very simple configuration wizard for most common usecases.
The following macros are not currently supported in the footer:
  • style