Learn How To Setup Firefox Sync Server on Debian 9 or Ubuntu 16.04

September 27, 2019

Table of Contents

If you are using a different system, please check our other tutorials.

Firefox Sync is a browser synchronization feature that lets you share your data and preferences (such as your bookmarks, history, passwords, open tabs and installed add-ons) across all of your devices. Mozilla also offers a “synchronization server” application for use with Firefox Sync for users and businesses that prefer to host their own synchronization data. This article shows you how to set up Mozilla Sync Server.


  • A newly deployed IT Web Services Debian 8, Debian 9 or Ubuntu 16.04 server instance.
  • A sudo user.

Install the necessary packages

Update the system:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade

To build and run Sync Server, you will need to install these packages:

  • python-dev
  • git
  • build-essential (C++ compiler, GCC compiler, make and other required tools).
  • sqlite3 (if you want to use a MySQL database instead of SQLite, you can replace the sqlite3 package with mariadb-server or mysql-server).
  • nginx (webserver. It’s up to you to choose which web server you want to use from apache2 or nginx).

Install the packages:

sudo apt-get install -y git git-core python-dev python-virtualenv build-essential sqlite3 nginx

Building the server

We will clone the Git repository of the synchronization server by typing the following command and then enter the folder:

git clone https://github.com/mozilla-services/syncserver
cd syncserver

Run the build command which will download the dependencies and compile the code.

make build

Sync Server configuration

The configuration of the synchronization server is very simple, there are just a few parameters to change in the configuration file (./syncserver.ini).

Open the configuration file with your favorite text editor (for example nano ./syncserver.ini).

use = egg:gunicorn
host =
port = 5000
workers = 1
timeout = 30
use = egg:syncserver
# This must be edited to point to the public URL of your server,
# i.e. the URL as seen by Firefox.
public_url = http://localhost:5000/
# This defines the database in which to store all server data.
#sqluri = sqlite:////tmp/syncserver.db
# This is a secret key used for signing authentication tokens.
# It should be long and randomly-generated.
# The following command will give a suitable value on *nix systems:
#    head -c 20 /dev/urandom | sha1sum
# If not specified then the server will generate a temporary one at startup.
# Set this to "false" to disable new-user signups on the server.
# Only request by existing accounts will be honoured.
# allow_new_users = false
# Set this to "true" to work around a mismatch between public_url and
# the application URL as seen by python, which can happen in certain reverse-
# proxy hosting setups.  It will overwrite the WSGI environ dict with the
# details from public_url.  This could have security implications if e.g.
# you tell the app that it's on HTTPS but it's really on HTTP, so it should
# only be used as a last resort and after careful checking of server config.
force_wsgi_environ = false
# Uncomment and edit the following to use a local BrowserID verifier
# rather than posting assertions to the mozilla-hosted verifier.
# Audiences should be set to your public_url without a trailing slash.
#backend = tokenserver.verifiers.LocalVerifier
#audiences = https://localhost:5000
# By default, syncserver will accept identity assertions issues by
# any server. You can restrict this by setting the below to a list
# of allowed issuer domains.
#allowed_issuers = www.mysite.com myfriendsdomain.org

The address of your server must be specified via the parameter public_url:

public_url = http://fsync.example.com

Note: the default value of public_url “http://localhost:5000/” will work for testing purposes on your local machine.

In the sqluri option, we will uncomment and put the location or URI that will allow the server to connect the database and store the information:

sqluri = sqlite:////path/to/database/file.db

If you want to use another type of DB:

sqluri = pymysql://username:password@db.example.com/sync

For the “secret” parameter, we will have to generate a secret key for authentication tokens:

head -c 20 /dev/urandom | sha1sum

Uncomment the line of the secret parameter and then copy/paste the returned string into the secret parameter:

secret = db8a203aed5fe3e4594d4b75990acb76242efd35

Note: If you do not put anything in this parameter, the server will generate one but it will be different each time the server is restarted.

For the “allow_new_users” parameter, uncomment it and set it as true to allow our account to connect to our server for the first time:

allow_new_users = true

We will then modify the “audiences” parameter and put the same thing as the “public_uri” parameter without forgetting to uncomment the line:

audiences = http://fsync.example.com

Finally, just add the following line to the end of your file:

forwarded_allow_ips = *

This line will help you avoid error messages and authorization issues.

Starting Sync Server

To start the synchronization server, you can either launch the following command:

./path/to/syncserver/local/bin/gunicorn --threads 4 --paste /path/to/syncserver/syncserver.ini &

… or this one:

make serve &

The first option allows choosing the location of the configuration file; and also to put the argument --threads 4, which allows assigning more power to the synchronization server.

To start the server each time your instance boots, you can add the following line to your crontab by typing the crontab -e command:

@reboot ./path/to/syncserver/local/bin/gunicorn --paste /path/to/syncserver/syncserver.ini &

Web server configuration

You can use different web servers that are compatible with the WSGI protocol. For example:

  • Nginx with uWSGI.
  • Apache combined with mod_wsgi.


For Nginx, you have to use Nginx’s built-in proxy as shown below:

server {
        listen  80;
        server_name fsync.example.com;
        location / {
                proxy_set_header Host $http_host;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_redirect off;
                proxy_read_timeout 120;
                proxy_connect_timeout 10;

Nginx + uWSGI

It is possible for Nginx users to use the WSGI socket only.

Install uWSGI via Pip:

pip install uwsgi

Install uWSGI via downloading a source tarball:

wget https://projects.unbit.it/downloads/uwsgi-latest.tar.gz
tar zxvf uwsgi-latest.tar.gz
cd <dir>

Note: After the build, you will have a uwsgi binary in the current directory.

Once installed, start it with the following options:

uwsgi --plugins python27 --manage-script-name 
--mount /<location>=/path/to/syncserver/syncserver.wsgi 
--socket /path/to/uwsgi.sock

Then use the following Nginx configuration:

location /<location>/ {
  include uwsgi_params;
  uwsgi_pass unix:/path/to/uwsgi.sock;


Install mod_wsgi:

apt-get install libapache2-mod-wsgi

Then use the following vhost:

<VirtualHost *:80>
  ServerName sync.example.com
  DocumentRoot /path/to/syncserver
  WSGIProcessGroup sync
  WSGIDaemonProcess sync user=sync group=sync processes=2 threads=25 python-path=/path/to/syncserver/local/lib/python2.7/site-packages/
  WSGIPassAuthorization On
  WSGIScriptAlias / /path/to/syncserver/syncserver.wsgi
  CustomLog /var/log/apache2/sync.example.com-access.log combined
  ErrorLog  /var/log/apache2/sync.example.com-error.log

Configure the client (Firefox)

Once the server has been installed and configured, you should configure desktop Firefox client to talk to your new Sync Server. Before you begin, if you are already connected to Firefox Sync Servers, you must log out. Otherwise, the connection to the new server may not work.

First, open a new tab and enter the following address:


In the search bar, enter identity.sync.tokenserver.uri and change its value to the URL of your server with a path of token/1.0/sync/1.5:


Need help?

Do you need help setting up this on your own service?
Please contact us and we’ll provide you the best possible quote!