2 - Installing and updating OpenSyncro

OpenSyncro is delivered as two separate ZIP archives: "install" and "source". For installing, deploying and updating OpenSyncro, only the "install" ZIP archive is needed. It contains the OpenSyncro web application package ("opensyncro.war"), an example configuration file ("opensyncro.properties"), two alternative database dump files ("opensyncro_demodb.sql" or "opensyncro_emptydb.sql") for initializing a new OpenSyncro database, and installation/upgrading instructions.

2.1 - Before installation

Before you can start the installation, you need to have the following software installed:


OpenSyncro should also run on servlet standard compliant application servers other than the Apache Tomcat, when the webapp and configuration files are copied to an equivalent path of, for example, JBoss 4.0 or Jetty 6.

2.2 - The installation process

This chapter goes through the installation process step-by-step. If you are installing OpenSyncro for the first time, check that the database server is online and start at step 2.2.1. For updating a previous OpenSyncro installation, you should see step 2.2.2 and then proceed to step 2.2.5.

The installation process begins with creating and initializing a dedicated database for OpenSyncro. Then, OpenSyncro needs a couple of parameters for the database connection. These parameters are located in OpenSyncro's configuration file called "opensyncro.properties".

2.2.1 - Creating a new OpenSyncro database

In MySQL, enter the database console with sufficient privileges to create a new database, e.g. "mysql -u root". In the database console, enter "CREATE DATABASE opensyncro_test DEFAULT CHARACTER SET utf8;" (without the double quotes) if you are running MySQL 5.0, or "CREATE DATABASE opensyncro_test;" if your MySQL version is 4.0. Here, opensyncro_test is the name of the database to be created and utf8 is our recommendation for the character encoding to be used in OpenSyncro's database (MySQL 5.0+ only).

There are no special restrictions regarding the database's name, as long as no other database already exists under the same name. If database was created successfully, MySQL should reply with "Query OK, 1 row affected". Finally, exit the database console with "exit" command.
mysql> CREATE DATABASE opensyncro_test DEFAULT CHARACTER SET utf8;
Query OK, 1 row affected (0.01 sec)

mysql> exit
Bye

2.2.2 - Initializing/updating an OpenSyncro database

For initializing the database created in the previous step, you have a choice of two database dump files: "opensyncro_emptydb.sql" and "opensyncro_demodb.sql", both located in the directory "Installation/mysql/initialization/". The dump files contain series of SQL statements to be executed by the database. The first dump file ("opensyncro_emptydb.sql") creates an empty database and an initial user account ('user') to log in with. The second dump file ("opensyncro_demodb.sql") is basically the same as the first one, but adds a couple of example integration processes (Pipes) for testing and learning OpenSyncro.

For the first installation of OpenSyncro, we recommend choosing the "opensyncro_demodb.sql" dump. On MySQL 5.0 the initialization can be done by running "mysql -u root --default-character-set=utf8 opensyncro_test <opensyncro_demodb.sql" from command prompt, in the "Installation/mysql/initialization/" directory. On MySQL 4.0 enter "mysql -u root opensyncro_test <opensyncro_demodb.sql" instead. If the initialization is successful, mysql command should not output any messages.
user@host:~/initialization$ mysql -u root --default-character-set=utf8 opensyncro_test <opensyncro_demodb.sql
user@host:~/initialization$
When updating OpenSyncro, see Installation/mysql/updates directory for further instructions for existing OpenSyncro database upgrade procedure.

2.2.3 - Setting database connection parameters for OpenSyncro

Open the OpenSyncro configuration file "opensyncro.properties" from "Installation/tomcat5/shared/classes/smilehouse/conf/" in a text editor. The file contains lines with "parameter name = value" pairs accompanied by explanatory comments. When using MySQL, you only need to specify jdbc.user and jdbc.password. jdbc.user specifies the database username and jdbc.password the database user's password to be used by OpenSyncro. jdbc.uri needs to be modified only if MySQL has not been installed to the same PC as Tomcat and OpenSyncro. Also verify that log.filename points to an existing directory. charset.database should be assigned the same character encoding that you used to create the OpenSyncro database.
# OpenSyncro application properties file.
# Shortened version with minimum set of configuration parameters.

jdbc.driver = com.mysql.jdbc.Driver
jdbc.user = root
jdbc.password =
jdbc.uri = jdbc:mysql://localhost/
charset.web = UTF-8
charset.database = UTF-8
log.filename = /var/log/opensyncro-log.txt
Copy the edited "opensyncro.properties" file to path "shared/classes/smilehouse/conf/" (or "lib/smilehouse/conf/" in Tomcat 6) under Tomcat installation directory.

If you are installing OpenSyncro on application server other than Tomcat and the equivalent path is not available by default, there is always an option to copy the "opensyncro.properties" file under the directory extracted from "opensyncro.war" package (see "Installing and updating OpenSyncro web application package"), for example "webapps/opensyncro/WEB-INF/classes/smilehouse/conf/opensyncro.properties".

