...

The database installation process differs between version 10 and version 11.

Please follow the relevant instructions below.

Expand

title	Version 11 - Show Details

Version 11

These instructions are written assuming configuration will be in the local.properties file. However, this isn't the only place that configuration options can be configured.

Table of Contents

include	Step.*
exclude	Step-.*

Configuration Files

Insert excerpt

	Server Configuration Properties
	Server Configuration Properties
name	ConfigurationFiles
nopanel	true

Step 1 Shutdown Tomcat

If Tomcat is currently running then shut it down before proceeding with the following steps.

Step 2 Copy the PhixFlow Webapp into Tomcat

To install the PhixFlow web application into Tomcat:

Copy $RELEASE/webapps/phixflow to $TOMCAT/webapps/phixflow

Configure the Webapp

A number of configuration files must be copied from supplied templates and configured.

...

Linux

Make sure that the file ownership is set correctly for the installed webapp(s):

Code Block
sudo chown -R tomcat:tomcat $TOMCAT/webapps/phixflow

Step 3 Create Configuration Files

Copy the following example configuration files and, where required, update them for your system.

Info
The files are in `$TOMCAT/webapps/$WEBAPP/WEB-INF/classes`

Make a copy of local.example.properties and rename it to local.properties
Make a copy of logback.phixflow.xml.example and rename it to logback.phixflow.xml

Step 4 Create PhixFlow File System

Note

Strictly speaking, all of the steps in this section are options - you can configure the file system as you wish, providing that you update System Configuration with the paths you have set up. However, this is PhixFlow's recommended set up, and is widely used across many PhixFlow installations.

This section also includes instructions for creating a soft-link from the PhixFlow file system area to Tomcat. It is recommended that you create this because it is needed to support creation of most applications in PhixFlow. In the commands below, a soft link is created from $TOMCAT/webapps/phixflow/datalink → [PhixFlow file system]/phixflow/datalink. This allows application designers to add image and template files to the PhixFlow file system rather than under Tomcat. Note that the Upgrading PhixFlow instructions include a step for re-creating this link when upgrading PhixFlow.

Windows

Create folders as below that are accessible by the user running Tomcat (WEBAPP is the name of the installed PhixFlow, often just "phixflow"):

C:/app/phixflow/data/$WEBAPP
C:/app/phixflow/data/$WEBAPP/upload
C:/app/phixflow/data/$WEBAPP/temp
C:/app/phixflow/data/$WEBAPP/import
C:/app/phixflow/data/$WEBAPP/export
C:/app/phixflow/data/$WEBAPP/datalink
C:/app/phixflow/data/$WEBAPP/templates
C:/app/phixflow/data/$WEBAPP/archive
C:/app/phixflow/data/$WEBAPP/driverFiles
C:/app/phixflow/data/$WEBAPP/download

Create the soft-link in a CMD or Powershell session:

Code Block
mklink /D C:\app\tomcat\webapps\$WEBAPP\datalink C:\app\phixflow\data\$WEBAPP\datalink

Linux

Code Block

export WEBAPP=[webapp name, e.g. phixflow]
sudo mkdir /opt/phixflow/data/$WEBAPP
sudo mkdir /opt/phixflow/data/$WEBAPP/upload
sudo mkdir /opt/phixflow/data/$WEBAPP/temp
sudo mkdir /opt/phixflow/data/$WEBAPP/import
sudo mkdir /opt/phixflow/data/$WEBAPP/export
sudo mkdir /opt/phixflow/data/$WEBAPP/datalink
sudo mkdir /opt/phixflow/data/$WEBAPP/templates
sudo mkdir /opt/phixflow/data/$WEBAPP/archive
sudo mkdir /opt/phixflow/data/$WEBAPP/driverFiles
sudo mkdir /opt/phixflow/data/$WEBAPP/download
sudo chown -R tomcat:tomcat /opt/phixflow/data/$WEBAPP
cd /opt/phixflow/data/$WEBAPP; sudo chmod g+w upload temp export datalink
sudo ln -sf /opt/phixflow/data/$WEBAPP/datalink /opt/tomcat/webapps/$WEBAPP/datalink

Step 5 Configure Essential Properties

Refer to Server Configuration Properties for the full list of available configuration properties. Refer to Configure a Keystore and Aliases if a keystore is being used.

The recommended minimum for a basic install in the local.properties file is as follows. This will create a new user called admin. The password will be autogenerated and written to the security.log file. It is strongly recommended that this password is changed immediately after installation.

Code Block

install.customer_name=<your customer name as provided with your licence>
install_licence_key=<Licence key as provided with your licence>
install.data.base=<C:/app/phixflow/data/$WEBAPP, /opt/phixflow/data/$WEBAPP, or other selected directory>
db.url=<database jdbc url>
phixflow-database-user=<database username>
phixflow-database-password=<database password>

