Opinio installation

Tomcat installation

These instructions are for the Tomcat application server. Other application servers are supported, and the instructions are similar. Refer to the documentation of your application server for deploying applications.

Make sure the required software is installed (see requirements).

Unzip the opinio zip file in a temporary folder. In it, there is an opinio.war file.
Locate the base web application directory, webapps, of your Tomcat installation, normally at [tomcat-home]/webapps.
Place the opinio.war file in this folder.
Restart Tomcat. Tomcat will now unpack and create the Opinio folder automatically.
For linux/unix:
For charts (in reports) to work, Opinio needs to know more information about where to find the graphical environment. The easiest way to do this is to simply tell Opinio to run in "headless mode".

To run your application server (Tomcat or other) in headless mode, you need to set the startup-options to support this. At the top of the Tomcat catalina.sh file (in the [tomcat-home]/bin folder):

# increasing memory usage to 512mb, and using headless mode JAVA_OPTS=" -Xmx512m -Djava.awt.headless=true "

Installation is now complete. Log in at the following address:

http://server-address/opinio/admin/login.do

Replace “server-address” with the address of the server you installed on. Use login = admin, password = admin. The password for admin should be changed before you start creating your surveys, to improve security.

IMPORTANT

If you are planning to use polls on your website, you might need to set up your Platform for Privacy Preferences (P3P) to prevent cookies from being blocked by browsers. This is especially crucial for polls as their cookies in most cases will be considered as third-party cookies. Compact policy and location of the policy reference file can be set in web.xml.

Search for PolicyRef and CompactPolicy in the web.xml file.

Read more about P3P here: http://www.w3.org/P3P.
Opinio comes with a demo database. The default database is meant for demo and test purposes. For production use, a scalable and robust platform should be used. See the section "Using other database platforms" for more information.

Opinio comes with Apache Derby as its default, built-in database. It runs Apache Derby i embedded mode, which means that it is running in the same processes as Opinio. In other words, Apache Derby is not running as a standalone database server. Apache Derby is known to be robust and fast. But we have not yet tested this in a production environment, and can not give any guarantees that it will perform well over time with Opinio.
Opinio comes with English as default language. Read section Internationalization to learn how to localize Opinio.
Read section "Administrators guide" in the User Manual for setup configuration, performance tips and application maintenance instructions.

Using other database platforms

Opinio is pre installed with Apache Derby - a light-weight, but fast database engine. This is meant for demonstration purpose only. To use the application in a large production environment, we recommend to change the database platform to SQL Server, MySql, Oracle or other more scalable database systems.

Opinio has been tested on and supports the following databases:

MySql
Oracle
SqlServer
DB2
PostgreSql
Derby (supported from 6.0)

MySql

Install MySql, and create a database called opinio. Make sure that the database supports the character sets you need to use (see Internationalization). Refer to the MySql documentation for more information about this. If you are only going to use the latin character set, you should not need to change character set settings. It is very important that this is verified before you start using the application, because changing the character set on existing data might lead to unpredictable problems.
Go to the opinio/WEB-INF/database folder and log into MySql. Change database to 'opinio' and run the mysql_create.sql script:

mysql> use opinio; mysql> source mysql_create.sql;
Rename the file

WEB-INF/database.properties

to

WEB-INF/database_derby.properties
Then Rename the file

WEB-INF/database_mySql.properties

to

WEB-INF/database.properties
Edit this file (WEB-INF/database.properties). The line starting with

objectplanet.persistence.jdbcURL=

...should read (if you have installed MySql on another system, replace localhost with the address of this host):

jdbc:mysql://localhost:3306/opinio

For non-Latin characters you might want to set database driver to Unicode mode by adding the following parameters:

jdbc:mysql://localhost:3306/opinio?useUnicode=true&characterEncoding=UTF-8

Set user name and password to use when connecting to the database:

objectplanet.persistence.user=[user name] objectplanet.persistence.password=[password]
Save the changes you have made to database.properties
Restart your application server

The connection to MySql should now work. You may also want to create your own database user (instead of using root), and set restricted permissions. To create a MySql user, look here for more information: http://www.mysql.com/doc/en/Adding_users.html. There are various admin-software on the market that makes this easier, like PhpMyAdmin (http://www.phpmyadmin.net/).

