installation.ad

== Installation

SymmetricDS at its core is a web application.  A SymmetricDS instance runs within the context of a web application container 
like Jetty or Tomcat, and uses web based protocols like HTTP to communicate with other instances.  

An instance has one of the following installation options:

. *<<Standalone Installation>>* - SymmetricDS is installed and run as a standalone process using the built-in
Jetty web server.  This is the simplest and recommended way to install an instance.  

. *<<Web Archive (WAR)>>* - A SymmetricDS web archive (WAR) file is deployed to an existing web application container that is
separately installed, maintained and run.    

. *<<Embedded>>* - SymmetricDS is embedded within an existing application.  In this option, a custom wrapper program is
written that calls the SymmetricDS API to synchronize data.

=== Standalone Installation

ifndef::pro[]
The SymmetricDS standalone ZIP file can be downloaded from https://sourceforge.net/projects/symmetricds/files[Sourceforge].  
It is installed by unzipping to the installation location.

The `sym` command line utility starts a standalone instance of SymmetricDS using
the built-in Jetty web server to handle requests.
The web server can be configured by changing properties in the
`conf/symmetric-server.properties` file.
           
The following example starts the server on the default port from the command line.  SymmetricDS will automatically create a node for each  
<<Node Properties File>> configured in the engines directory.
            
[source, cli]
----
bin/sym
----

To automatically start SymmetricDS when the machine boots, see <<Running as a Service>>.

endif::pro[]

ifdef::pro[]
The SymmetricDS installer is an executable jar file named *symmetric-pro-<version>-setup.jar*.  
In order to run the installer, you must have the Java Runtime Environment (JRE)
version 6.0 or newer installed.
Start the installer by _double-clicking_ it (if the JRE is in your path and associated with .jar files),
or by running it from a command prompt, like this:

`java -jar symmetric-pro-<version>-setup.jar`

The default installation will run in graphical mode, but it can also be run from a command window by
adding the `-console` argument on the end of the command.

[.float-group]
--
[.left.text-left]
image::install/install-first.png[]

The first screen is a Welcome screen that includes the SymmetricDS Pro version number.
The installer will ask a series of questions before writing files to disk.

To begin selecting installation options, click *Next*.

--

[.float-group]
--
[.left.text-left]
image::install/install-second.png[]

Specify whether you want to install a new version of SymmetricDS for the first time 
(_Install new software_) or upgrade an existing version of SymmetricDS that was previously installed 
(_Upgrade existing software_).  For upgrade, the existing installation of SymmetricDS or
SymmetricDS Pro is verified before continuing.

Select the appropriate option and click *Next*.

--

[.float-group]
--
[.left.text-left]
image::install/install-third.png[]

Carefully read the SymmetricDS Pro License Agreement.

If you accept, select _I accept the terms of this license agreement_ and click *Next*.

--

[.float-group]
--
[.left.text-left]
image::install/install-fourth.png[]

Choose the installation path where SymmetricDS will either be installed or upgraded.
If the directory does not already exist, it will be created for you.  Make sure your user has permission
to write to the file system.

After entering the directory path, click *Next*.

--

[.float-group]
--
[.left.text-left]
image::install/install-fifth.png[]

Select the packages you want to install and verify disk space requirements are met.
By default, all packages are selected.  If you are NOT integrating 
SymmetricDS with Android, you can unselect the Android package.

After selecting packages, click *Next*.

--

[.float-group]
--
[.left.text-left]
image::install/install-sixth.png[]

A standalone installation can either be run automatically by the system or manually by the user.
Select the _Install service to run automatically_ checkbox to install a Windows service or Unix daemon that will
start SymmetricDS when the computer is restarted.  The service can installed or uninstalled later using
the Control Center or command line (see <<Running as a Service>>).

Select the _Run server after installing_ checkbox to also run SymmetricDS after installation so it can be used immediately.

After selecting options, click *Next*.

--

[.float-group]
--
[.left.text-left]
image::install/install-seventh.png[]

