V3.2 Installation Instructions
From Frevvodocs
frevvo Live Forms™ v3
Contents
|
Installing frevvo Live Forms™ in-house
The following instructions apply to frevvo's downloadable versions – prior to V3.3. If you are using V3.3 or later versions, please click V3.3 Installation Instructions.
frevvo Live Forms is available in both a hosted version and a downloadable version that you may install in-house. If you are trying to decide which version is right for your needs please refer to [SaaS or Download?]. There is nothing to install for the hosted version. Just point your browser to http://www.frevvo.com to get started building and using your forms.
Instructions
The following instructions apply to frevvo's downloadable version.
When you [sign up] for the downloadable version you will automatically be sent an activation email which contains a license key and a link to the installation instructions.
THERE ARE TWO CHOICES. One button labeled Download frevvo war and the other labeled Download Tomcat bundle. The bundle includes Tomcat 6.0.16 and works on Windows & Linux systems. If you are planning to install a trial version of frevvo, we strongly recommend the Tomcat bundle since it is setup to run frevvo Live Forms without any further configuration.
The frevvo war download is recommended for existing customer who are already running frevvo and wish to upgrade to the latest version. If you are not an existing customer and want to install frevvo in-house in your existing web application server (jboss, jetty, apache, etc..) please contact frevvo support for further configuration and dependencies.
Videos
For help installing the downloads, please watch the [Tomcat Bundle installation video] and the [frevvo war installation video].
Prerequisites
The following prerequisites must be satisfied in order to run frevvo in-house.
- JDK or JRE 1.5 (Update 8 or higher) also JDK or JRE 1.6 are supported.
- Servlet 2.4 or higher container. frevvo recommends Tomcat 5.5 or higher (not required for bundle)
- http(s) connectivity to http://www.frevvo.com for licensing and software update.
Once you have a machine that satisfies the above requirements, please follow these steps:
Installing frevvo-Tomcat bundle
Set up the environment (Windows only)
- Make sure that the JAVA_HOME environment variable is set to the installation directory of your JDK or JRE, for example, C:\Program Files\Java\jdk1.5.0_12
Unpack the download zip
- Unzip the frevvo.zip file. (Note Windows Only: you must extract the zip file into c:\).
- Ensure that you do not have another server running on port 8080.
Start frevvo
Upgrading Customers IMPORTANT For Upgrading Customers, please refer to Upgrading your Form Server below. Customers upgrading from a prior Live Forms release... must copy their existing user and assets directories to c:\frevvo\ before starting v3 for the 1st time.
- Start frevvo (See below on Windows vs Linux).
- Open frevvo's home page in your browser. e.g. http://localhost:8080/frevvo/web/login. If you are using a browser on a different machine replace localhost with the name of the server machine but see host-port configuration below.
- See Installing your Customer License Key
- Configure the Admin host:port
- Add a new user
On Windows
- In a windows explorer go to c:\frevvo and double-click Start frevvo. This should start Tomcat on port 8080 with frevvo correctly pre-configured.
On Linux
Linux requires minor additional configuration. Assuming you unziped into a directory /home/frevvo. (It is important to note that these steps assume and require that they are executed from the tomcat directory. If not you will need to make the appropriate adjustments to these steps.)
- cd /home/frevvo/tomcat
- tomcat$ vi conf/Catalina/localhost/context.xml.default
Change this line
<Parameter name="frevvo.users.path" value="c:\frevvo\users" override="false"/>
To this line
<Parameter name="frevvo.users.path" value="../users" override="false"/>
Note: the users path is relative to the location the executable was started in, which in this case is the the tomcat subdirectory.
- tomcat$ chmod 755 bin/*.sh
- tomcat$ ./bin/catalina.sh run
Or alternatively, to start/stop Tomcat in the background:
- tomcat$ ./bin/catalina.sh start
- tomcat$ ./bin/catalina.sh stop
Tomcat Manager
- Note that the Tomcat Manager user name/password are preset to frevvo/frevvo. If you wish to change the password, you may do so by editing the file c:\frevvo\tomcat\conf\tomcat-users.xml in any text editor.
Installing frevvo.war Standalone
In case you want to install frevvo into your own Servlet container (eg. Tomcat, JBoss, Glassfish, etc) you can also install the frevvo.war without the prepackaged Tomcat bundle.
This requires additional jars into your container classpath and a few web application context parameters (each container has a specific way of setting context parameters). If you dont have the required expertise or privilege in house to configure your own web container, we strongly recommend the Tomcat bundle since it is setup to run frevvo Live Forms without any further configuration.
Upgrading Customers IMPORTANT For Upgrading Customers, please refer to Upgrading your Form Server below. Customers upgrading from a prior Live Forms release... must copy the contents of the new users directory from the zipfile into the existing frevvo users directory before starting V3.1 for the 1st time.
Download the Tomcat Bundle
- Download the Frevvo Live Forms Tomcat bundle from our servers. The Tomcat bundle is a working example of installing frevvo.war standalone and it has the added benefit of already bundling all the required dependencies (jars and configuration files) that you will need to use.
Unpack the Tomcat bundle zip
- Unzip the bundle to a location of your choice (i.e. $FREVVO_HOME). We are going to copy a some files from this bundle such as the frevvo.war, additional jars and a Tomcat configuration file
Deploy the frevvo.war
- Copy the $FREVVO_HOME/data folder to the location of your choice e.g. /var/frevvo/data ($FREVVO_DATA)
- Copy the $FREVVO_HOME/tomcat/webapps/frevvo.war to the webapps folder of your Servet container (e.g. see $FREVVO_HOME/tomcat/webapps or use the container's deployer UI)
- Copy the following Jars from the $FREVVO_HOME/tomcat/lib to your container lib folder:
* $FREVVO_HOME/tomcat/lib/slf4j-jdk14-1.5.6.jar * $FREVVO_HOME/tomcat/lib/slf4j-api-1.5.6.jar * $FREVVO_HOME/tomcat/lib/mail-1.4.1.jar * $FREVVO_HOME/tomcat/lib/activation-1.1.jar
- Copy the following DB connection pooling related jars (or provide an alternate one based on your deployment configuration):
* $FREVVO_HOME/tomcat/lib/commons-pool-1.3.jar * $FREVVO_HOME/tomcat/lib/commons-dbcp-1.2.2.jar * $FREVVO_HOME/tomcat/lib/commons-collections-2.1.1.jar
- Copy one of the following jars (or all) depending on your database:
* $FREVVO_HOME/tomcat/lib/hsqldb-1.8.0.7.jar (HSQLDB) * $FREVVO_HOME/tomcat/lib/jtds-1.2.2.jar (SQL Server) * $FREVVO_HOME/tomcat/lib/mysql-connector-java-5.1.6.jar (MYSQL)
We use the Simple Logging Facade for Java (SLF4J) for our logging needs and the above jars, namely slf4j-api-1.5.6.jar and slf4j-jdk14-1.5.6.jar, will configure SLF4J to use the Java Logging APIs (java.util.logging). If your application server uses a different logging infrastructure you can replace the slf4j-jdk14-1.5.6.jar with the correct one. You can find more info here on how to do this and download the correct SLF4J adapter.
Note: At this point it is required that the context path for the frevvo web application be /frevvo
Configure web application resources
Configure the following web application resources (use $FREVVO_DATA/tomcat/conf/Catalina/localhost/context.xml.default as your guide):
* jdbc/frevvoDS (javax.sql.DataSource) * mail/frevvoDS (javax.mail.Session)
Failure to setup these resource will cause issues trying to create new forms, view submissions or submit forms, issues sending emails.
Here is a sample jdbc/frevvoDS resource configuration for Apache Tomcat 6.x connecting to HSQLDB:
<Parameter name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/> <Resource auth="Container" type="javax.sql.DataSource" factory="org.apache.commons.dbcp.BasicDataSourceFactory" name="jdbc/frevvoDS" driverClassName="org.hsqldb.jdbcDriver" username="sa" password="" url="jdbc:hsqldb:file:formsdb" maxActive="20" maxIdle="3" maxWait="10000" validationQuery="select 1 from INFORMATION_SCHEMA.SYSTEM_USERS" testOnBorrow="true" testOnIdle="true" timeBetweenEvictionRunsMillis="10000" removeAbandoned="true" logAbandoned="true"/>
Here is a sample mail/frevvoDS resource configuration for Apache Tomcat 6.x:
<Resource
auth="Container"
factory="org.apache.naming.factory.MailSessionFactory"
type="javax.mail.Session"
name="mail/frevvoDS"
mail.smtp.host="{your.smtp.host}"
mail.smtp.port="{your.smtp.port}"
mail.smtp.auth="true"
mail.smtp.starttls.enable="true"
mail.smtp.user="{your.smtp.user}"
mail.smtp.password="{your.smtp.password}"
mail.debug="false"/>
Configure Hibernate Dialect
You will also need to configure the Hibernate dialect to use the correct class for your database.
Override the following web context parameter:
* hibernate.dialect
With any of the dialects supported by Hibernate 3.2.4.ga. Here are some of them:
* org.hibernate.dialect.HSQLDialect * org.hibernate.dialect.MySQL5Dialect * org.hibernate.dialect.MySQL5InnoDBDialect * org.hibernate.dialect.Oracle9Dialect * org.hibernate.dialect.OracleDialect * org.hibernate.dialect.PostgreSQLDialect * org.hibernate.dialect.SQLServerDialect * org.hibernate.dialect.Sybase11Dialect
For example, changing the dialect in Apache Tomcat can be achieved by adding the following parameter element to the context.xml file or context.xml.default file:
<Parameter name="hibernate.dialect" value="org.hibernate.dialect.PostgreSQLDialect" override="false"/>
For additional dialects see Hibernate documentation.
Override Container context parameters
Override at least the following context parameters (see $FREVVO_HOME/tomcat/conf/Catalina/localhost/context.xml.default as an example):
* frevvo.users.path - the $FREVVO_DATA folder chosen above, e.g. /var/frevvo/data/users on linux or c:\frevvo\data\users on windows * frevvo.mail.from.email - an email address used as the from address in emails sent by frevvo) * frevvo.mail.bounce.email - an email address used when emails sent by frevvo bounce * frevvo.app.port - the http connector port for your application server -- 8082 is the default * frevvo.ssl.port - the https connector port for your application server -- 443 is the default
Alternatively, you can set the frevvo.users.path using a system property.
Additional configurations
* Make sure your container supports large HTTP headers (e.g. 32768 bytes is a safe number) * If using Tomcat, make sure that you set the useBodyEncodingForURI="true" in the Connector configuration
Get it up and running
* Start your application server * Open frevvo's home page in your browser. e.g. http://localhost:8082/frevvo (replace localhost with your server name).
Common Installation Tasks
Install your customer license key
- Open frevvo's home page in your browser. e.g. http://<myserver>:8080/frevvo/web/login
- If this is a new frevvo installation you will be prompted to enter the license key you received in your activation email
- Copy the license string you received via an email titled "Download software" or given to you by frevvo into the License Key box and submit.
- You will next see this page
- New Customer should proceed immediately by clicking the continue button.
- Existing/Upgrading customers must follow the upgrade instructions first and then click the continue button
This will start the frevvo Live Forms Installation Process. When this process is complete you will see this final page:
- You must restart frevvo
Updating your customer license key
If you are currently running with a trial license and have since purchased frevvo Live Forms and now need to install you permanent license key, please refer to the documentation Updating your License.
Admin host:port configuration
- Login to frevvo as: user admin , password admin
- Click on the applications link in the header
- Edit the Admin application and click on the properties in the header
- Verify that the Form Action and Doc Action base URLs are correct
- In particular, you may need to change/add a port number.
- For example, if your server is named gandalf and is running on port 8000, you will need to change the URLs to http: //gandalf:8000/
- Note: The trailing / is important.
- Edit the Add User form
- Click on the Rules tab and expand the User Exists rule
- Once again, you will need to set the correct port on which your server is running. You can leave this as localhost.
Changing the admin user password
Perform the following steps still logged in as the admin user.
- Click on applications link to get back to the main menu
- Then, click on the users link in the header
- Click on the
icon for the admin user. You will see a profile form appear
- Use this form to change the password and click submit. You should see a success message. It may take a while for the update to succeed.
Add a new user
The admin user should not be used for creating your own forms. Add a new user for that purpose.
- Make sure you are still logged in as the admin user
- Click on the users link in the header, to navigate to the Users page
- Click the
icon. You should see a form appear
- Fill in all form fields. You should see User xxx was successfully added, where xxx is the user id you selected.
- Logout as the admin user.
- Login as the xxx user above. You should be able to login successfully and begin creating and using your own forms
Email Configuration
The forgot password functionality and form submissions sent via email both require proper configuration of frevvo's smtp component. Edit the file named configuration.default.xml and setup the parameters shown below. In a default frevvo installation this file is located in <install_dir>\frevvo\tomcat\conf\Catalina\localhost\context.xml.default
The configuration.default.xml contains a few other parameters that effect emails sent from frevvo:
<Parameter name="frevvo.mail.from.email" value="no-reply@frevvo.com" override="false"/> <Parameter name="frevvo.mail.debug" value="false" override="false"/> <Parameter name="frevvo.mail.bounce.email" value="support@frevvo.com" override="false"/>
from.email sets the from address in form submission and forgot password emails. debug sends more debugging info to the tomcat log files. And bounce.email set an address to receive emails that cannot be delivered to the to email address.
License Configuration
The frevvo Form Server prompts you for a license string when first started. See License Installation for full details. frevvo stores the license in c:\frevvo\users\.frevvo\customer.lic. There after frevvo pings the frevvo license server on a regular interval. If the frevvo Form Server cannot communicate with the frevvo license server the license will temporarily expire until communication is reestablished.
Proxy Setting
If your company uses a Proxy Server your frevvo Form Server may not be able to communicate with the license server directly. frevvo has web configuration parameters to enable communication from the Form Server to the license server via your proxy. Edit the following parameters in web.xml or override them at the container level, eg: on Tomcat in tomcat/config/catalina/localhost/context.xml.default.
| Parameter | Description |
|---|---|
| frevvo.proxy.host | HTTP Proxy Host |
| frevvo.proxy.port | HTTP Proxy port |
| frevvo.proxy.username | HTTP username |
| frevvo.proxy.password | HTTP password |
Please contact us if you have questions on licensing.
Upgrading your Form Server
Existing/upgrading customers running prior version of frevvo Live Forms must take a few additional steps during the installation of the new v3 Form Server. The upgrade can be accomplished one of two ways. Both upgrade paths are explained in detail below.
1) Install the frevvo-tomcat v3 bundle zip, and then migrate your old frevvo users, etc.. into the new v3 frevvo-tomcat bundle.
or
2) Replace frevvo.war in your existing web application container with the new v3 frevvo.war
NOTE: These instructions assume that you have installed frevvo v3 into c:\frevvo and your users into c:\frevvo\users. If you have installed elsewhere make the appropriate adjustments to the instructions below.
frevvo-tomcat upgrade path
Backup
Before starting the upgrade process:
- Make a backup copy of your current frevvo users c:\frevvo\users and assets c:\frevvo\assets
- Login as the admin user and download any applications and control templates you may have added
- Make a backup copy of tomcat\conf\Catalina\localhost\context.xml.default (tomcat-specific, if it exists)
- Make a backup copy of webapps\frevvo\WEB-INF\web.xml located in your web application container directory.
users
It is very important to copy your existing users into your new v3 users directory BEFORE starting the new v3.1 Form Server for the 1st time. frevvo automatically migrates older users from v1, v2 and v3 into the new v3.1 format. This is a one time process so your older users must be already installed into v3 prior to the 1st start.
- copy users\* from your old Form Server installation into c:\frevvo\users. This assumes that you have installed the new v3 into c:\frevvo.
Note that the new v3 users directory already contains a few special users and files. Take care NOT to overwrite these new files when you copy the users from your existing users directory.
assets
All images and videos uploaded and used by your user's forms are stored in the assets directory. Copy the contents of the assets directory from your old Form Server to c:\frevvo\assets
form templates (migration from v2 only)
If your v2 Live Forms installation contains any published Form Templates, please contact frevvo for information on migrating templates to v3. If you are migrating from an earlier version of v3 to the new v3.1 version, this migration process occurs automatically.
control templates
Control Templates are located in your old admin user. To migrate them to v3, download the applications containing your control templates, from your old admin user and upload into the new v3 admin user. Then drag/drop all the controls into the v3 admin user's Custom Palette. If you custom controls are group controls (sections, repeats, panels, tabs) you will notice that v3 launches a wizard when you drop them into Custom. See the documentation on Custom Group Wizard for details.
context.xml.default
Edit c:\frevvo\tomcat\conf\Catalina\localhost\context.xml.default to add any customizations your made in your old Form Server to the v3 Form Server. Note that you cannot simply copy the old context.xml.default to the v3 Form Server as the configuration file has changed.
frevvo.war upgrade path
Backup
Before starting the upgrade process:
- Make a backup copy of your current frevvo users c:\frevvo\users and assets c:\frevvo\assets
- Login as the admin user and download any applications and control templates you may have added
- Make a backup copy of tomcat\conf\Catalina\localhost\context.xml.default (tomcat-specific, if it exists)
- Make a backup copy of webapps\frevvo\WEB-INF\web.xml located in your web application container directory.
Unpack the v3 download zip
- Create a directory where you want to unzip frevvo v3
- Unzip frevvo.zip. This extracts frevvo.war, a readme.txt, and a users folder, and a context.default.xml file.
Stop/Undeploy frevvo v1/v2/v3
- Shutdown and Undeploy your old frevvo Form Server. For example if you are running under tomcat, you can use the tomcat manager to do this.
users
- copy the contents of the users folder from the v3 download zip into your current Form Server's users directory. This will replace your old admin user with the new v3 admin user as well as a few other system files.
It is very important to update the users from the v3 frevvo.zip file BEFORE starting the v3 Form Server for the 1st time. frevvo automatically migrates older users from v1, v2 and v3 into the new v3.1 format. This is a one time process so your older users must be already installed into v3 prior to the 1st start.
form templates (migration from v2 only)
If your v2 Live Forms installation contains any published Form Templates, please contact frevvo for information on migrating templates to v3. If you are migrating from an earlier version of v3 to the new v3.1 version, this migration process occurs automatically.
control templates
Control Templates are located in your old admin user. To migrate them to v3, upload the applications downloaded in the backup step above, into the v3 admin user. Then drag/drop all the controls into the v3 admin user's Custom Palette. If you custom controls are group controls (sections, repeats, panels, tabs) you will notice that v3 launches a wizard when you drop them into Custom. See the documentation on Custom Group Wizard for details.
context.xml.default
This file is tomcat specific. If you are working with a different web application server, use the contents of this file as a guide to the configurable frevvo web parameters.
- Replace and/or Merge context.xml.default (tomcat-specific, if it exists in your web application server) with the one from the v3 frevvo.zip file.
- If you had customized frevvo in your web application server via another method, locate and delete the frevvo web paramenters and replace them with the new parameters from the v3 frevvo.zip file conntext.xml.default.
web.xml
- Edit web.xml as described above in Standalone frevvo (without Tomcat)
- Also make any customizations you had from the backup copy of web.xml you saved earlier.
Need Help?
Contact Us
If you need help with the installation and configuration process contact us.
Troubleshooting
Here are several common configuration error that can be easily solved.
Login page display "Unable to renew license"
You see the following error message on frevvo's login page when you try to access the login page in your browser at http://<yourhost><port>/frevvo/web/login
"Unable to renew license for 1 attempt(s). Your license will expire in 2 day(s). Please contact frevvo for help."
You will also see the following error in the tomcat log file:
WARNING: License monitor: failed to authorize start up for 0 attempts. Next attempt in 1 hours.
This is often caused by running your web app container (ex: tomcat) under a SUN JDK or JRE that is not version 1.5.0 update 8 or later. Verify that you are running with the required JDK or JRE. If not, to solve this, download & install JDK or JRE 1.5.0 version 8 or later from http://www.sun.com. Set your JAVA_HOME on windows to the JDK or JRE install directory on your computer. Then restart your web app container.
This may also be caused by an incorrect string content in your customer.lic file. Look in the location where you put your frevvo users directory. Verify that a a customer.lic file exists in a subdirectory named .frevvo. Edit the customer.lic file and verify that the content is correct. This file must contain a single line which is the license key sent to you via email when you downloaded frevvo.zip.
Unable to contact license server
This may be due to your external http traffic being routed through a proxy server. Please see the topic license configuration for details on how to setup the frevvo Form Server to work with a proxy server.
frevvo fails to install/start as windows service
Running c:\frevvo\Install Service, fails to install the frevvo service and the frevvo fails to run as a windows service. This problem is solved by adding %JAVA_HOME%/bin to the system PATH Environment Variable.
If this fails to solve the problem even with setting of JAVA_HOME the tomcat service may not be able to find msvcr71.dll even though it is in the bin directory of your JDK or JRE installation, copy msvcr71.dll from the bin directory of your java installation the bin directory of your tomcat installation or to your C:\WINDOWS\System32 directory.
You may see these errors in the windows service log file:
[174 javajni.c] [error] The specified module could not be found. [986 prunsrv.c] [error] Failed creating java C:\Program Files\Java\jdk1.6.0_07\jre\bin\server\jvm.dll [1260 prunsrv.c] [error] ServiceStart returned 1
