HTTP server HOWTO#

SyncEvolution 1.0 alpha and above can act as a SyncML server over HTTP. This lets clients sync to the SyncEvoluton server, with SyncEvolution acting as a hub between servers and clients. This HOWTO focuses on the usage of the HTTP on a remote server and thus stores data in plain files instead of depending on Evolution.

It is also possible to synchronize SyncEvolution with another instance of SyncEvolution on regular desktops/laptops where both use Evolution.

Requirements#

A computer that can be contacted by the devices which are going to synchronize against the server
Shell access to that machine
Core runtime libraries needed by SyncEvolution (libstdc++, libsoup, libdbus)
the Python Twisted framework and D-Bus bindings (python-twisted-web, python-dbus in Debian/Ubuntu)
Evolution itself is not needed
Root access is not required, but can be used

Instructions#

Install SyncEvolution, version 1.2 or greater.[1]
To start the HTTP server, on port 9000, run:
```
syncevo-http-server http://localhost:9000/syncevolution &
```
The port and path (syncevolution in this case) can be replaced with alternative values.

If using a version of SyncEvolution installed in a custom location, or compiled from source and not installed, some environment variables must be set so that SyncEvolution can find its files. A D-Bus session must be started. Both can be done automatically with
```
syncevo-http-server --start-syncevolution --start-dbus-session
```
Setup a client to connect to the server, using the synchronization URI: http://${host}:${port}/syncevolution where you should replace ${host} with the host or IP address of the server, ${port} with the port and syncevolution with the path that you chose earlier.
Start the sync process from the client now. The process will fail, so look in the output from the SyncEvolution HTTP server for the string:
```
[ERROR] no configuration found for deviceID XYZ123
```
where XYZ123 will be a string unique to the client.
Store the device ID in a shell variable:
```
deviceID=XYZ123
```
and do the same for a peer name (this can be any name that you like):
```
peer=myPeerName
```

Configure the server, by running the following commands:

# Choose a directory where SyncEvolution will
# store the PIM data, using its internal file backend.
# To store in some other backend, like Evolution,
# you'll have to use different "type" and "evolutionsource"
# values in the commands below.
datapath=$HOME/some-directory

# All sources are disabled by default.
# The URI is reset here because it can be used to rename the
# data source (not necessary when configuring the client, so
# that it uses the source names as URIs).
syncevolution --configure \
  --template default \
  --sync-property syncURL= \
  --sync-property peerIsClient=1 \
  --sync-property remoteDeviceId=${deviceID} \
  --sync-property username=${username} \
  --sync-property password=${password} \
  --source-property uri= \
  --source-property sync=none \
  ${peer}

# Remove the "--source-property type" lines to use the Evolution backends.
syncevolution --configure \
   --source-property type=file:text/vcard:3.0 \
   --source-property evolutionsource=file://${datapath}/addressbook \
   ${peer} addressbook
syncevolution --configure \
   --source-property type=file:text/calendar:2.0 \
   --source-property evolutionsource=file://${datapath}/calendar \
   ${peer} calendar
syncevolution --configure \
   --source-property type=file:text/calendar:2.0 \
   --source-property evolutionsource=file://${datapath}/todo \
   ${peer} todo
syncevolution --configure \
   --source-property type=file:text/plain:1.0 \
   --source-property evolutionsource=file://${datapath}/memo \
   ${peer} memo
syncevolution --configure \
   --source-property type=virtual:text/calendar:2.0 \
   --source-property evolutionsource=calendar,todo \
   ${peer} calendar+todo

# Enable the sources the client is meant to have access to.
# The real sync mode is chosen by the client; all that matters
# here is that sync != disabled.
syncevolution --configure \
   --source-property sync=two-way \
   ${peer} addressbook calendar todo memo

# If your client needs a combined database for events
# and tasks, then instead enable calendar+todo. Enabling
# calendar or task is not necessary. In such a
# configuration the client cannot access the calendar
# and todo sources directly.
syncevolution --configure \
   --source-property sync=two-way \
   ${peer} addressbook calendar+todo

Start synchronization with the client again. If desired, the individual synchronization databases can be accessed by changing the sync URI to add either addressbook, calendar, todo or memo. For clients which only support a combined storage of events and tasks (not the case for SyncEvolution itself as client), use calendar+todo for the URI. The server still stores events and tasks separately. If the client does not allow configuring the URIs, then it is possible to set aliases on the server side via the uri property in the commands above.

Usage notes#

The server must have been started as described above whenever a client wants to synchronize. Automating this is left as an exercise to the reader…

HTTPS is probably possible by extending the way how Twisted is used and/or configured. Patches and instructions are welcome.

It is possible to manipulate items on the server by adding, removing or editing the files in ${datapath}. The file modification time stamp is used to detect updated files.

In the configuration above, the server runs synccompare at the start and end of each sync session. This can be avoided like this:

syncevolution --configure printChanges=0 ${peer}

Limitations#

There are some limitations to the HTTP synchronization mode:

all processes run in the same user account
the data being synchronized is owned the that user
the processes depend on D-Bus for communicating with each other

Troubleshooting#

Full log files and database dumps are stored in the directory ‘~/.cache/syncevolution’.
When the server is running, check the output of the command: `syncevolution –print-sessions ${peer}`