Installing Pervasync Server

There is only one Pervasync server package that you can download from Pervasync web site. The single server package can work with both Oracle and MySQL databases. Once the Pervasync server is up and running, users can download sync clients from the start page of the server web application.

The installation process includes un-packing and setting up.

 

Getting and Un-Packing Pervasync Server Distribution

The latest and greatest version of Pervasync server is available on the Pervasync products web page at:

http://www.pervasync.com/products.

Download the server zip file, e.g. pervasync_server-4.0.0.zip, and save it on your server computer.

To install Pervasync server, choose a directory and un-pack the zip file there. For example, the following commands un-pack the server distribution and create sync server home /pervasync_server-4.0.0 on a Linux/Unix machine.

cd /

unzip pervasync_server-4.0.0.zip

 

On Windows platform, replace “/” with “\”. By the way the sync home doesn’t have to be under the top most root directory.

NOTE: Perform the setup as the user that will run the web container for Pervasync server. For example, if you run Tomcat on Linux as user tomcat, you should do the Pervasync server setup as user tomcat. If you do the setup as super user (e.g. root), you should change the ownership of the Pervasync server tree to tomcat at the end of the setup.

A Pervasync server home has the following directory layout:

pervasync_server-4.0.0

|

+— bin // contains executables.

|

+— classes // contains Pervasync java classes

|

+— config // contains configurations files

|

+— demo // contains demo apps

|

+— doc // contains documentation

|

+— install // contains scripts for setup, un-install etc.

|

+— lib // contains library jars

|

+— web // contains server web app

|

+— README.txt // the readme file

NOTE: You may encounter file permission issues on Windows 7 and Linux if you create un-pack the Pervasync home with an admin/root user account and later on setup or run the server with a non-admin user account. The reason is that at runtime, Pervasync needs to write some internal files so it has to have write permission to the home folder. The solution is to grant the runtime user FULL CONTROL of the Pervasync home. Better yet, make the runtime user the owner of the home.

Pervasync Server System Requirements

Before you run the setup program to setup the server, make sure you have the following ready.

Database Engines and JDBC Drivers

Pervasync server supports

  • MySQL version 5.0.2 or newer and
  • Oracle database version 8.1.7 or newer.

Get Oracle database products from Oracle:

http://www.oracle.com/technology/software/products/database/index.html

and MySQL database products from MySQL/Oracle:

http://dev.mysql.com/downloads/

Install the desired database engine. Make sure your database is up and the appropriate JDBC driver is available.

You need JDBC drivers for Pervasync server to communicate with the database engine. You need ojdbc5.jar or ojdbc6.jar for Oracle and mysql-connector-java-5.x.x-bin.jar for MySQL. You can download an Oracle JDBC driver (e.g. ojdbc5.jar or ojdbc6.jar) from Oracle:

http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html

and a MySQL Java connector (e.g., mysql-connector-java-5.x.x-bin.jar) from MySQL/Oracle:

http://dev.mysql.com/downloads/connector/j/.

Copy the JDBC driver (the JDBC jar files) to the lib directory under Pervasync server home. Pervasync server home is the Pervasync directory where the README.txt resides.

NOTE: If you run Oracle for central DB, you only need Oracle JDBC driver jar. If you run MySQL, you only need MySQL Java connector jar.

Java Platform

The sync server and sync client are written in pure Java and can be installed on Windows, Linux and Mac OS X platforms that have a Sun JDK version 1.6 or newer installed.

Get the latest JDK from Oracle:

http://www.oracle.com/technetwork/java/javase/downloads/index.html

Install JDK on server host following the instructions.

NOTE: Pervasync server requires Sun JDK. It may not be able to work with pre-installed OpenJDK or gcj on Linux. Refer to the appendixes of this guide on steps of installing standalone Sun JDK on Linux. Instructions are also available in appendixes for installing JDK on Windows.

NOTE: Open a new shell window and run “java –version” on the command line to make sure the newly installed JDK is taking effect. Sample output:

java version “1.6.0_17”

Java(TM) SE Runtime Environment (build 1.6.0_17-b04)

Java HotSpot(TM) Client VM (build 14.3-b01, mixed mode, sharing)

If the old JDK or non-Oracle/Sun JDK is still taking effect, check the PATH env variable to make sure the bin dir of the new JDK is on the front.

Servlet/JSP Containers or Application Servers

To setup Pervasync server, you have to install a Java servlet container, e.g. Apache Tomcat. The sync server includes a standard J2EE servlet app, which needs to be deployed on an application server or a J2EE container. You may use whatever containers you prefer, but the following containers are recommended for the sync server:

Install one of the servlet containers on server host following the instructions.

NOTE: Pervasync server requires Tomcat 6 and cannot work with pre-installed Tomcat 5 on Linux. Refer to the appendix of this guide on steps of installing standalone Tomcat 6 on Linux and installing Tomcat as a service on Windows.

Setting up the Sync Server Using the Pervasync Server Setup Tool