Note: The "opensyncro.properties" file may additionally contain a list of databases which OpenSyncro should check for pending Pipe execution requests at startup. Information about enabling this feature is provided in chapter "Pipe Execution Queue".

2.2.4 - Adding JDBC database driver to Tomcat's Java classpath

Copy MySQL connector JAR file, e.g. "mysql-connector-java-5.0.4-bin.jar" to "shared/lib/" (or "lib/" in Tomcat 6) subdirectory under Tomcat's installation directory.

2.2.5 - Installing and updating OpenSyncro web application package

Copy the OpenSyncro web application package file "opensyncro.war" located in "Installation/tomcat5/webapps/" to "webapps/" subdirectory under Tomcat installation directory. When updating, stop the OpenSyncro webapp in Tomcat first, then replace "webapps/opensyncro.war" with a new version of the file, delete the "webapps/opensyncro/" directory (if it exists) and finally restart the OpenSyncro webapp.

This completes the basic OpenSyncro installation. If you don't have any external OpenSyncro components to install, you are ready to test your installation by following the instructions in chapter 2.3.

2.2.6 - Installing and updating external components

OpenSyncro can be extended by adding components to an existing installation. Components for connecting to various ERP systems are available for purchase from Smilehouse Oy. The basic OpenSyncro installation does not require any external components. If you haven't purchased external components, you can skip to chapter 2.3.

External Dynamic Components are Java archives (.jar files), whose location is specified with "component.dir" property in the opensyncro.properties file (see step 2.2.3). To inform OpenSyncro of the external component location, append a new line to opensyncro.properties:
component.dir = /path/to/component/directory
Where "/path/to/component/directory" is the full path to the directory containing the component .jar files. After modifying opensyncro.properties, restart OpenSyncro (or Tomcat). Now the new components should be listed on the Component manager page (see chapter 3.2) and are ready for use.

The OpenSyncro installation with external components is now complete. The next chapter provides instructions for testing the installation and some troubleshooting advice.

2.2.7 - Restricting OpenSyncro web application's access with a security policy

For added security it is recommended to allow OpenSyncro web application to access only the resources necessary for successful execution of the intended integration tasks. This can be accomplished by running OpenSyncro's servlet container (Tomcat) on an operating system user account with limited privileges. Another, complementary way would be to configure a security policy to the servlet container.

OpenSyncro distribution includes an example Tomcat "catalina.policy" file for restricting the web application's access to minimal filesystem and network resources. The file is located in "Installation/tomcat5/conf/" directory.

Before copying or merging the security policy file to "conf/catalina.policy" under Tomcat's installation directory, you will need to edit the file and update references to filesystem paths and network sockets according to your server environment. OpenSyncro related lines in the policy file are marked with comments explaining the purpose of each granted permission.

2.2.8 - Running multiple instances of OpenSyncro in the same application server

OpenSyncro supports running multiple instances of the web application on the same server. If you place several copies of OpenSyncro WAR file under Tomcat's webapps/ directory, the opensyncro.properties filenames are generated as follows:


Webapp filenameProperties filename
opensyncro.waropensyncro.properties
anotheropensyncro.waros_anotheropensyncro.properties
123.waros_123.properties
Table 2.1 : Webapp to properties filename mapping

If the OpenSyncro WAR filename is anything else than the default "opensyncro.war", its properties file name will be the WAR filename prefixed with "os_".

2.3 - Testing the installation and troubleshooting

Start Tomcat and point your web browser to "http://localhost:8080/opensyncro/Login" (assuming that Tomcat is running in port 8080). If installation step 2.2.5 was successful, you should see a OpenSyncro Login page asking for database name, user name and password. Log in to the OpenSyncro database you've created ("opensyncro_test") with username "user" and password "password". If "OpenSyncro - All Pipes" page shows up, the installation has been successful.
Picture 2.1 : OpenSyncro Login prompt




In case a "Login failed" dialog is displayed after clicking the "Login" button - or an HTTP error #500 page is displayed, it might be due to one of the following reasons:


The reason can be found in the OpenSyncro's log file, or in the Tomcat output console if there has been a problem with the log file itself (see step 2.2.3, "log.filename" in "opensyncro.properties"). A list of most common installation problem related log file messages with their explanations follows:
Log message: Couldn't get database connection: java.sql.SQLException: General error message from server: "Unknown database 'opensyncro_test'"
Explanation: Database is not found, see installation step 2.2.1

Log message: OpenSyncro: Cannot find file "opensyncro.properties" in classpath, startup failed.
Explanation: OpenSyncro is unable to load its settings from "opensyncro.properties" file, see step 2.2.3

Log message: OpenSyncro: Couldn't get environment information, startup failed.
Explanation: JDBC database driver can not be found by Tomcat (OpenSyncro), see step 2.2.4

Log message: Couldn't get database connection: java.sql.SQLException: No suitable driver
Explanation: jdbc.uri value in opensyncro.properties might be missing the last '/' (slash) character, see step 2.2.3