For standard synchronization and web console access over HTTP, select the _Enable HTTP_ checkbox.
For encrypted synchronization and web console access over HTTPS, select the _Enabled SSL_ checkbox.

The Java Management eXtensions (JMX) are a set of server properties and operations that can be used to manage the server.
To enable a simple web console for JMX, select the _Enable JMX_ checkbox.
To enable remote access for JMX clients like JConsole and `bin/jmx`, select the _Enable JMX Agent_ checkbox.

After selecting options and specifying unused ports, click *Next*.

--

[.float-group]
--
[.left.text-left]
image::install/install-eigth.png[]

Confirm your installation settings and click *Next* to begin the installation.

--

[.float-group]
--
[.left.text-left]
image::install/install-ninth.png[]

After SymmetricDS finishes installing, click *Next*.

--

[.float-group]
--
[.left.text-left]
image::install/install-tenth.png[]

If you chose the option for the server to start after installation, wait for it to start and then click *Next*.

--

[.float-group]
--
[.left.text-left]
image::install/install-eleventh.png[]

The installation is now complete.  Choose if you want to open the SymmetricDS Pro Control Center where
you can view the server status and open a web console.

Click *Done* to exit the installer.

--

[.float-group]
--
[.left.text-left]
image::install/install-twelth.png[]

From the SymmetricDS Pro Control Center, 
you can start/stop the server, open the web console, and install/uninstall the service.

To begin configuration of SymmetricDS, check that the server is running, and then click *Open Web Console*.  

--

To continue setup and configuration of SymmetricDS, refer to the <<Setup>> section.

endif::pro[]

=== Running as a Service
   
SymmetricDS can be configured to start automatically when the system boots, running as a Windows service or Linux/Unix daemon.
A wrapper process starts SymmetricDS and monitors it, so it can be restarted if it runs out of memory or exits unexpectedly.
The wrapper writes standard output and standard error to the `logs/wrapper.log` file.

ifdef::pro[]
For SymmetricDS Pro, you may have already installed as a service, so this section will show you how to manually install
the service from command line.
endif::pro[]

==== Running as a Windows Service
       
To install the service, run the following command as Administrator:

[source, cli]
----
bin\sym_service.bat install
----

Most configuration changes do not require the service to be re-installed.
To uninstall the service, run the following command as Administrator:

[source, cli]
----
bin\sym_service.bat uninstall
----
   
To start and stop the service manually, run the following commands as Administrator:
[source, cli]
----
bin\sym_service.bat start
bin\sym_service.bat stop
----

==== Running as a Linux/Unix daemon
       
An init script is written to the system `/etc/init.d` directory.
Symbolic links are created for starting on run levels 2, 3, and 5 and stopping on run levels 0, 1, and 6.
To install the script, running the following command as root:
[source, cli]
----
bin/sym_service install
----
   
Most configuration changes do not require the service to be re-installed.
To uninstall the service, run the following command as root:
[source, cli]
----
bin/sym_service uninstall
----
   
To start and stop the service manually, run the following commands:
[source, cli]
----
bin/sym_service start
bin/sym_service stop
----
    
=== Clustering
       
A single SymmetricDS node may be clustered across a series of instances, creating a web farm.  A node might be clustered to provide load balancing and failover, for example.

When clustered, a hardware load balancer is typically used.  

For clustered nodes running SymmetricDS 3.8 and later the recommended approach is to configure the load balancer to use sticky sessions or ensure the staging directory for all nodes in the cluster are using a shared network drive. 

For clustered nodes running SymmetricDS 3.7 and earlier it is recommended to round robin client requests to the cluster and configure the load balancer for stateless connections.

ifndef::pro[]
Also, the `sync.url` (discussed in <<Node Properties File>>) SymmetricDS property should be set to the URL of the load balancer.
endif::pro[]

ifdef::pro[]
Also, the `sync.url` (discussed in <<Registration URL>>) SymmetricDS property should be set to the URL of the load balancer.
endif::pro[]
   
