Skip to content
Run-Your-Own Firefox Sync Server
Branch: master
Clone or download
pjenvey Merge pull request #169 from mozilla-services/update-sqlalchemy-1.3.3
fix(deps): Update SQLAlchemy to latest version.
Latest commit a9fa69d Apr 18, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Migrate to CircleCI 2 (#129); r=jrgm Jul 23, 2018
bin Add a script to help users delete Mozilla-hosted data. Sep 20, 2018
syncserver Improve support for Python 3. Oct 10, 2018
.dockerignore Migrate to CircleCI 2 (#129); r=jrgm Jul 23, 2018
.gitignore Use a persistent sqlite db by default, rather than in-memory one. Mar 25, 2014
.travis.yml travis: install virtualenv Oct 21, 2018 Add Mozilla Code of Conduct file Mar 27, 2019 Add, based on templates from FxA. Feb 6, 2019
Dockerfile Add --no-use-pep517 to pip, as a workaround for build issues. Jan 28, 2019
LICENSE Add a simple static node assignment backend, for easier deployment. Feb 11, 2014
Makefile makefile: use the system Python's virtualenv Oct 19, 2018
README.rst chore(docs): Clarify docs on using a secret key in docker env vars. Mar 7, 2019
dev-requirements.txt Add support for deploying via dockerflow pipeline. (#90) r=vladikoff May 26, 2017
requirements.txt fix(deps): Update SQLAlchemy to latest version. Apr 17, 2019 Prep v1.8.0 May 4, 2018
syncserver.wsgi Improve support for Python 3. Oct 10, 2018


Run-Your-Own Firefox Sync Server

This is an all-in-one package for running a self-hosted Firefox Sync server. It bundles the "tokenserver" project for authentication and the "syncstorage" project for storage, to produce a single stand-alone webapp.

Complete installation instructions are available at:


The Sync Server software runs using python 2.7, and the build process requires make and virtualenv. You will need to have the following packages (or similar, depending on your operating system) installed:

  • python2.7
  • python2.7-dev
  • python-virtualenv
  • gcc and g++
  • make

Take a checkout of this repository, then run "make build" to pull in the necessary python package dependencies:

$ git clone
$ cd syncserver
$ make build

To sanity-check that things got installed correctly, do the following:

$ make test

Now you can run the server:

$ make serve

This should start a server on http://localhost:5000/.

Now go into Firefox's about:config page, search for a setting named "tokenServerURI", and change it to point to your server:

identity.sync.tokenserver.uri:  http://localhost:5000/token/1.0/sync/1.5

(Prior to Firefox 42, the TokenServer preference name for Firefox Desktop was "services.sync.tokenServerURI". While the old preference name will work in Firefox 42 and later, the new preference is recommended as the old preference name will be reset when the user signs out from Sync causing potential confusion.)

Firefox should now sync against your local server rather than the default Mozilla-hosted servers.

For more details on setting up a stable deployment, see:


All customization of the server can be done by editing the file "syncserver.ini", which contains lots of comments to help you on your way. Things you might like to change include:

  • The client-visible hostname for your server. Edit the "public_url" key under the [syncerver] section.
  • The database in which to store sync data. Edit the "sqluri" setting under the [syncserver] section.
  • The secret key to use for signing auth tokens. Find the "secret" entry under the [syncserver] section and follow the instructions in the comment to replace it with a strong random key.

Database Backend Modules

If your python installation doesn't provide the "sqlite" module by default, you may need to install it as a separate package:

$ ./local/bin/pip install pysqlite2

Similarly, if you want to use a different database backend you will need to install an appropriate python module, e.g:

$ ./local/bin/pip install PyMySQL
$ ./local/bin/pip install psycopg2

Runner under Docker

There is experimental support for running the server inside a Docker container. The docker image runs with UID/GID 1001/10001. Build the image like this:

$ docker build -t syncserver:latest .

Then you can run the server by passing in configuration options as environmet variables, like this:

$ docker run --rm \
    -p 5000:5000 \
    -e SYNCSERVER_PUBLIC_URL=http://localhost:5000 \
    -e SYNCSERVER_SQLURI=sqlite:////tmp/syncserver.db \
    -e PORT=5000 \

Don't forget to generate a random secret key to use in the SYNCSERVER_SECRET environment variable!

And you can test whether it's running correctly by using the builtin function test suite, like so:

$ /usr/local/bin/python -m syncstorage.tests.functional.test_storage \
    --use-token-server http://localhost:5000/token/1.0/sync/1.5

If you'd like a persistent setup, you can mount a volume as well:

$ docker run -d \
    -v /syncserver:/data \
    -p 5000:5000 \
    -e SYNCSERVER_PUBLIC_URL=http://localhost:5000 \
    -e SYNCSERVER_SQLURI=sqlite:////data/syncserver.db \
    -e PORT=5000 \

Make sure that /syncserver is owned by 1001:1001

Removing Mozilla-hosted data

If you have previously uploaded Firefox Sync data to the Mozilla-hosted storage service and would like to remove it, you can use the following script to do so:

$ pip install PyFxA
$ python ./bin/

Questions, Feedback

You can’t perform that action at this time.