Installing and updating OpenSyncroOpenSyncro 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.
Before installationBefore you can start the installation, you need to have the following
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.
The installation processThis 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
Creating a new OpenSyncro databaseIn 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"
mysql> CREATE DATABASE opensyncro_test DEFAULT CHARACTER SET utf8;
Query OK, 1 row affected (0.01 sec)
Initializing/updating an OpenSyncro databaseFor 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
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
<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
When updating OpenSyncro, see
Installation/mysql/updates directory for further instructions
for existing OpenSyncro database upgrade procedure.
Setting database connection parameters for OpenSyncroOpen 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.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
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
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
Adding JDBC database driver to Tomcat's Java classpathCopy MySQL connector JAR file, e.g.
"shared/lib/" (or "lib/" in Tomcat 6)
subdirectory under Tomcat's installation directory.
Installing and updating OpenSyncro web application packageCopy 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
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.
Installing and updating external componentsOpenSyncro 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
component.dir = /path/to/component/directoryWhere
"/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.
Restricting OpenSyncro web application's access with a security
policyFor 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.
Running multiple instances of OpenSyncro in the same application
serverOpenSyncro 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 filename||Properties filename
|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
Testing the installation and troubleshootingStart 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
: 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:
- a problem with OpenSyncro's database connection: specified database cannot
be found on the server or OpenSyncro is unable to connect to database server
- OpenSyncro might be unable to find "opensyncro.properties" file (see step
- login username and/or password might be wrong (default: "user" /
- On "opensyncro.properties" file's "parameter.name = parameter.value" lines
there are extraneous space characters at the end of the line,
after the parameter value. OpenSyncro includes these tailing spaces into the
parameter value and thus may be unable to load the JDBC driver class, connect
or log in to the database and so on.
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