Oracle

Install Oracle, and create a database called opinio, and a user called opinio. Make sure that the database supports the character sets you need to use (see Internationalization). Refer to the Oracle documentation for more information about this. If you are only going to use the latin character set, you should not need to change character set settings. It is very important that this is verified before you start using the application, because changing the character set on existing data might lead to unpredictable problems.
Place the Oracle JDBC driver in the Opinio/WEB-INF/lib folder. This driver should come with the Oracle installation. It is called classes12.jar.
Run the script oracle_create.sql on this database, with the opinio user.
Rename the file:

WEB-INF/database.properties

to

WEB-INF/database_derby.properties
Then Rename the file:

WEB-INF/database_oracle.properties

to

WEB-INF/database.properties
Edit this file (WEB-INF/database.properties). The line starting with:

objectplanet.persistence.jdbcURL=

...should read (if you have installed Oracle on another system, replace localhost with the address of this host):

jdbc:oracle:thin:@(description=(address_list=(address=(protocol=tcp)(port=1521)(host=localhost)))(connect_data=(sid=OPINIO)))

Set user name and password to use when connecting to the database:

objectplanet.persistence.user=[user name] objectplanet.persistence.password=[password]
Save the changes you have made to database.properties
Restart your web server

Instructions for other database platforms will be added soon.

Internationalization

It is possible to configure Opinio to support other languages. Opinio comes with English as default language. You can use UTF-8 (Unicode) for most of the languages.

Set database encoding to UTF-8. Examples:
- Apache Derby is a Java based database and supports Unicode natively. No configuration needed.
- Microsoft SQL Server stores Unicode texts by using Unicode data types. Opinio is already using these types, which means that no other configuration is needed.
- Older MySql versions does not support Unicode. But it is possible to configure the JDBC driver to use Unicode when handling texts. You will need to add two parameters to the jdbcURL in WEB-INF/opinio.properties:
  
  objectplanet.persistence.jdbcURL=jdbc:mysql://localhost:3306/opinio?useUnicode=true&characterEncoding=UTF-8
  
  Newer MySql versions support Unicode. Refer to the database documentation for description on how to configure the database server to support UTF-8.
- Other databases. Refer to the database documentation for description on how to configure the database server to support UTF-8
Set system character encoding toUTF-8. System character encoding is the encoding for texts entered in all input fields. It can be set on the Opinio administration screens, go to Setup -> Edit system settings and select "UTF-8" as value for "Character encoding". Save the settings.
Set report chart fonts. Report charts are created on the server and returned as Java generated image. The Java font.properties are used.

The example bellow shows the steps needed to display charts with Chinese characters. If you have UTF-8 font, you can use it instead.
1. Make sure that Chinese font is installed on the server
2. Go to the folder JAVA_HOME\jre\lib
3. Rename font.properties to font.properties.default
4. Rename font.properties.zh_TW_Big5 to font.properties
5. Restart java
You can find some helpful tips on how to edit Java font.properties if you search on the Internet.
Set report PDF fonts

As the name (Portable Document Format) implies, PDF files can be viewed on various platforms and will always look the same. This is partially true because in this format there is a special way of dealing with fonts.

Configuration properties are used to register the fonts to use when generating the Pdf report files. All font styles used in the report template can be configured in the opinio/WEB-INF/classes/jasperreports.properties file. By default the fonts used are the 'Bitstream Vera' fonts located in the opinio/WEB-INF/classes/fonts directory.

# The different font styles used in the pdf jasperreport net.sf.jasperreports.export.pdf.font.ReportTitleFont=fonts/VeraBd.ttf net.sf.jasperreports.export.pdf.font.SubTitleFont=fonts/VeraBd.ttf net.sf.jasperreports.export.pdf.font.TitleFont=fonts/VeraBd.ttf net.sf.jasperreports.export.pdf.font.TextFont=fonts/Vera.ttf net.sf.jasperreports.export.pdf.font.LabelFont=fonts/VeraBd.ttf net.sf.jasperreports.export.pdf.font.ValueFont=fonts/Vera.ttf

