Install the PhixFlow Webapp

Owned by Gary Parden
Last updated: Aug 14, 2024 by Zoe Baldwin
3 min read

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.

Configuration Files

Configuration options can be specified in a number of different ways. These take precedence in the following order:

  1. Java System properties – set using the -D propertyName=value on the java command line / tomcat launch configuration

  2. webapps/<phixflow>/WEB-INF/classes/local.properties – optional java properties file

  3. webapps/<phixflow>/WEB-INF/classes/phixflow.properties – optional java properties file

  4. Environment variables – using the environment form of the property name as described below

  5. webapps/<phixflow>/WEB-INF/classes/context/server.properties – this contains the default values and should not be modified

In other words

  • a setting in phixflow.properties takes precedence over a setting for that same property in server.properties

  • a setting in local.properties takes precedence over a setting for that same property in either or both server.properties or phixflow.properties

Keystore Files

Optionally, secrets, such as database passwords, can be kept encrypted in external secret files. Refer to Configure a Keystore and Aliases for instructions on how to configure this before proceeding with the installation.

Environment Form of Property Names

As operating systems have stricter rules around valid characters in environment variable names, and prefer them to be in upper case, when using environment variables the property name should be converted as follows:

  • Replace dots (.) with underscores (_)

  • Remove any dashes (-)

  • Convert to uppercase

For example, “db.url” would be looked up as “DB_URL” when resolved from environment variables.

Guidelines and Advice for Configuration

  • The context/server.properties file should never be changed. This is replaced on upgrade.

  • For a multi-instance environment (e.g. DEV, QA and Prod) it is recommended that a common phixflow.properties file is used on all instances, containing configuration settings that are identical on all environments. The local.properties file is then used for local overrides, such as database url and passwords.

  • For single instance environments it is recommended that you use only the local.properties file.

  • Only properties that have differing values from the default settings in the server.properties should be configured. This makes it easier to review and manage the configuration and ensures that fixes and improvements to the default settings will be applied automatically.

  • In docker environments it may be beneficial to use environment variables rather than settings in the local.properties file. This allows the same container image to be started as multiple instances with different configurations.

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

Linux

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

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.

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

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

Step 4 Create PhixFlow File System

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:

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

Linux

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.

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:

Database Connection Configuration

These are the basic settings to enable connection to the Phixflow database.

Property

Requires Configuration

Default Value

Explanation

db.url

Always

<none>

The jdbc url of the database including any required parameters. For more information on defining the database URL consult your Database Administrator.
Example URLs

MySQL

jdbc:mysql://localhost/phixflow?defaultFetchSize=2000&allowPublicKeyRetrieval=true
Note the allowPublicKeyRetrieval parameter may be required depending on your setup

Oracle

jdbc:oracle:thin:@//localhost:1521/pdb.local

SQL Server

jdbc:sqlserver://;database=webtrunk;sendStringParametersAsUnicode=false;encrypt=false

MS SQL Server JDBC driver version 12.6.1 onwards, defaults to using an encrypted connection which may require additional parameters to be added to the URL. If encryption is not required, add 'encrypt=false' to the URL.

See https://learn.microsoft.com/en-us/sql/connect/jdbc/microsoft-jdbc-driver-for-sql-server?view=sql-server-ver16

phixflow-database-user

Often

<none>

Default key name containing the database username. This can also be stored in the keystore.

phixflow-database-password

Often

<none>

Default key name containing the database password. This can also be stored in the keystore.

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:

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

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:

  1. Create a second database user to hold the data for the new instance.
  2. Copy the PhixFlow web application into the Tomcat again:
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