[[TOC]]
= Synchronization =

== Purpose ==

== Method ==

=== Overview ===

The synchronization process is controlled entirely by the ''local'' Sahana Eden instance.

The local Eden instance runs the scheduler process, and initiates the update requests when due, while the ''remote'' repository merely responds to these requests.

[[Image(sync1.png)]]

The local Eden instance first downloads the available updates from the remote repository ('''pull''') and imports them into the local database, and then uploads all available updates from the local database to the remote repository ('''push''').

Both ''pull'' and ''push'' are each a RESTful HTTP-request, using S3XML as data format.
== Configuration ==

=== Prerequisites ===

Both sites must have Sahana Eden installed and running. To avoid problems with different database structures, both Sahana Eden instances should always use the same version of the software.

While performing synchronization jobs, the ''local'' site must be able to establish a connection to the ''remote'' site over the network using HTTP. 

If a proxy server is to be used for the HTTP connection, this can be configured in the [#SynchronizationSettings Synchronization Settings] (proxy authentication is currently not supported).

Check that both instances have the synchronization module enabled in {{{models/000_config.py}}}. If the ''sync'' section is missing from {{{deployment_settings.modules}}}, then add it as follows:

{{{
deployment_settings.modules = OrderedDict([

    ...

    # Add or uncomment this section, if it is missing or commented:
    ("sync", Storage(
            name_nice = T("Synchronization"),
            description = T("Synchronization"),
            restricted = True,
            access = "|1|",     # Only Administrators can see this module in the default menu & access the controller
            module_type = 0     # This item is handled separately for the menu
        )),

    ...

])
}}}

=== Synchronization Homepage ===

Login as administrator and open the '''Administration''' menu. In the left menu, you find the following entries:

[[Image(sync_menu.png)]]

Click on '''Synchronization''' here to open the homepage of the Synchronization Module:

[[Image(sync_homepage.png)]]

=== Synchronization Settings ===

Go to the [#SynchronizationHomepage Synchronization Homepage] and click '''Settings''' to open this page:

[[Image(sync_config.png)]]

==== UUID ====

This page shows you the '''UUID''' (universally unique identifier) of ''this'' repository. You will need this identifier to register the repository at the peer site (the local UUID to register at the remote site, and the remote UUID to register at the local site). The UUID is created during the first run of the Sahana Eden instance, and cannot be changed.

==== To Do ====

...at the '''local''' site:

  - if needed, enter the complete URL of the proxy server (including port number if not 80) that is to be used when connecting to the remote site. Click ''Save'' to update the configuration.

...at the '''remote''' site:

  - no change required
=== Worker ===

The scheduled synchronization jobs are performed by a separate asynchronous web2py '''worker''' process at the local site.

==== To Do ====

...at the '''local''' site:

To start the worker process, open a shell on the local server, change into the web2py home directory and run:

{{{
python web2py.py -K eden -Q
}}}

''(replace "eden" with the name of your Sahana Eden application if necessary)''

In more advanced configurations you may want to run this command as a daemon process, e.g. under Linux by:

{{{
nohup python web2py.py -K eden -Q >/dev/null 2>&1 &
}}}

...at the '''remote''' site:

  - no action required

==== Repository Configuration ====

Go to the [#SynchronizationHomepage Synchronization Homepage] and click '''Repositories'''. This will show you a list of all configured repositories:

[[Image(sync_repository.png)]]

The '''Open''' button in each line opens the configuration for the respective repository.

By clicking '''Add Repository''', you can add a new peer repository configuration:

[[Image(sync_repository_add.png)]]

  ||''Field''||''Instructions''||at the '''local''' site||at the '''remote''' site||
  ||Name||Enter a name for own reference||required||required||
  ||URL||Enter the URL of the repository||required||-||
  ||username||Enter the username to authenticate at the repository||required||-||
  ||password||Enter the password to authenticate at the repository||required||-||
  ||proxy||Enter the URL of a proxy server to connect to the repository, if different from the [#SynchronizationSettings Synchronization Settings]||fill in as needed||-||
  ||Accept Pushes||check this if the repository is allowed to push updates||-||set as needed||
  ||UUID||Enter the UUID from the [#SynchronizationSettings Synchronization Settings] of the repository||required||required||

==== To Do ====

...at the '''local''' site:

  - add a repository configuration for the '''remote''' site

...at the '''remote''' site:

  - add a repository configuration for the '''local''' site

----

See [wiki:S3/Synchronization]