The 'Bitstream Vera' fonts does not support all langaguages/character sets in the world (not many do). Say you want to support, for example, Japanese in your Pdf reports, you will then have to change the different font styles listed above to use a font that does support the Japanese language/character set.

Restart the application server after changes to jasperreports.properties file.

Read section "Internationalization of Opinio" in the User Manual for more detailed description.

Clustering setup

Opinio supports clustering, which means you can run multiple instances of Opinio, and run them as one single coherent application. The advantages to this is clear: You can obtain much higher scalability with less powerful servers, and improve availability (if one server goes down, Opinio is still up and running). Note that clustered licenses are required to enable this functionality.

To run Opinio in clustering mode, there are certain requirements:

The application server that Opinio runs on (Tomcat, WebLogic, WebSphere, etc..) must support session replication. Tomcat 5.0 and newer supports this.
You need a license key for each cluster member (Opinio installation) with clustering enabled. This can be purchased at http://www.objectplanet.com/Opinio
A load balancer is needed to distribute load between the cluster members. A load balancer that is session-aware is highly recommended. This means that a user will be routed to the same cluster member on each request for the duration of the session (provided this particular member is up and running the whole time). This feature is sometimes referred to as "stickiness" or "sticky sessions". This will ease the communication between the cluster members, because less information must be communicated, and will put much less stress on the database, because Opinio will be able to make full use of it's internal caching mechanisms.

Follow these steps for installing Opinio with clustering support:

Install a web server that supports Session replication for each cluster member (each computer that will be running Opinio).
Make sure that all web servers in the cluster are within the same network and accept UDP and TCP packets from each other. If communication is restricted between Opinio nodes, cluster members may end up unsynchronized.
Configure the web server for clustering support. This might differ for the individual servers. If you are running Tomcat, it is recommended to make a small change in tomcat's server.xml in addition to the common clustering setup. The <useDirtyFlag> attribute within the <Cluster> tag should be set to false to make sure that session is replicated at all times.
If running Tomcat and a dual IP stack (IPv4 and IPv6) is installed, add this to JAVA_OPTS in catalina.sh/bat:
-Djava.net.preferIPv4Stack=true.
Install/prepare a database for Opinio. The database system should be a scalable and reliable database system. All cluster members will connect to this database, so it should be able to handle all this traffic. The database can quickly become the bottleneck, unless it is running on a powerful server. Some databases support clustering (Oracle, for example). Please note that clustering setup for the database is completely unrelated to the clustering of Opinio.
Synchronize the date and time on all cluster members. The time on all systems should be within 5 seconds of each other. It is possible to use Internet time servers to adjust the time automatically, and keep them synchronized (time.nist.gov for example).
On Linux, make sure a hostname is mapped to the IP address of the server in /etc/hosts. Example:
192.168.0.2 myhost localhost.localdomain localhost
Install Opinio on all cluster members. For instructions to install Opinio on a single system, see Installation.
Edit the file opinio/WEB-INF/web.xml and uncomment the <distributable/> tag.
Now you need to set license key for all cluster members. To get a license key you will need Host id from each Opinio installation. Get the host id by going to each installation directly (not through the load balancer), and click on "Setup -> Manage Licenses". Contact ObjectPlanet at: http://support.objectplanet.com/esupport/ to get the license key.

Set license key for all cluster members:
- Stop all cluster members.
- Start one cluster member. Go to Setup -> Manager Licenses
- Set license key for the started installation and save
- Since license key for the current installation activates clustering, you will now be able to set licenses for other cluster members from here. Click on Manage Licenses again.
- Enter HostId, IP address and license key for all cluster members.
Set up the load balancer. Refer to the load balancer documentation on how to configure it.
Set the load balancer's base address as System base URL (so that Opinio knows how to produce the Survey URLs etc..). To do so, login to Opinio (any of the Opinio installations), and click on "Setup" in the main menu. The System base URL can look like this: http://[LOAD_BALANCER_ADDRESS]/opinio
Restart all cluster members. Start one system first, and wait for at least 3 minutes to start the remaining members. This is to make sure database upgrades will be performed properly. Opinio will always check the database and upgrade it automatically if needed. Only one Opinio installation should be performing this task at any time. It is not necessary to start one cluster member alone initially every time the cluster is restarted. Only after an Opinio upgrade will this be necessary.
Check that all cluster members can be accessed by Opinio. Access one of the cluster members and go to Manage Licenses. Click on "Test IP-based system URL".
When a new cluster member is added (or restarted), it tries to download the uploaded files not existing locally from other cluster members. This will cause a lot of traffic if the amount of files are large, hence it is recommended to copy the upload folder from an existing cluster member to the new cluster member. This might not be necessary if a cluster member has been down only for a small period of time, and the amount of new uploaded files are insignificant.