If the cluster will be running any of the SymmetricDS jobs, then the `cluster.lock.enabled` property should be set to `true`.
By setting this property to true, SymmetricDS will use a row in the <<LOCK>> table as a semaphore to make sure that only one instance at a time
runs a job.  When a lock is acquired, a row is updated in the lock table with the time of the lock and the server id of the locking job.  The lock time is set back to null
when the job is finished running.  Another instance of SymmetricDS cannot acquire a lock until the locking instance (according to the server id) releases the lock.  If an
instance is terminated while the lock is still held, an instance with the same server id is allowed to reacquire the lock.  If the locking instance remains down, the lock can be
broken after a period of time, specified by the `cluster.lock.timeout.ms` property, has expired.  Note that if the job is still running and the lock
expires, two jobs could be running at the same time which could cause database deadlocks.
   
By default, the locking server id is the hostname of the server.  If two clustered instances are running on the same server, then the `cluster.server.id` property
may be set to indicate the name that the instance should use for its server id.
   
When deploying SymmetricDS to an application server like Tomcat or JBoss, no special session clustering needs to be configured for the application server.
    
=== Other Deployment Options

It is recommended that SymmetricDS is installed as a standalone service, however there are two other deployment options.

==== Web Archive (WAR)
           
           
This option means packaging a WAR file and deploying to your favorite
web server, like Apache Tomcat.  It's a little more work, but you
can configure the web server to do whatever you need.  SymmetricDS can also
be embedded in an existing web application, if desired.  As a web application archive, a WAR is deployed to an application server,
such as Tomcat, Jetty, or JBoss.  The structure of the archive will have a `web.xml`
file in the `WEB-INF` folder, an appropriately configured `symmetric.properties` file in the `WEB-INF/classes` folder,
and the required JAR files in the `WEB-INF/lib` folder.

.War
image::symmetric_war.gif[]

A war file can be generated using the standalone installation's `symadmin` utility and the
`create-war` subcommand.  The command requires the name of the war file to generate.  It
essentially packages up the web directory, the conf directory and includes an optional
properties file.  Note that if a properties file is included, it will be copied to
WEB-INF/classes/symmetric.properties.  This is the same location conf/symmetric.properties
would have been copied to.  The generated war distribution uses the same web.xml as the standalone
deployment.
            
[source, cli]           
----
bin/symadmin -p my-symmetric-ds.properties create-war /some/path/to/symmetric-ds.war
----

==== Embedded
           
This option means you must write a wrapper Java program that runs
SymmetricDS.  You would probably use Jetty web server, which is also embeddable.
You could bring up an embedded database like Derby or H2.  You could configure the
web server, database, or SymmetricDS to do whatever you needed, but it's also
the most work of the three options discussed thus far.
   
The deployment model you choose depends on how much flexibility you need versus how easy you
want it to be.  Both Jetty and Tomcat are excellent, scalable web servers that
compete with each other and have great performance.  Most people choose either
the _Standalone_ or _Web Archive_ with Tomcat 5.5 or 6.  Deploying to Tomcat
is a good middle-of-the-road decision that requires a little more work for more flexibility.

A Java application with the SymmetricDS Java Archive (JAR) library on its
classpath can use the `SymmetricWebServer` to start the server.
            
[source, java]
----
import org.jumpmind.symmetric.SymmetricWebServer;

public class StartSymmetricEngine {

    public static void main(String[] args) throws Exception {

        SymmetricWebServer node = new SymmetricWebServer(
                                   "classpath://my-application.properties", "conf/web_dir");

        // this will create the database, sync triggers, start jobs running
        node.start(8080);

        // this will stop the node
        node.stop();
    }
----
           
This example starts the SymmetricDS server on port 8080.
The configuration properties file, `my-application.properties`,
is packaged in the application to provide properties that override the SymmetricDS
default values.  The second parameter to the constructor points to the web directory.
The default location is `web`.  In this example the web directory is located
at `conf/web_dir`.  The web.xml is expected to be found at `conf/web_dir/WEB-INF/web.xml`.