V3.0 Installation Instructions
From Frevvodocs
frevvo Live Forms™ v3.0
V3.0 GA Release July 20, 2008...
Contents |
Installing frevvo Live Forms™ in-house
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 you 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 download. Clicking on the download link takes you back to www.frevvo.com where you will download frevvo.zip to your local computer.
THERE ARE TWO CHOICES. One button labeled Download (frevvo-only) and the other labeled Download Tomcat Bundle. The bundle includes Tomcat 6.0.14 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-only 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 [Standalone frevvo installation video].
Prerequisites
The following prerequisites must be satisfied in order to run frevvo in-house.
- JDK 1.5 (Update 8 or higher) or JDK 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:
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, 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 directories to c:\frevvo\users before starting V3.0 for the 1st time.
- Once you have copied your existing users, 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.
- You will see this page
- For existing customers, this will upgrade users from prior Live Forms version to the new v3.0 version
- Once the upgrade is done for both new and existing customer, you must restart frevvo
New Customers NOTE that both existing/upgrading AND new download installation will see the Upgrade page the 1st time you start frevvo. For new customers you still will have to complete the upgrade step and then restart frevvo before continuing.
Start frevvo/tomcat (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.
Start frevvo/tomcat (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"/>
- tomcat$ chmod 755 bin/*.sh
- tomcat$ catalina.sh run
Or alternatively, to start/stop Tomcat in the background:
- tomcat$ catalina.sh start
- tomcat$ 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-5.5.23\conf\tomcat-users.xml in any text editor.
Install your customer license key
- 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.
- This will create an empty customer license file - $users/.frevvo/customer.lic
- Edit customer.lic and copy the license key you received in your activation email into the file
- Note: The customer.lic should contain nothing else but the key prefixed with the string "customer.key=". For example:
customer.key=_EAsa4P32op95322GMcPQobQ
- Restart the frevvo web application
host:port configuration
This step is not required if you are accessing frevvo using http://localhost:8080/frevvo/web/login.
- 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
- Edit the Form Action and Doc Action base URLs
- In particular, replace localhost with the name of your server.
- For example, if your server is named gandalf, you will need to change the URLs to http: //gandalf:8080/
- Note: The trailing / is important.
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.
- After the user is created, make sure you click the "enabled" checkbox in the user's profile. If you do not, the user
will be automatically disable after the 30 day trial period expires.
- 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
Standalone frevvo (without Tomcat)
Unpack the download zip
The frevvo-only download requires special configuration in your web application container for required dependencies. Please contact frevvo support if you require help. 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. If you are a current customer upgrading to the latest version you can simply unzip the war file and install the new frevvo.war into your web application server.
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.0 for the 1st time.
- Create a directory where you want to unzip frevvo
- Unzip frevvo.zip. This extracts frevvo.war, a readme.txt, and a users folder.
- Move the users folder to the location of your choice e.g. /var/frevvo/users (Referred to below as $users)
- Deploy frevvo.war to a servlet container e.g. Tomcat
- Edit web.xml as follows:
- Set frevvo.users.path to the $users folder chosen above
- If you have a mail server, set the from and bounce parameters, and refer to Email Configuration below.
- If your web server is not running on port 80, you will need to uncomment and edit the following context parameter (replace 8080 with your port number):
<context-param>
<description>Application port</description>
<param-name>frevvo.app.port</param-name>
<param-value>8080</param-value>
</context-param>
- The servlet container should automatically restart the frevvo web application.
- Contact frevvo customer support for configuration and dependencies.
Install your customer license key
- Open frevvo's home page in your browser. e.g. http://<myserver>:8080/frevvo/web/login
- This will create an empty customer license file - $users/.frevvo/customer.lic
- Edit customer.lic and copy the license key you received in your activation email into the file
- Note: The customer.lic should contain nothing else but the key prefixed with the string "customer.key=". For example:
customer.key=_EAsa4P32op95322GMcPQobQ
- Restart the frevvo web application
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.
- After the user is created, make sure you click the "enabled" checkbox in the user's profile. If you do not, the user
will be automatically disable after the 30 day trial period expires.
- 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.
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.
Upgrading your Form Server
Both existing/upgrade customers and those installing Live Forms for the first time, must compete the upgrade step. The first time you start v3 you will see this page:
New Live Forms installations, click the upgrade button, then restart frevvo when the process completes and you are told to restart. And your installation process is finished.
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
users
It is very important to copy your existing users into the v3 users directory BEFORE starting the v3 Form Server for the 1st time. frevvo automatically migrates older users from v1 and v2 into the new v3 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 v3 into c:\frevvo.
assets (v2 only)
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 (v2 only)
If your v2 Live Forms installation contains any published Form Templates, please contact frevvo for information on migrating templates to v3.
control templates (v2 only)
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 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.
Start frevvo/tomcat v3
- 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.
- If you're installing on Linux, see Start frevvo/tomcat (Linux) above.
- 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.
- You will see this page
The first time you start v3 you will see this page:
Clicking "upgrade" starts the migration process. Please wait until it has completed and the browser window displays the following page:
Restart frevvo v3
Now you can restart v3 and the user upgrade process is complete.
frevvo.war (standalone) upgrade path
Backup
Before starting the upgrade process:
- Make a backup copy of your frevvo user directory c:\frevvo\users
- Login as the admin user and download any applications you 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
- 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 v3 admin user.
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 and v2 into the new v3 format. This is a one time process so your older users must be already installed into v3 prior to the 1st start.
form templates (v2 only)
If your v2 Live Forms installation contains any published Form Templates, please contact frevvo for information on migrating templates to v3.
control templates (v2 only)
Control Templates are located in your v2 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.
Deploy/Start v3 frevvo
- Deploy the new v3 frevvo.war to a servlet container e.g. Tomcat
- This will automatically start the new v3 frevvo Form Server.
- Open frevvo's home page in your browser. e.g. http://<myserver>:8080/frevvo/web/login
The first time you start v3 you will see this page:
Clicking "upgrade" starts the migration process. Please wait until it has completed and the browser window displays the following page:
Restart frevvo v3
Now you can restart v3 and the user upgrade process is complete.
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 JRE that is not version 1.5.0 update 8 or later. Verify that you are running with the required JRE. If not, to solve this, download & install JRE 1.5.0 version 8 or later from http://www.sun.com. Set your JAVA_HOME on windows to the 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. And it must have a prefix of "customer.key=". Verify that the content looks as follows:
customer.key=<your license key>
where <your license key> is replaced by the string sent to your in the download activation email. For example:
customer.key=_EAsa4P32op95322GMcPQobQ