Upgrade

Opinio comes with automatic database upgrade for the supported databases. This means that Opinio will automatically detect the database version, and make the necessary upgrades.

Follows the instructions for Opinio upgrade. If you are running in clustering mode (multiple instances of Opinio) - remember to upgrade all cluster members. All cluster members must be stopped before upgrade begins.

Make full backups of the Opinio folder and the database. If you are running another database than the embedded Apache Derby, refer to the documentation of your database platform for more information about backups. This step should not be skipped.
Stop the application server.
Move the opinio folder out of the webapps folder of your application server (Tomcat or other). Keep this as backup for now.
Place the opinio.war file in the webapps folder, and restart your application server.
If you upgrade from Opinio 4 or 5 to Opinio 6 or 7:

In Opinio 6.0, the database connection properties have been moved out to a separate file named database.properties.
- Copy the database connection properties from your old opinio.properties file to the database.properties on the new installation.
- New system properties (called "Global Opinio properties" in the old opinio.properties file) have been added in version 6. Override the same properties in the new installation with the values from the old opinio.properties.
- Change the new properties if needed for you installation. See System settings.
Edit the opinio/WEB-INF/opinio.properties file, if this file was edited after the original installation (if you are using another database than the built-in Derby database, for example) to reestablish the database connection. If you copy the properties file from your old installation, make sure to include any new properties in this file. New properties are sometimes added in new versions.
If you upgrade from Opinio 6 to a later version:
- If you are using another database than the built-in Derby, copy the database.properties file from your old installation to the new one to reestablish the database connection.
- New system properties are sometimes added in new versions to opinio.properties file. Copy the existing properties from the old opinio.properties file to the new opinio.properties file. Change the new properties if needed for you installation. See System settings.
If you upgrade to Opinio 7 and you have created custom survey templates:
The html code has changed slightly, and the form might now be left-aligned. If you need to have the form centered horizontally, add the following code to your css file:

#page-div {
margin-left: auto;
margin-right: auto;
}
If you are using another database than the built-in Derby database copy the JDBC driver to the new installation (Opinio/WEB-INF/lib folder).
Copy the upload folder of your old Opinio installation to your new installation. Make sure it is located under the Opinio top folder.
For Apache Derby users: If you are using the built-in database (Apache Derby) in embedded mode, then you must also copy the database files from the old installation, to the newly installed version. Copy the folder opinio/WEB-INF/data/derbyDB to the new installation (overwrite the files). It is the embedded mode which is the default. If you have changed the configuration to run Apache Derby in server mode, and you are not running it from the folder where Opinio is installed, there is no need to copy the database files, because they are not replaced by the upgrade. Opinio will then take care of the upgrade automatically, by adding/modifying the the database structure for the new version.
Restart the application server. If you are running multiple instances of Opinio in clustering mode, remember to start one server first to perform automatic database upgrades.
If you are using Oracle database, connect to the database and check that all indices are valid. Rebuild invalid indices.
Open log files in opinio/WEB-INF/log and confirm that database upgrade was completed. The database upgrade was successful when you see statement "Opinio database upgrade completed." in the log file.
You can also go the system monitoring page at http://server-address/opinio/admin/sys.do to see the current system status.
Your new version is now installed, and the database is updated for the new version. If you are running multiple instances of Opinio in clustering mode, you can now start the remaining cluster members.

Requirements

Tomcat installation

Using other database platforms

Internationalization

System settings

Clustering setup

Upgrade

Uninstall