NOTE: There are two ways setting up the sync server, a GUI way and a command-line scripts way. This section describes the GUI way. See section 4.1.4 for steps to use the non-GUI setup scripts in folder “install” to set up the server.

The pvs.sh (or pvs.bat for Windows) program in the “bin” folder is the entry point to the Pervasync Server Setup Tool for setting up the server. If you have a hosted sever and can only access the server via a text based telnet or ssh window, the program won’t run. However, it is not difficult to set up a graphic remote desktop to the server. For example, you could use VNC. See http://www.realvnc.com/support/getting-started.html for details.

NOTE: Optionally you may want to edit the conf files located in the config directory. Some of the configurations, such as pervasync.server.db.user.options and pervasync.server.db.user.grants, affect setup as well as server runtime. If you do edit the conf file, do it before you launch the Setup Tool GUI so that the new settings can take effect.

Launching the Pervasync Server Setup Tool

To launch the Pervasync Server Setup Tool, change directory to the “bin” folder of Pervasync server home and invoke “pvs.bat” for Windows or “pvs.sh” for Linux. A GUI window will pop up asking the database type of your central DB.

NOTE: If you see the following error, most likely you are using a Java version older than JDK 6. Download and setup JDK 6 or newer.

In the DB type dialogue window, select MYSQL or ORADB (for Oracle databases) and click OK. Then you will be presented with the main window with a Setup tab.

Use the “Setup” tab to setup the sync server. Carefully examine all the input fields and fill in proper values. Fields that have an asterisk (*) next to their names are required to be filled. Some fields are made read-only and you normally shouldn’t change them. If you do need to change their values, click “Advanced Mode” on the top right corner. See next section for descriptions of the fields.

TIP: Move mouse cursor over a field input box to show the description of the field (tooltip).

 

Central DB Connection Properties

Sync server needs a Pervasync admin schema to store its metadata. To create that schema, the database root/system user name and password are needed. The top panel of the setup screen is for the database connection. Listed below are the explanations of text boxes of the GUI:

Pervasync Web App Deployment

The bottom panel of the setup screen is for Pervasync web app deployment. The web folder in Pervasync server home folder contains a standard J2EE web app for the sync servlet and admin console. The web app can be deployed into any J2EE containers. If you select Tomcat as the container, the web app will be automatically deployed to Tomcat during setup. Otherwise, you need to deploy it yourself following the specific web container’s deployment instructions.

If you select Apache Tomcat, you need to click “Locate Tomcat Home“, then browse and find Tomcat Home directory.

NOTE: If you install a standalone Tomcat server and all the sub-folders such as conf and bin are under a same root folder, the root folder is the Tomcat Home. However if Tomcat is installed using one of the Linux distribution packages, Tomcat sub-folders may be installed in different places. For example, conf, webapps and log sub-folders may be put in /var/lib/tomcat6, while bin and doc are put in /usr/shared/tomcat6. In this case, use the root folder that contains the conf sub-folder as Tomcat Home, i.e. /var/lib/tomcat6.

Performing Setup

Now, simply click “Setup” button to start the setup process, which will do the following:

  1. Set up the sync server home.
  2. Create the sync server admin user/schema in the database if it does not exist; or upgrade the schema if already exits.
  3. Deploy the sync server web application if you select Tomcat as the servlet container.

NOTE: Do not move or remove the sync server home after setup.

NOTE: You could setup multiple sync server instances on different machines. All these sync servers share one and only one sync server DB user. To set up a new instance, repeat the setup on a new host machine.

Once the setup completes successfully and the Pervasync web application is properly deployed, you can access the start page of the Pervasync server web at:

http://<server>:<port>/pervasync, e.g. http://localhost:8080/pervasync

If you see the Pervasync web app start page like that showing below, then your sync server setup has been successful. Congratulations!

Use Pervasync Admin User and Admin Password you specified in the GUI of server setup to login to the web based admin console after which you can publish central database tables and create sync users.

On the same Pervasync start page there is a link to the Java based sync client for end users to download.

NOTE: Users do not need to login to the web based admin console to download the sync client.

If your Internet Browser cannot display the web page, or it can’t establish a connection to the server, then you need to check your servlet container (e.g. Tomcat) to see whether or not it is started. If your servlet container is up but Pervasync is still not available, first check the log files of your servlet container (e.g. files inside the logs folder of Tomcat home) and then the log files in the log folder of Pervasync home to see if there are error messages.

NOTE: You may need to re-start your servlet container after the web app deployment.

If you see an AccessControl exception like the following, then your Tomcat has a security manager on.

SEVERE: Exception starting filter accessControl

java.lang.RuntimeException: java.security.AccessControlException: access denied (java.io.FilePermission /opt/pervasync/config read)

Locate your Tomcat startup script and remove “-security” and then restart Tomcat.

 

Updating Server Settings

If you need to change Pervasync server admin user password etc. after you have configured Pervasync server, you can go to the “bin” folder and invoke “pvs.bat” for Windows or “pvs.sh” for Linux. The setup main screen will pop up. You can make changes and click “Update”.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s