HTTP Server HOWTO

Submitted by Patrick Ohly, updated on 4 May 2010 - 07:32

Introduction

Starting with SyncEvolution 1.0 alpha, SyncEvolution can act as a SyncML server. The way how clients contact that server depends on the transport mechanism. One option is HTTP. Because SyncEvolution is primarily a "personal SyncML server", there are several intentional restrictions:

  • All processes run in the same user account.
  • The data being synchronized is owned by that user.
  • The processes depend on D-Bus for communicating with each other.
  • HTTP server mode is not the main use case and more experimental than OBEX/Bluetooth server mode (direct sync with phones). We use it for testing, but not regularly yet.

Requirements

  • A machine that can be contacted by the devices which are going to synchronize against the server.
  • Shell access to that machine.
  • This HOWTO works with and without root access.
  • Core runtime libraries needed by SyncEvolution (libstdc++, libsoup, libdbus). Evolution itself is not needed.
  • The Python Twisted framework and D-Bus binding (python-twisted-web, python-dbus in Debian/Ubuntu).

Terminology

${password}, ${username}
Account credentials, must be configured on client and server to let clients talk to the server.
${devID}
Every client must be configured manually on the server, at least at the moment. The key used by the server for finding the right configuration is the client's SyncML device ID.
${port}
Each instance of the SyncML HTTP server must use its own network port. 9000 is an arbitrary number chosen for this HOWTO, change it if already in use.
${host}
the name under which the server can be reached by clients
${datapath}
SyncEvolution can store data in Evolution, but this is not required and will fail on a server where Evolution has never been started before. This HOWTO describes how to configure the file backend as data storage in an arbitrary data directory, with one sub directory per database.
${syncevopath}
only when installing the binary .tar.gz distribution in a non-standard location: the directory containing the "usr" hierarchy from the .tar.gz

Setup of Server

  1. Get a copy of the sources (.tar.gz snapshots, directly from git repository
  2. install SyncEvolution ≥ 1.0 beta 3:
    • if you have root permissions, install in /usr normally, otherwise just unpack somewhere (${syncevo_path})
    • otherwise compile from source with --enable-dbus-service --disable-ecal --disable-ebook --disable-shared
  3. ensure that you have a D-Bus session:
    • env | grep DBUS_SESSION_BUS_ADDRESS
    • if not, run test/dbus-session.sh bash
  4. set shell variables, used by commands below (example values here):
    port=9000
    username=my_own_name
    password=my_super_secret_password
    datapath=$HOME/syncevolution-data-dir
  5. set paths
    • shared objects, not necessary when installed as root in /usr or when using --disable-shared:
      export SYNCEVOLUTION_BACKEND_DIR=${syncevopath}/lib/syncevolution/backends
      export LD_LIBRARY_PATH=${syncevopath}/lib/:${syncevopath}/lib/syncevolution:$LD_LIBRARY_PATH
    • PATH to binaries and runtime files, also not necessary when installed as root in /usr or when compiled from source and installed:
      export PATH=${syncevopath}/libexec:${syncevopath}/bin:$PATH
      export SYNCEVOLUTION_XML_CONFIG_DIR=${syncevopath}/share/syncevolution/xml
      export SYNCEVOLUTION_TEMPLATE_DIR=${syncevopath}/share/syncevolution/templates
  6. run syncevo-dbus-server &
  7. run test/syncevo-http-server.py http://localhost:9000/syncevolution &
  8. let the client attempt to synchronize (see below)
  9. search the output for the line [ERROR] no configuration found for deviceID XYZ123
  10. remember the device ID printed at the end of that line and pick a more memorable name for it:
    devID=XYZ123
    peer=my_foobar_device
  11. configure the server:
    syncevolution --configure \
      --template default \
      --sync-property syncURL= \
      --sync-property peerIsClient=1 \
      --sync-property remoteDeviceId=${devID} \
      --sync-property username=${username} \
      --sync-property password=${password} \
      ${peer}

    # Remove the "--source-property type" lines to use the Evolution backends.
    # The uri is reset here because it can be used to rename the data source.
    syncevolution --configure \
      --source-property type=file:text/vcard:3.0 \
      --source-property uri= \
      --source-property evolutionsource=file://${datapath}/addressbook \
      ${peer} addressbook
    syncevolution --configure \
      --source-property type=file:text/calendar:2.0 \
      --source-property uri= \
      --source-property evolutionsource=file://${datapath}/calendar \
      ${peer} calendar
    syncevolution --configure \
      --source-property type=file:text/calendar:2.0 \
      --source-property uri= \
      --source-property evolutionsource=file://${datapath}/todo \
      ${peer} todo
    syncevolution --configure \
      --source-property type=file:text/plain:1.0 \
      --source-property uri= \
      --source-property evolutionsource=file://${datapath}/memo \
      ${peer} memo
    syncevolution --configure \
      --source-property type=virtual:text/calendar:2.0 \
      --source-property uri= \
      --source-property evolutionsource=calendar,todo \
      ${peer} calendar+todo
  12. start synchronization in the client again after configuring as described below => should work now and place files in the sub directories of ${datapath}

Setup of Client(s)

Use http://${host}:${port}/syncevolution as sync URL. The URIs for the different databases are 'addressbook', 'calendar', 'todo', 'memo'. For clients which only support a combined storage of events and tasks (not the case for SyncEvolution itself as client), use 'calendar+todo' as 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/or instructions 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 --sync-property printChanges=0 ${peer}

Troubleshooting

Watch the output of syncevo-dbus-server to learn what kind of ERRORs it runs into. Full log files and database dumps are stored in ~/.cache/syncevolution, see syncevolution --print-sessions ${peer}.