weave4j - Firefox Sync Server for Java

Please note: weave4j is not maintained any longer and only implements version 1.0 and 1.1 of the Firefox Sync protocol. Recent versions of Firefox do not support this protocol version any longer. They use protocol version 1.5. Unfortunately, supporting this version is not trivial because the way how authentication and encryption works has changed significantly. In particular, in addition to a Firefox Sync server, a Firefox Accounts server is needed. If you are still interested in running your own server, have a look at the documentation provided by Mozilla.

Table of Content

About weave4j

Firefox Sync (formerly known as Weave) is a service to synchronize bookmarks, open tabs and other parameters between instances of Mozilla Firefox running on different computers. The original server-side implementation of Firefox Sync provided by Mozilla was written in PHP and rather difficult to setup. Now, there is a better Python-based implementation, however setup is still non-trivial.

Weave4j is a Java / Scala based server implementation of the Firefox Sync protocol that can be easily deployed in any JEE web container like Tomcat or Jetty. The Firefox Sync data is stored in an HyperSQL database in the web application's directory.

The software is licensed under the GNU General Public License 3.0.


The Firefox Sync User API 1.0 and Firefox Sync Storage API version 1.0 and 1.1 as specified by Mozilla is implemented by weave4j with the following exceptions:


weave4j 2.0.1 (released November 12th, 2014)

weave4j 2.0.1 is a bugfix release. Scala has been updated to version 2.10 and Spring has been updated to version 3.0.7. The primary change is a bugfix in the handling of the /user/1.0/<username>/node/weave URL. While this fix is not critical for Firefox, it improves the interoperability with third-party clients (e.g. iCab Mobile).

This version only supports versions 1.0 and 1.1 of the sync protocol. Therefore, an account cannot be setup in recent Firefox versions. You will have to create (or connect to) the account with Firefox 28 or older and upgrade Firefox after the initial configuration. Newer Firefox versions will continue to sync if the configuration has been performed using an older Firefox version.

weave4j 2.0.0 (released July 10th, 2011)

weave4j 2.0.0 brings quite a number of new features and some minor changes:

Getting Started

Download and unpack Apache Tomcat. Download the weave4j WAR from the download section below and place it in Tomcat's webapps directory. Start Tomcat using the start script for your platform (e.g. bin/startup.sh). Tomcat has to be configured to unpack the WAR, but fortunately this is the default setting.

That's it: Now you can enter the URL your Tomcat is running at (e.g. http://localhost:8080/weave4j-X.X.X/) in the preferences of the Weave client and everything should be working.

Important Note: Newer versions of Firefox or the Firefox Sync addon respectively refuse to work over an unencrypted (HTTP) connection. They do not report an error but fail silently. Therefore, you either have to configure Tomcat to use SSL (harder to do) or you have to setup Apache with SSL support and forward requests to Tomcat using either HTTP or AJP (preferred). There is a good HowTo about setting up Tomcat with Apache's mod_proxy_ajp.

Please also note, that you have to add the SSL certificate of the weave4j server to the list of trusted certificates in Firefox before trying to configure Firefox Sync. This step is not needed, if the server is using a certificate that is signed by a trusted certification authority.

The HSQL database that stores the Weave data will be located in webapps/weave4j-X.X.X/WEB-INF/weave4j-database.*. If you want to change this location, you have to edit the file webapps/weave4j-X.X.X/WEB-INF/local-config.properties and restart Tomcat.

You should also consult the local-config.properties file in order to enable captchas, disable the user registration and configure options for sending the password reset e-mails. In order to enable the administrative web interface you must set the password hash in the before mentioned file. You can use a simple PHP script (source) for this tasks. The administrator's user name is fixed to "admin". The administrative web interface can be reached at <weave4j URL>/adminui/. The normal user interface is available at <weave4j URL>/ui/.


Release 2.0.1 (November 12th, 2014):
This release of weave4j fixes a minor bug that caused trouble with some third-party clients (e.g. iCab Mobile). It also updates Scala and Spring to more recent versions.

Release 2.0.0 (July 10th, 2011):
This release of weave4j brings support for the Firefox Sync Storage API 1.1 (used by Firefox 5) and several other new features.

Release 1.0.0 (March 22nd, 2010):
This is the first release of weave4j.

The source code can be found in the weave4j SVN repository.

Visit other projects on projects.marsching.org!

© 2010-2014 Sebastian Marsching