The configuration settings are show below:

Insert excerpt

	Server Configuration Properties
	Server Configuration Properties
name	BasicDatabase
nopanel	true

Step 6 Restart Tomcat

Whenever you make changes in $TOMCAT/webapps/phixflow, remember to restart Tomcat, so that the changes are used.

Linux

If you have followed PhixFlow's recommended installation for PhixFlow, you can use the commands:

Code Block
sudo systemctl stop tomcat sudo systemctl start tomcat

Either do Minimum Set-up After Installation on page Administration, or instruct the people you are delivering this to to complete these steps immediately

Multiple PhixFlow Webapps
Anchor
renamingLogFile
renamingLogFile

To install multiple instances of PhixFlow on a single server, complete the installation steps above to create a first PhixFlow instance. Then install a further instance:

Create a second database user to hold the data for the new instance.
Copy the PhixFlow web application into the Tomcat again:

Code Block
cp $RELEASE/webapps/phixflow to $TOMCAT/webapps/<mywebapp>

where <mywebapp> is the name of your new instance.

Remember to set up a separate user and schema in the database for the new PhixFlow instance and to configure phixflow-datasource.xml with the user, password and connection-string.

Renaming the Log File

By default, the settings in logback.xml send log messages from all PhixFlow webapps to the same log file, phixflow.log. When you have multiple instances, it is then not clear which webapp has generated which messages. In this case, we recommend that you change each webapp to log into a separate log file.

For each webapp, edit the local.properties file and set the change the name of the log file to something that uniquely identifies which webapp it has been generated by - we recommend phixflow_webappName.log (where webappName should be changed to the name of the webapp). This can be configured by setting logging.file.phixflow.base=phixflow_webappName

Expand

title	Version 10 - Show Details

Version 10

Table of Contents

include	Step-.*

Step-1 Copy the PhixFlow Webapp into Tomcat

To install the PhixFlow web application into Tomcat:

Copy $RELEASE/webapps/phixflow to $TOMCAT/webapps/phixflow

Linux

Make sure that the file ownership is set correctly for the installed webapps:

Code Block
sudo chown -R tomcat:tomcat $TOMCAT/webapps/phixflow

Step-2 Create Configuration Files

Copy the following example configuration files and, where required, update them for your system.

Info
The files are in `$TOMCAT/webapps/$WEBAPP/WEB-INF/classes`

...

phixflow-instance.xml

Copy the example file phixflow-instance.xml.example to phixflow-instance.xml.

phixflow-instance.xml identifies the webapp instance in a resilient configuration and sets whether the instance is active on startup.

phixflow-datasource.xml

The PhixFlow webapp must be configured to

...

provide user access to the

...

PhixFlow database. In phixflow-datasource.xml, enter an alias username and password. The actual username and password are stored in an encrypted keystore; see Configure a Keystore and Aliases.

Copy phixflow-datasource.xml.<database>.example to phixflow-datasource.xml

...

.
Edit the properties for <bean id="dataSource"... (shown below).

...

Enter the alias for the database:
- username
- and password.

Code Block

language	xml

<property name="url">

...

<value>CONNECTION-STRING</value>
</property>
<property name="username">

...

<value>ALIAS-USERNAME</value>
</property>
<property name="password">

...

<value>ALIAS-PASSWORD</value>
</property>

Connection Strings

The connection strings given here should cover most cases of connecting to PhixFlow's own database. For information about how connection strings are constructed for the various database platforms supported by PhixFlow, see Database URLs.

The platform-specific [CONNECTION STRING]s are:

Oracle:

...

4. Replace the temporary values with:

USERNAME: the database user's name.
PASSWORD: the database user's password.
CONNECTION-STRING: this depends on the database platform, and is one of:

Oracle: jdbc:oracle:thin:@hostname:1521:phixflow

Oracle (> 12c with PDB containers):

...

jdbc:oracle:thin:@hostname:1521/phixflow

SQL Server:

...

jdbc:sqlserver://hostname\myservice;databaseName=phixflow;sendStringParametersAsUnicode=false

MySQL:

...

jdbc:mysql://

...

Configure phixflow-instance.xml

phixflow-instance.xml identifies the webapp instance in a resilient configuration and sets whether the instance is active on startup.

Initially, simply copy the example file phixflow-instance.xml.example to phixflow-instance.xml.

...

localhost/phixflow?defaultFetchSize=2000

These strings cover most cases of connecting to PhixFlow's own database. For information about how connection strings are constructed for the various database platforms supported by PhixFlow; see Database URLs.

phixflow-secret.xml

If you have not already done so Configure a Keystore and Aliases. Use phixflow-secret.xml to specify the keystore details.

