Operating System Debian

How to Self-Host Firefox Sync (syncstorage-rs) on Debian 13 or Ubuntu 26.04

Run your own Firefox Sync server with Mozilla's syncstorage-rs and Docker Compose on Debian 13 or Ubuntu 26.04, replacing the retired Python syncserver.

Firefox Sync keeps bookmarks, history, passwords and open tabs in step between your devices, and Mozilla lets you store that data on your own server instead of theirs. The Python syncserver package that older tutorials installed on Debian 9 and Ubuntu 16.04 is retired: its repository carries a notice that it is no longer maintained and was archived in February 2026. Its replacement is syncstorage-rs, a rewrite in Rust that contains both the storage service and the token server. This guide deploys it the way Mozilla documents for self-hosting, with Docker Compose, on Debian 13 or Ubuntu 26.04 LTS (the steps are the same on Debian 12 and Ubuntu 24.04), and then points Firefox at it.

What you need

  • A 64-bit x86 server. The images Mozilla publishes are built for linux/amd64 only.
  • A user with sudo rights and a host name for the service, sync.example.com in the examples, pointing at the server.
  • A Mozilla account. A self-hosted sync server stores your data, but sign-in still goes through Mozilla accounts; the documented setup assumes this.

Sync data is encrypted on the client before upload, so the server holds ciphertext. Running your own server changes where that ciphertext lives, not how you log in.

Install Docker

Install Docker Engine and the Compose plugin from Docker's repository. These are the commands for Debian:

sudo apt update
sudo apt install ca-certificates curl git
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

On Ubuntu, replace debian with ubuntu in the two download.docker.com URLs; everything else is identical.

Get the compose file

The syncstorage-rs repository ships ready-made "one-shot" compose files that start the sync server together with its databases. Clone the repository:

sudo git clone https://github.com/mozilla-services/syncstorage-rs.git /opt/syncstorage-rs
cd /opt/syncstorage-rs

The file used here is docker/docker-compose.one-shot.mysql.yaml. It defines three containers: syncserver, plus one MySQL 8.0 container each for the storage database and the token server database, with named volumes for the data. A PostgreSQL variant, docker/docker-compose.one-shot.postgres.yaml, uses a single database for both and works the same way.

By default the file builds the server from source, which takes a long time and a lot of memory. To use Mozilla's prebuilt image instead, open the file and replace the build: block of the syncserver service (the lines from build: down to the last args entry) with these two lines, as described in the comments at the top of the file:

    image: ghcr.io/mozilla-services/syncstorage-rs/syncserver-mysql:${SYNCSERVER_VERSION:?set SYNCSERVER_VERSION to a published tag}
    platform: linux/amd64

While you are in the file, change the published port so the service is reachable only through the reverse proxy you will add below. In the ports: list of the syncserver service, put 127.0.0.1: in front of the existing value:

    ports:
      - "127.0.0.1:${SYNC_PORT:-8000}:${SYNC_PORT:-8000}"

The database containers are not published to the host at all, so their fixed internal passwords are not reachable from outside the Compose network.

Set the secret, version and public URL

Three values must be supplied. Put them in an environment file so every later docker compose command uses the same ones. Generate a secret first:

openssl rand -hex 32

Create /opt/syncstorage-rs/sync.env:

SYNCSERVER_VERSION=replace-with-a-published-tag
SYNC_MASTER_SECRET=paste-the-generated-secret-here
SYNC_TOKENSERVER__INIT_NODE_URL=https://sync.example.com
  • SYNCSERVER_VERSION is an image tag. Release builds are tagged with the release version and latest; pick one from the syncserver-mysql packages page linked from the repository rather than guessing.
  • SYNC_MASTER_SECRET is used to derive authentication secrets. The compose file's default is a placeholder; never keep it.
  • SYNC_TOKENSERVER__INIT_NODE_URL is the address clients are told to use for storage. The server writes it into the token server database on first start only if no node exists yet, so set the final public URL before you start anything.
sudo chmod 600 /opt/syncstorage-rs/sync.env

Start the server

cd /opt/syncstorage-rs
sudo docker compose --env-file sync.env -f docker/docker-compose.one-shot.mysql.yaml up -d

The database schemas are created automatically at startup. Wait until the syncserver container reports healthy, then check the heartbeat endpoint:

sudo docker compose --env-file sync.env -f docker/docker-compose.one-shot.mysql.yaml ps
curl http://localhost:8000/__heartbeat__

A status reply instead of a connection error means the server is up.

Put HTTPS in front

Mozilla's guide stops at http://localhost:8000. For devices outside the server you need a public HTTPS address, which any reverse proxy can provide. With nginx and Certbot from the distribution:

sudo apt install nginx certbot python3-certbot-nginx

Create /etc/nginx/sites-available/sync.example.com:

server {
    listen 80;
    server_name sync.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 4m;
    }
}
sudo ln -s /etc/nginx/sites-available/sync.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d sync.example.com

Then confirm that curl https://sync.example.com/__heartbeat__ answers from another machine.

Point Firefox at your server

On desktop Firefox:

  1. Open about:config.
  2. Find the preference identity.sync.tokenserver.uri.
  3. Set it to https://sync.example.com/1.0/sync/1.5.
  4. Restart Firefox and sign in to your Mozilla account if you have not already.

Check about:sync-log to see whether syncs succeed. On Firefox for Android, open Settings > About Firefox, tap the Firefox logo repeatedly until the debug menu is enabled, go back to Settings, open Sync Debug, enter the same URL under the custom sync server option and use the "Stop Firefox" entry in that menu to apply it. Repeat on every device; a device that still uses the default value keeps syncing with Mozilla's servers and will not see the others.

Maintenance

  • Logs: sudo docker logs -f syncserver. Set RUST_LOG=debug in sync.env for more detail and SYNC_HUMAN_LOGS=true for readable output.
  • Updates: change SYNCSERVER_VERSION to a newer tag, run sudo git pull only if you want the newer compose file (re-apply your two edits afterwards), and run the up -d command again.
  • Backups: the data lives in the Docker volumes of the two database containers. Dump them with mysqldump inside the containers or back up the volumes while the stack is stopped. Keep sync.env with the backup.

All settings can also be passed as SYNC_-prefixed environment variables; the full list is in the syncstorage-rs documentation, which also contains the Docker deployment guide this article follows.

Frequently asked questions

Can I still use the old Python syncserver?

No. It is unmaintained, its repository is archived, and its own README points to syncstorage-rs. Do not start new deployments on it.

Do I need my own accounts server as well?

No. The documented self-hosting setup authenticates against Mozilla accounts and only moves the storage of your sync data to your server. That is why the compose file contains Mozilla's account and OAuth endpoints.

Will my existing data move to the new server automatically?

There is nothing to migrate on the server side. After you change identity.sync.tokenserver.uri, each device uploads its local data to the new server on its next sync, and the devices merge there.

Can I use a database I already run instead of the bundled containers?

Yes. Mozilla's Docker guide includes a smaller compose file with only the sync service, which takes SYNC_SYNCSTORAGE__DATABASE_URL and SYNC_TOKENSERVER__DATABASE_URL pointing at existing MySQL or PostgreSQL databases, with a matching syncserver-postgres image for PostgreSQL.

Share story:

Continue reading other guides on How VPS.