Copy the example file phixflow-login.xml.example to phixflow-login.xml

...

.

You will use this file if you need to configure PhixFlow to authenticate users’ usernames and passwords against an external

...

domain, or Active Directory, or a SAML Single Sign-on server

...

, such as the Active Directory Federation Services server.

...

Initially, simply copy the example file phixflow-login.xml.example to phixflow-login.xml.

logback.xml
Anchor
logback
logback

Copy the example file logback.xml.example to logback.xml.

The logback.xml file controls detailed event/error logging on the server.

...

Initially, simply copy the example file logback.xml.example to logback.xml.

For instructions on how to change the name of the log file generated, see below.

Please contact PhixFlow Support for instructions on how to integrate this into other logging frameworks (e.g. Google Cloud's stackdriver).

...

You only need to change this file:

to rename the log file if you have multiple PhixFlow instances; see Renaming the Log File, below.
to change the logging level when troubleshooting; see Server Log Files
to update the standard retention setting for PhixFlow generated log files; the default is 30 days. See PhixFlow log retention settings
as requested by PhixFlow Support.

...

Tip
Changes to logback.xml

...

take effect within a

...

one or two minutes. You do not need to restart

...

Tomcat

...

.

...

phixflow-logging.xml
Anchor
phixflow-log
phixflow-log

Copy the example file phixflow-logging.xml.example to phixflow-logging.xml.

The phixflow-logging.xml file contains a list of directories that contain log files, and is used when downloading log files from the GUI.

...

Initially, simply copy the example file phixflow-logging.xml.example to phixflow-logging.xml.

...

You only need to change this file as requested by PhixFlow Support.

Using Your own Logo in PhixFlow

Optionally, you can configure PhixFlow to display your own company logo.

...

The logo must be a vector graphic .svg file

...

with the name customerLogo.svg (case sensitive). Add the file to $TOMCAT/webapps/phixflow/gui/images/

Step-3 Restart Tomcat

Whenever you make changes in $TOMCAT/webapps/phixflow, remember to restart Tomcat, so that the changes are used.

Linux

If you have followed PhixFlow's recommended installation for PhixFlow, you can use the commands:

Code Block
sudo systemctl stop tomcat sudo systemctl start tomcat

Create PhixFlow File System

Note

Strictly speaking, all of the steps in this section are options - you can configure the file system as you wish, providing that you update System Configuration with the paths you have set up. However, this is PhixFlow's recommended set up, and is widely used across many PhixFlow installations.

This section also includes instructions for creating a soft-link from the PhixFlow file system area to Tomcat. It is recommended that you create this because it is needed to support creation of most applications in PhixFlow. In the commands below, a soft link is created from $TOMCAT/webapps/phixflow/datalink → [PhixFlow file system]/phixflow/datalink. This allows application designers to add image and template files to the PhixFlow file system rather than under Tomcat. Note that the Upgrading PhixFlow instructions include a step for re-creating this link when upgrading PhixFlow.

Windows

Create folders as below that are accessible by the user running Tomcat (WEBAPP is the name of the installed PhixFlow, often just "phixflow"):

C:/app/phixflow/data/$WEBAPP
C:/app/phixflow/data/$WEBAPP/upload
C:/app/phixflow/data/$WEBAPP/temp
C:/app/phixflow/data/$WEBAPP/import
C:/app/phixflow/data/$WEBAPP/export
C:/app/phixflow/data/$WEBAPP/datalink
C:/app/phixflow/data/$WEBAPP/templates
C:/app/phixflow/data/$WEBAPP/archive
C:/app/phixflow/data/$WEBAPP/driverFiles
C:/app/phixflow/data/$WEBAPP/download

Create the soft-link in a CMD or Powershell session:

Code Block
mklink /D C:\app\tomcat\webapps\$WEBAPP\datalink C:\app\phixflow\data\$WEBAPP\datalink

Linux

Code Block

export WEBAPP=[webapp name, e.g. phixflow]
sudo mkdir /opt/phixflow/data/$WEBAPP
sudo mkdir /opt/phixflow/data/$WEBAPP/upload
sudo mkdir /opt/phixflow/data/$WEBAPP/temp
sudo mkdir /opt/phixflow/data/$WEBAPP/import
sudo mkdir /opt/phixflow/data/$WEBAPP/export
sudo mkdir /opt/phixflow/data/$WEBAPP/datalink
sudo mkdir /opt/phixflow/data/$WEBAPP/templates
sudo mkdir /opt/phixflow/data/$WEBAPP/archive
sudo mkdir /opt/phixflow/data/$WEBAPP/driverFiles
sudo mkdir /opt/phixflow/data/$WEBAPP/download
sudo chown -R tomcat:tomcat /opt/phixflow/data/$WEBAPP
cd /opt/phixflow/data/$WEBAPP; sudo chmod g+w upload temp export datalink
sudo ln -sf /opt/phixflow/data/$WEBAPP/datalink /opt/tomcat/webapps/$WEBAPP/datalink

Either do Minimum Set-up After Installation on page Administration, or instruct the people you are delivering this to to complete these steps immediately

Multiple PhixFlow Webapps
Anchor
renamingLogFile
renamingLogFile

To install multiple instances of PhixFlow on a single server, complete the installation steps above to create a first PhixFlow instance. Then install a further instance:

Create a second database user to hold the data for the new instance.
Copy the PhixFlow web application into the Tomcat again:

Code Block
cp $RELEASE/webapps/phixflow to $TOMCAT/webapps/

...

<mywebapp>

where

...

<mywebapp> is the name of your

...

new instance.

phixflow-datasource.xml

...

Remember to set up a separate user and schema in the database for the new PhixFlow instance and to

...

configure phixflow-datasource.xml

...

with the user, password and connection-string.

Renaming the Log File

By default, the settings in

...

logback.xml send log messages from all

...

PhixFlow webapps to the same log file

...

, phixflow.log

...

. When you have multiple instances, it is then not clear which webapp has generated which messages

...

. In this case, we recommend that

...

you change each webapp to log

...

into a separate log file

...

This example shows

.

For each webapp, edit the logback.xml file and change the name of the log file to something that uniquely identifies which webapp it has been generated by - we recommend phixflow_webappName.log (where webappName should be changed to the name of the webapp). This needs to be added in two places:

on line 3: messages are re-directed initially to logs/

...

phixflow_webappName.log
on line 6: messages re-directed after daily rollover to logs/

...

phixflow_webappName.yyyy-MM-dd.log.

Code Block

language	xml
title	logback.xml
linenumbers	true

... 
 <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>logs/

...

phixflow_webappName.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">        
      <!-- daily rollover -->
      <fileNamePattern>logs/

...

phixflow_webappName.%d{yyyy-MM-dd}.log</fileNamePattern>
      <maxHistory>30</maxHistory>
    </rollingPolicy>
    <encoder>
      <pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern>
    </encoder>
  </appender>
...

Versions Compared

Old Version 21

New Version Current

Key

Version 11

Configuration Files

Step 1 Shutdown Tomcat

Step 2 Copy the PhixFlow Webapp into Tomcat

Configure the Webapp

Step 3 Create Configuration Files

Step 4 Create PhixFlow File System

Step 5 Configure Essential Properties

Step 6 Restart Tomcat

Multiple PhixFlow Webapps
Anchor
renamingLogFile
renamingLogFile

Renaming the Log File

Version 10

Step-1 Copy the PhixFlow Webapp into Tomcat

Step-2 Create Configuration Files

phixflow-instance.xml

phixflow-datasource.xml

Connection Strings

Configure phixflow-instance.xml

phixflow-secret.xml

logback.xml
Anchor
logback
logback

phixflow-logging.xml
Anchor
phixflow-log
phixflow-log

Using Your own Logo in PhixFlow

Step-3 Restart Tomcat

Create PhixFlow File System

Multiple PhixFlow Webapps
Anchor
renamingLogFile
renamingLogFile

phixflow-datasource.xml

Renaming the Log File

Page Comparison

Versions Compared

Old Version 21

New Version Current

Key

Version 11

Configuration Files

Step 1 Shutdown Tomcat

Step 2 Copy the PhixFlow Webapp into Tomcat

Configure the Webapp

Step 3 Create Configuration Files

Step 4 Create PhixFlow File System

Step 5 Configure Essential Properties

Step 6 Restart Tomcat

Multiple PhixFlow Webapps AnchorrenamingLogFilerenamingLogFile

Renaming the Log File

Version 10

Step-1 Copy the PhixFlow Webapp into Tomcat

Step-2 Create Configuration Files

phixflow-instance.xml

phixflow-datasource.xml

Connection Strings

Configure phixflow-instance.xml

phixflow-secret.xml

phixflow-login.xml Anchorloginlogin

logback.xml Anchorlogbacklogback

phixflow-logging.xml Anchorphixflow-logphixflow-log

Using Your own Logo in PhixFlow

Step-3 Restart Tomcat

Create PhixFlow File System

Multiple PhixFlow Webapps AnchorrenamingLogFilerenamingLogFile

phixflow-datasource.xml

Renaming the Log File

Multiple PhixFlow Webapps
Anchor
renamingLogFile
renamingLogFile

phixflow-login.xml
Anchor
login
login

logback.xml
Anchor
logback
logback

phixflow-logging.xml
Anchor
phixflow-log
phixflow-log

Multiple PhixFlow Webapps
Anchor
renamingLogFile
renamingLogFile