Migrating¶
How to move to firefox-sync from another self-hosted Firefox Sync setup, and how to move a firefox-sync install from docker compose to Kubernetes. To upgrade firefox-sync itself, including from the earlier release, see Upgrading.
Each section says on its Tested: line whether and how it was tested. The database moves are tested by tests/migrate.sh <scenario>: an account of upstream's mock accounts server writes its data through the old stack, the commands of this page move it as written here, and the same account (same uid and keys) reads it back through firefox-sync, on the new node, with SYNC_MAX_USERS and the admin UI counting it. The old stacks run in containers: their own compose files where they publish images, otherwise the same database server, names and schema.
Keep the old server until every device syncs with the new one.
How to choose¶
| You run | Sync data | Accounts | Section |
|---|---|---|---|
| the earlier release of firefox-sync | upgrade in place | - | The earlier firefox-sync release |
| firefox-sync with docker compose or the Quadlets, to Kubernetes | dump and restore | Mozilla's | From docker compose to Kubernetes |
| Mozilla's syncstorage-rs compose files | start fresh, or move the database | Mozilla's | syncstorage-rs |
| dan-r/syncstorage-rs-docker, MASH | start fresh, or move the database | Mozilla's | dan-r |
| jeena/fxsync-docker | start fresh, or move the database | Mozilla's | jeena |
NixOS services.firefox-syncserver |
start fresh, or move the database | Mozilla's | NixOS |
YunoHost syncserver-rs |
start fresh, or move the database | Mozilla's | YunoHost |
| the Python syncserver (any image) | start fresh only | Mozilla's | Python syncserver |
| jackyzy823/fxa-selfhosting | start fresh only | must move | fxa-selfhosting |
From docker compose to the Quadlets on the same host: make a backup with compose and restore it with the Quadlets, as in Backups. Not tested.
Start fresh first¶
The Sync server keeps a copy of what your browsers already have, encrypted with keys derived from your account password. When Firefox finds an empty server for an account whose keys did not change, it uploads everything it has on its next sync. Other devices merge their own data in when they sync after it.
So for every server that only does Sync (you sign in with Mozilla's accounts, or your accounts stay where they are), the simplest and safest way is to start fresh:
- Set up firefox-sync (the docs index). Set
SYNC_MAX_USERSto at least the number of accounts that will use it (Limits). -
Start with the device that has the most data, usually your main desktop:
- if the address of the Sync server changes: disconnect Sync and choose to keep the data on the device (Firefox asks), set the new address (Firefox), sign in again and sync;
- if you keep the same address (your reverse proxy now sends it to firefox-sync, see below): restart Firefox and use
Sync Now. Firefox may use its token from the old server for up to an hour; disconnecting and signing in again switches it at once.
-
Wait until that device has synced (
about:sync-logon desktop, or the account's storage in the admin UI), then do the other devices one at a time.
The data kept only on the old server is lost: for example the data of a device you no longer have. If no device has everything, move the database instead: see the sections below for the setups where that works.
To keep the same address, the path must match too: firefox-sync's tokenserver is at https://<host>/1.0/sync/1.5 and the storage at https://<host>/1.5/<uid>. Set SYNC_PUBLIC_URL to the old host name and point the reverse proxy for that host to firefox-sync: see Reverse proxy (with the Helm chart, syncDomain and its Ingress).
Rollback: stop the old stack (docker compose stop, not down -v) instead of removing it. Until all devices have synced with firefox-sync, going back is pointing the reverse proxy, or the Firefox setting, back to it and starting it.
Tested: not as a migration. It is what Firefox does with any new server: tests/test_fxa_browser.py syncs a real Firefox to an empty one.
Moving the database¶
This only works between syncstorage-rs servers (the Rust one) on the same kind of database, and only with the same accounts service. Then the accounts keep their Sync ids and their data, and Firefox goes on syncing without uploading everything again.
-
The same accounts service. The tokenserver knows an account as
<fxa uid>@<FXA_EMAIL_DOMAIN>in itsuserstable, with thegeneration,keys_changed_atandclient_stateof the account's keys. With Mozilla's accounts that isapi.accounts.firefox.comeverywhere. A differentFXA_EMAIL_DOMAINmakes every account a new one: then start fresh.- Check the old
userstable:SELECT DISTINCT email FROM users. A configuration that sets no email domain gets syncstorage-rs' default,api-accounts.stage.mozaws.net(Mozilla's test servers): for example Mozilla'sdocker-compose.mysql.yamlanddocker-compose.postgres.yamlas they are. - Loaded with
FXA_EMAIL_DOMAIN=api.accounts.firefox.com, such accounts are not found: the tokenserver makes new, empty ones, andSYNC_MAX_USERS, counting the old ones too, refuses them.
- Check the old
-
The same kind of database.
- MariaDB or MySQL to firefox-sync's MariaDB (the default): supported. Dumps of MySQL 8 use the
utf8mb4_0900_ai_cicollation, which MariaDB knows from 11.4.5 on; the stack runsmariadb:lts, newer than that. Tested from MySQL 8.0, MariaDB 10.6, 10.11 and 11.4 intomariadb:lts. - To firefox-sync on MySQL (
SYNC_DB=mysql): only dumps from MySQL, or from MariaDB before 11. MariaDB 11 and newer writeuca1400collations that MySQL rejects. Tested from MySQL 8.0 intomysql:lts; dumps of MariaDB into MySQL were not tested. - PostgreSQL to firefox-sync's PostgreSQL: supported. Tested from PostgreSQL 15, 17 and 18 into the stack's.
- MySQL or MariaDB to PostgreSQL, or back: not a plain dump, not supported. Start fresh.
- MariaDB or MySQL to firefox-sync's MariaDB (the default): supported. Dumps of MySQL 8 use the
-
Whole databases, including
__diesel_schema_migrations: it tells syncstorage-rs which migrations already ran. firefox-sync runs the newest syncstorage-rs, so it applies the migrations the old server did not have yet. Going back to an older version afterwards is not possible. - Into empty databases, before firefox-sync's first start. At the start, syncstorage-rs adds the node for
SYNC_PUBLIC_URLif it is missing. Then the init container moves every account to that node and takes the old nodes out (db_init.sql, PostgreSQL). So the old node URL does not need to be changed by hand. SYNC_MAX_USERSat least the number of accounts. Accounts that are already in the database always get in, but with fewer seats than accounts, new ones are refused.SYNC_MASTER_SECRETandSYNC_METRICS_HASH_SECRETdon't need to be the old ones: Firefox gets a new token when the old one is refused. The tests use new ones: the accounts sign in again and find their data. That Firefox asks for a new token by itself was not tested.
Loading into firefox-sync¶
- Set up firefox-sync with
./prepare_environment.sh(MariaDB or PostgreSQL, as the old server), but don't rundocker compose up -dyet. New volumes are empty. - Stop the old server, except its database, so that nothing changes during the dump. Make the dumps (see each section):
tokenserver.sqlandsyncstorage.sqlfor MariaDB or MySQL,syncserver.sql(or three files) for PostgreSQL. -
Start only the database containers and load the dumps. PostgreSQL loads as the Sync server's role, never as the superuser: see PostgreSQL users.
With Quadlets, MariaDB or MySQL:# MariaDB (compose/sync-mariadb.yml) docker compose up -d --wait tokenserver_db syncstorage_db docker compose exec -T tokenserver_db sh -c 'MYSQL_PWD="$MARIADB_PASSWORD" mariadb -u"$MARIADB_USER" "$MARIADB_DATABASE"' < tokenserver.sql docker compose exec -T syncstorage_db sh -c 'MYSQL_PWD="$MARIADB_PASSWORD" mariadb -u"$MARIADB_USER" "$MARIADB_DATABASE"' < syncstorage.sql # MySQL (SYNC_DB=mysql, compose/sync-mysql.yml): the same, with the MySQL client docker compose up -d --wait tokenserver_db syncstorage_db docker compose exec -T tokenserver_db sh -c 'MYSQL_PWD="$MYSQL_PASSWORD" mysql -u"$MYSQL_USER" "$MYSQL_DATABASE"' < tokenserver.sql docker compose exec -T syncstorage_db sh -c 'MYSQL_PWD="$MYSQL_PASSWORD" mysql -u"$MYSQL_USER" "$MYSQL_DATABASE"' < syncstorage.sql # PostgreSQL (compose/sync-postgres.yml): as the Sync server's role # SYNC_POSTGRES_APP_USER, created first. Not as SYNC_POSTGRES_USER, the superuser: what the dump # brings (functions in a CHECK, an index, a view) would run with its rights (reference/database-users.md) docker compose up -d --wait postgres_db docker compose run --rm sync_role_init docker compose run --rm --no-deps -T --entrypoint sh sync_role_init -c 'PGPASSWORD="$POSTGRES_SYNC_PASSWORD" psql -h "$POSTGRES_SERVER" -U "$POSTGRES_SYNC_USER" -d "$POSTGRES_DATABASE" -v ON_ERROR_STOP=1' < syncserver.sqlsystemctl --user start firefox-sync-tokenserver-db.service firefox-sync-syncstorage-db.service, then, oncepodman healthcheck run firefox-sync-tokenserver-dbandfirefox-sync-syncstorage-dbpass, the same withpodman exec -i firefox-sync-tokenserver-db sh -c '...' < tokenserver.sqlandfirefox-sync-syncstorage-db, then startfirefox-sync-syncstorage.service. PostgreSQL:systemctl --user start firefox-sync-sync-role-init.service(the database starts first), thenpodman exec -i firefox-sync-postgres-db sh -c 'PGPASSWORD="$FFS_SYNC_PASSWORD" psql -h 127.0.0.1 -U "$FFS_SYNC_USER" -d "$POSTGRES_DB" -v ON_ERROR_STOP=1' < syncserver.sql, then startfirefox-sync-syncstorage.service.With your own database server, load them with
mariadborpsqlas in Move an existing install (not tested). -
docker compose up -d. - Point your reverse proxy, or Firefox, to firefox-sync, as in Start fresh first. Firefox does not need to sign out: on its next token it is sent to the new node and finds its data there.
To Kubernetes: load the dumps into docker compose as above, then follow From docker compose to Kubernetes (not tested).
Checking the result¶
docker compose logs tokenserver_db_initshowsCurrent users: N, the number of accounts of the old server.- The admin UI (
COMPOSE_PROFILES=admin) lists the accounts on its first page, with what each stores. -
In the tokenserver database every current account points to the new node:
docker compose exec tokenserver_db sh -c 'MYSQL_PWD="$MARIADB_PASSWORD" mariadb -u"$MARIADB_USER" "$MARIADB_DATABASE" -e "SELECT u.uid, u.email, u.generation, u.keys_changed_at, u.client_state, n.node FROM users u JOIN nodes n ON n.id = u.nodeid WHERE u.replaced_at IS NULL"' # MySQL (SYNC_DB=mysql) docker compose exec tokenserver_db sh -c 'MYSQL_PWD="$MYSQL_PASSWORD" mysql -u"$MYSQL_USER" "$MYSQL_DATABASE" -e "SELECT u.uid, u.email, u.generation, u.keys_changed_at, u.client_state, n.node FROM users u JOIN nodes n ON n.id = u.nodeid WHERE u.replaced_at IS NULL"' # PostgreSQL, as the Sync server's role (never SYNC_POSTGRES_USER on the Sync database, reference/database-users.md) docker compose run --rm --no-deps -T --entrypoint sh sync_role_init -c 'PGPASSWORD="$POSTGRES_SYNC_PASSWORD" psql -h "$POSTGRES_SERVER" -U "$POSTGRES_SYNC_USER" -d "$POSTGRES_DATABASE" -c "SELECT u.uid, u.email, u.generation, u.keys_changed_at, u.client_state, n.node FROM users u JOIN nodes n ON n.id = u.nodeid WHERE u.replaced_at IS NULL"' -
On desktop,
about:sync-logshows syncs without errors, and a new profile signed in to the same account gets the bookmarks without any other device uploading them first.
Rollback: as in Start fresh first. What was synced to firefox-sync in the meantime is not on the old server, but the devices still have it and upload it again.
Tested: the steps above (docker compose; not your own database server) in every scenario of the sections below. The Quadlets: tests/podman.sh (SYNC_DB=mysql, SYNC_DB=postgres too) loads the dumps of a Quadlet install into a new one with the commands above, as written here. tests/migrate.sh runs the commands of this section and of "Checking the result" as written, with the admin UI on. Not tested with a real Firefox: the client is upstream's test client, signing in like Firefox does after a sign-in.
From docker compose to Kubernetes¶
The same images and databases, moved to the Helm chart with a dump and a restore.
With the self-hosted accounts, they move in the same steps: see With the self-hosted accounts below for what each step adds.
-
On the compose host, with this release: the earlier one first needs The earlier firefox-sync release, so that
.envhas theSYNC_names. Stop the Sync server and the admin UI, so that nothing changes after the dump, and make one with the backup service. If it is off, turn it on for this:COMPOSE_PROFILES=...,backupanddocker compose up -d backup.docker compose stop syncstorage ffs-admin docker compose exec backup sh /ffs-backup/backup.sh now docker compose cp backup:/backups ffs-backups && tar -C ffs-backups -czf ffs-backups.tar.gz . && rm -rf ffs-backupsdocker compose cpreads the backup service's volume whatever the compose project is called.The files are named after the databases of
.env(SYNC_TOKENSERVER_DB_NAME,SYNC_STORAGE_DB_NAME,SYNC_POSTGRES_NAME,ADMIN_DB_NAME). The chart's restore readstokenserver,syncstorage(PostgreSQL:syncserver) andffs_admin: with other names, rename them in the copy.With the Quadlets:
systemctl --user stop firefox-sync-syncstorage.service firefox-sync-admin.service,systemctl --user start firefox-sync-backup.service, thenpodman volume export firefox-sync-backups | gzip > ffs-backups.tar.gz(the restore reads a gzipped tar). -
Create an existingSecret with the secrets of
.env, so that the Sync server keeps itsSYNC_MASTER_SECRETandSYNC_METRICS_HASH_SECRET. New ones work too: Firefox gets a new token when the old one is refused. The chart's keys are not all named as in.env:v() { grep -m1 "^$1=" .env | cut -d= -f2-; } kubectl create secret generic ffs-secrets \ --from-literal=SYNC_MASTER_SECRET="$(v SYNC_MASTER_SECRET)" --from-literal=METRICS_HASH_SECRET="$(v SYNC_METRICS_HASH_SECRET)" \ --from-literal=ADMIN_PASSWORD="$(v ADMIN_PASSWORD)" --from-literal=ADMIN_DB_PASSWORD="$(v ADMIN_DB_PASSWORD)" \ --from-literal=TOKENSERVER_DB_PASSWORD="$(v SYNC_TOKENSERVER_DB_PASSWORD)" --from-literal=STORAGE_DB_PASSWORD="$(v SYNC_STORAGE_DB_PASSWORD)" # PostgreSQL, instead of the last two: POSTGRES_PASSWORD from SYNC_POSTGRES_PASSWORD, # POSTGRES_SYNC_PASSWORD from SYNC_POSTGRES_APP_PASSWORDThe bundled databases are new: their passwords need not be the old ones, but none may be empty. An
.envwithoutADMIN_DB_PASSWORDorSYNC_POSTGRES_APP_PASSWORDneeds one generated. -
Write your values from
.env. Each setting's value is in the Helm column of Settings. The ones that matter here:SYNC_PUBLIC_URLbecomessyncDomain: keep it, so Firefox goes on with the same address;SYNC_DBbecomesdatabase.backend(postgreswithcompose/sync-postgres.ymlinCOMPOSE_FILE);SYNC_POSTGRES_IMAGEbecomesdatabase.image.postgres: the same major (its dump also loads into a newer one);backup.enabled: trueis needed for the restore;- and
existingSecret: ffs-secrets, and the Ingress (Install).
-
Run
helm installwith them, put the copy into the backups' PVC and restore it: Restore on Kubernetes, "On a new cluster", from step 3 (the Secret is yourexistingSecret). - Point the host name to the Ingress (DNS, or your reverse proxy), then check as in Checking the result:
kubectl logs deploy/ffs-firefox-sync-syncstorage -c db-initshowsCurrent users: N. Firefox needs nothing: the same address, the same accounts on the same node.
With your own database server (SYNC_DB_CONTAINERS=0) there is nothing to move: stop the stack (docker compose down), put the passwords of .env into the existingSecret as above, and point the chart to the same server and names (With Helm).
Rollback: docker compose start syncstorage ffs-admin (or the Quadlets) and the host name back to it, as long as nothing synced to Kubernetes in the meantime. What did is still on the devices, which upload it again.
With the self-hosted accounts¶
The accounts keep their databases, their keys and their secrets, so Firefox stays signed in. Each step above adds:
-
The dump. Stop the accounts too, and dump them first, with
backup-fxa. The copy of/backupsthen has bothsync/andaccounts/:docker compose stop syncstorage ffs-admin fxa-auth fxa-content fxa-profile docker compose exec backup-fxa sh /ffs-backup/backup.sh nowThen the
backup.sh nowofbackupand the copy, as above. The keys, from their volume, with thetarof Copy them off the host:fxa-keys.tar.gz. The avatars of thefxa-profile-imagesvolume are in no backup and don't move: the accounts show the default one until their owners upload theirs again. -
The secrets. Put the keys into a Secret of their own, for
fxa.keys.existingSecret:mkdir fxa-keys && tar -C fxa-keys -xzf fxa-keys.tar.gz kubectl create secret generic ffs-fxa-keys --from-file=fxa-keys/secret-key.json --from-file=fxa-keys/public-key.json \ --from-file=fxa-keys/vapid-keys.json --from-file=fxa-keys/openid-key.jsonAdd the accounts' secrets of
.envtoffs-secrets, with the same names:FXA_AUTH_SECRET,FXA_OAUTH_SECRET,FXA_PROFILE_SECRET,FXA_FLOW_ID_KEY,FXA_SESSION_TOKEN_HANDLE_KEY,FXA_CONTENT_SESSION_SECRET,FXA_MYSQL_PASSWORD,FXA_ADMIN_DB_PASSWORDandFXA_SMTP_PASS.FXA_REDIS_PASSWORDis the chart's own: generate one. Every key: existingSecret. -
The values.
fxa.enabled: true, the same three URLs,fxa.database.backendasFXA_DB,fxa.keys.existingSecret: ffs-fxa-keys, the top-levelsmtp.*fromFXA_SMTP_*, andfxa.ingress(Self-hosted accounts). Each setting's value: Settings. - The restore. Restore on Kubernetes restores the accounts' run first, from
/backups/accounts. Use the run of the same night as the Sync one. - The host names. Point the four of them to the Ingress controller.
With your own accounts database server (FXA_DB_CONTAINERS=0), skip the dump and the restore of the accounts: point fxa.database.external.* to the same server (With Helm), with FXA_MYSQL_POLICY_PASSWORD in ffs-secrets too.
Tested: not as a migration. tests/helm-fxa.sh restores the chart's own accounts dump with the command of Restore on Kubernetes, into a scratch database.
Tested: not as a migration. tests/helm.sh e2e restores the chart's own backups with the commands of Restore in pods of the backup's spec, as Restore on Kubernetes does. Those steps as written were run once on kind (MariaDB, PostgreSQL), not in CI.
Mozilla's syncstorage-rs compose files¶
mozilla-services/syncstorage-rs ships docker/docker-compose.one-shot.mysql.yaml and docker-compose.one-shot.postgres.yaml (images ghcr.io/mozilla-services/syncstorage-rs/syncserver-mysql and syncserver-postgres). docker-compose.mysql.yaml and docker-compose.postgres.yaml are its end-to-end test setup, which some people run too.
| File | Database | Databases, user |
|---|---|---|
docker-compose.one-shot.mysql.yaml |
MySQL 8.0, containers syncserver-tokenserver-db and syncserver-sync-db |
tokenserver, syncstorage, user sync / sync |
docker-compose.one-shot.postgres.yaml |
PostgreSQL 18, container syncserver-postgres |
one database syncserver, user sync / sync (the same layout as firefox-sync) |
docker-compose.mysql.yaml |
MySQL 8.0, services tokenserver-db and sync-db |
tokenserver, syncstorage, user test / test |
docker-compose.postgres.yaml |
PostgreSQL 18, services tokenserver-db and sync-db |
tokenserver, syncstorage, user test / test |
Recommended: start fresh. The database path is supported. Its node is SYNC_TOKENSERVER__INIT_NODE_URL (http://localhost:8000 by default); firefox-sync moves the accounts to its own.
The dumps, as the user of each database container's environment (MYSQL_USER, MYSQL_PASSWORD); with your own changes the database names may differ:
# MySQL, one-shot file
docker exec syncserver-tokenserver-db sh -c 'MYSQL_PWD="$MYSQL_PASSWORD" mysqldump -u"$MYSQL_USER" --single-transaction --no-tablespaces --set-gtid-purged=OFF tokenserver' > tokenserver.sql
docker exec syncserver-sync-db sh -c 'MYSQL_PWD="$MYSQL_PASSWORD" mysqldump -u"$MYSQL_USER" --single-transaction --no-tablespaces --set-gtid-purged=OFF syncstorage' > syncstorage.sql
# MySQL, the test setup (from the directory of your checkout)
dc="docker compose -f docker/docker-compose.mysql.yaml exec -T"
$dc tokenserver-db sh -c 'MYSQL_PWD="$MYSQL_PASSWORD" mysqldump -u"$MYSQL_USER" --single-transaction --no-tablespaces --set-gtid-purged=OFF tokenserver' > tokenserver.sql
$dc sync-db sh -c 'MYSQL_PWD="$MYSQL_PASSWORD" mysqldump -u"$MYSQL_USER" --single-transaction --no-tablespaces --set-gtid-purged=OFF syncstorage' > syncstorage.sql
# PostgreSQL, one-shot file: one database, like firefox-sync
docker exec syncserver-postgres pg_dump -U sync --no-owner --no-acl syncserver > syncserver.sql
PostgreSQL with two databases (the test setup) into firefox-sync's one: both have a __diesel_schema_migrations table, with different rows. Dump the tokenserver whole, the storage without that table, then its rows only, and load the three files in this order:
dc="docker compose -f docker/docker-compose.postgres.yaml exec -T"
$dc tokenserver-db pg_dump -U test --no-owner --no-acl tokenserver > syncserver.sql
$dc sync-db pg_dump -U test --no-owner --no-acl --exclude-table=__diesel_schema_migrations syncstorage > syncstorage.sql
$dc sync-db pg_dump -U test --data-only --table=__diesel_schema_migrations syncstorage > syncstorage-migrations.sql
# then, in firefox-sync, as in "Loading into firefox-sync" (sync_role_init first), with each file in turn:
# docker compose run --rm --no-deps -T --entrypoint sh sync_role_init -c 'PGPASSWORD="$POSTGRES_SYNC_PASSWORD" psql -h "$POSTGRES_SERVER" -U "$POSTGRES_SYNC_USER" -d "$POSTGRES_DATABASE" -v ON_ERROR_STOP=1' < <file>
Then Loading into firefox-sync. Firefox: the same .../1.0/sync/1.5 path, so with the same host name nothing changes on the devices.
Tested: with the files of syncstorage-rs master (530d0f0) and the published 0.23.3 images. tests/migrate.sh upstream-mysql (one-shot MySQL to firefox-sync's MariaDB), upstream-mysql-to-mysql (the same to SYNC_DB=mysql), upstream-mysql-testsetup (docker-compose.mysql.yaml), upstream-postgres (one-shot PostgreSQL) and upstream-postgres-2db (docker-compose.postgres.yaml, the three files). The test files got a node URL, the tokenserver and api.accounts.firefox.com as email domain (see Moving the database).
dan-r/syncstorage-rs-docker (and MASH)¶
dan-r/syncstorage-rs-docker (docker-compose.yaml, entrypoint.sh, init.sql) runs:
- one
linuxserver/mariadb:10.6.13containerfirefox_mariadb, with its data in./data/config; - the databases
syncstorage_rsandtokenserver_rs, usersync; - syncstorage-rs built from a pinned commit of June 2025. Its entrypoint sets node 1 to
SYNC_URL, andSYNC_CAPACITYlimits the accounts.
The MASH playbook installs a fork of it (ansible-role-syncstorage-rs-docker) with the same database names on its MySQL or MariaDB server.
Recommended: start fresh. The database path is supported (MariaDB 10.6 into MariaDB):
docker exec firefox_mariadb sh -c 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mariadb-dump -uroot --single-transaction --no-tablespaces tokenserver_rs' > tokenserver.sql
docker exec firefox_mariadb sh -c 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mariadb-dump -uroot --single-transaction --no-tablespaces syncstorage_rs' > syncstorage.sql
With MASH, run it against the server of syncstorage_rs_docker_database_mysql_hostname, with mysqldump if that is MySQL. Then Loading into firefox-sync, with SYNC_MAX_USERS at least the accounts you had (SYNC_CAPACITY). Firefox: SYNC_URL/1.0/sync/1.5, the same path as firefox-sync.
Tested: tests/migrate.sh dan-r, its layout rather than its image (which builds from source): linuxserver/mariadb:10.6.13 as firefox_mariadb with its init.sql, syncstorage-rs 0.18.3 (its pinned commit is 0.18.3 and 8 commits without migrations), the services and nodes rows of its entrypoint, then the commands above. firefox-sync then adds the newer migrations. MASH: not tested.
jeena/fxsync-docker¶
jeena/fxsync-docker, archived on GitHub (moved to git.jeena.net), the inspiration of this project. Its docker-compose.yaml runs mozilla/syncstorage-rs:0.13.6 with two mariadb:10.11 containers, firefox_tokenserver_db (tokenserver) and firefox_syncstorage_db (syncstorage), one user MARIADB_USER for both, and node 1 set to DOMAIN.
Recommended: start fresh. The database path is supported:
docker exec firefox_tokenserver_db sh -c 'MYSQL_PWD="$MARIADB_PASSWORD" mariadb-dump -u"$MARIADB_USER" --single-transaction --no-tablespaces tokenserver' > tokenserver.sql
docker exec firefox_syncstorage_db sh -c 'MYSQL_PWD="$MARIADB_PASSWORD" mariadb-dump -u"$MARIADB_USER" --single-transaction --no-tablespaces syncstorage' > syncstorage.sql
Then Loading into firefox-sync. syncstorage-rs 0.13.6 is old: firefox-sync runs the migrations added since. Firefox: the same path.
Tested: tests/migrate.sh jeena, its docker-compose.yaml as it is (mozilla/syncstorage-rs:0.13.6, mariadb:10.11, its init container), changed only for the test: the mock as accounts server, no published port.
NixOS services.firefox-syncserver¶
The NixOS module (firefox-syncserver.nix) runs syncstorage-rs with one database for the tokenserver and the storage, firefox_syncserver by default (services.firefox-syncserver.database.name). It is on the local services.mysql server (MariaDB or MySQL, database.type = "mysql") or on PostgreSQL (database.type = "postgresql"). With singleNode.enable it sets node 1 to singleNode.url and its capacity.
Recommended: start fresh. The database path is supported. On the NixOS host, as root:
# MariaDB: one database, split into firefox-sync's two (the migrations table goes into both)
sudo mariadb-dump --single-transaction --no-tablespaces firefox_syncserver users nodes services __diesel_schema_migrations > tokenserver.sql
sudo mariadb-dump --single-transaction --no-tablespaces firefox_syncserver bso collections user_collections batch_uploads batch_upload_items __diesel_schema_migrations > syncstorage.sql
# MySQL (services.mysql.package = pkgs.mysql80 or newer): the same with mysqldump instead of mariadb-dump
# PostgreSQL: one database, like firefox-sync
sudo -u postgres pg_dump --no-owner --no-acl firefox_syncserver > syncserver.sql
Then Loading into firefox-sync, and services.firefox-syncserver.enable = false once all devices synced. Firefox: the same path.
Tested: the module's layout in containers, not on NixOS: one database firefox_syncserver for syncstorage-rs 0.23.3. tests/migrate.sh nixos-mysql (MariaDB 11.4, whose image has mariadb-dump but no mysqldump; the table lists are all its tables) and nixos-postgres (PostgreSQL 17), the commands above run as root in the database container. MySQL with mysqldump: not tested.
YunoHost syncserver-rs_ynh¶
YunoHost-Apps/syncserver-rs_ynh builds syncstorage-rs on the YunoHost server. Since 0.23.3~ynh9 it uses PostgreSQL with two databases, syncserver_rs (storage) and syncserver_rs_tokenserver (config.toml, install). Before that it used MariaDB, and that upgrade did not copy the data: the clients uploaded it again. MariaDB databases of the same names left from then are old.
Recommended: start fresh. The database path is supported, into firefox-sync's PostgreSQL. As root on the YunoHost server:
sudo -u postgres pg_dump --no-owner --no-acl syncserver_rs_tokenserver > syncserver.sql
sudo -u postgres pg_dump --no-owner --no-acl --exclude-table=__diesel_schema_migrations syncserver_rs > syncstorage.sql
sudo -u postgres pg_dump --data-only --table=__diesel_schema_migrations syncserver_rs > syncstorage-migrations.sql
Load the three files in this order, as for the two-database PostgreSQL, then Loading into firefox-sync. Firefox: YunoHost's address is https://<domain><path>/1.0/sync/1.5. With a path, change the setting on the devices, or rewrite the path in your reverse proxy. Remove the app once all devices synced.
Tested: the app's layout in containers, not on YunoHost: tests/migrate.sh yunohost, syncstorage-rs 0.23.3 on PostgreSQL 15 (bookworm's) with the two databases of one owner, the commands above run as postgres in the database container. The path rewrite and the MariaDB databases of before 0.23.3~ynh9: not tested.
The Python syncserver¶
mozilla-services/syncserver, archived by Mozilla in 2023 and replaced by syncstorage-rs, and the images built on it: crazy-max/docker-firefox-syncserver (archived), snw35/ffsync, mozilla/syncserver. It keeps the tokenserver and the storage in one SQLAlchemy database (syncserver.sqluri: SQLite syncserver.db by default, or MySQL or PostgreSQL) with its own schema, which syncstorage-rs does not read.
Recommended: start fresh only. Its address is https://<host>/token/1.0/sync/1.5. Either change the setting on the devices to firefox-sync's .../1.0/sync/1.5, or keep the host name and have your reverse proxy send /token/ to firefox-sync without the prefix:
location /token/ { proxy_pass http://127.0.0.1:5000/; }
Tested: no.
jackyzy823/fxa-selfhosting¶
jackyzy823/fxa-selfhosting runs Mozilla accounts and the Python syncserver, from docker-compose.tmpl.yml and your config.yml (config.yml.sample):
- one MySQL 8.4 container
mysqldb, userrootwithout a password, data in<persistencepath>/mysql_data: the accounts infxa,fxa_oauth,fxa_profileandpushbox(created by Mozilla'spatcher.mjs, like here), the Python syncserver insync; fxa_versioninconfig.yml(v1.342.2in the sample): the release ofmozilla/fxa-mono;- the keys, generated inside the
fxa-auth-servercontainer at every start when missing, in/fxa/packages/fxa-auth-server/dist/packages/fxa-auth-server/config/:secret-key.json,public-key.json,vapid-keys.json,key.json(andnewKey.json,oldKey.jsonafter a key rotation). There is no volume for them: a new container gets new keys; - the avatars in
<persistencepath>/public; - the host names
<content>,<auth>,<oauth>,<profile>,<sync>ofdomain.name(www,api,oauth,profile,tokenin the sample): the accounts API and OAuth on two host names (here one,FXA_AUTH_URL), and Sync athttps://token.<domain>/token/1.0/sync/1.5.
The accounts must move: an account is the record in fxa.accounts, and its Sync keys are derived from its password and that record. New accounts, even with the same email and password, have new keys, and every device would have to sign up again. The Sync data cannot move (Python syncserver): start fresh for it, after the accounts moved. None of this has been tested.
- Check the versions. firefox-sync runs the newest accounts release it tested (
FXA_VERSION=fxa-mono-latest). It must be the same asfxa_versionor newer: the migrations only go forward. If yours is newer, pinFXA_VERSIONto a release at least as new (fxa-mono-<release>, see Self-hosted accounts). -
Set up firefox-sync with self-hosted accounts on MySQL (Set up), but don't start it. Then in
.env:- keep the old public URLs:
FXA_CONTENT_URL=https://<content>.<domain>,FXA_AUTH_URL=https://<auth>.<domain>,FXA_PROFILE_URL=https://<profile>.<domain>,FXA_EMAIL_DOMAIN=<auth>.<domain>; - set
FXA_OAUTH_SECRETandFXA_AUTH_SECRETtosecrets.authsecret, andFXA_PROFILE_SECRETtosecrets.profileserver_authsecret_bearertokenofconfig.yml. That may not be needed, but it is the safe side. If they are still the sample values, use new ones and expect to sign in again everywhere; SYNC_PUBLIC_URLcan behttps://<sync>.<domain>.
- keep the old public URLs:
-
On the old server, stop everything but the database, dump the accounts and copy the keys:
docker compose stop && docker compose start mysqldb docker compose exec -T mysqldb mysqldump -uroot --single-transaction --set-gtid-purged=OFF --routines --triggers \ --databases fxa fxa_oauth fxa_profile pushbox > fxa.sql mkdir old-keys for f in secret-key.json public-key.json vapid-keys.json key.json newKey.json oldKey.json; do docker compose cp fxa-auth-server:/fxa/packages/fxa-auth-server/dist/packages/fxa-auth-server/config/$f old-keys/ done # newKey.json and oldKey.json are often missing; without the old container, skip this -
In firefox-sync, load the dump into the new, empty
fxa-db, then the keys into thefxa-keysvolume and the avatars, all before the accounts start:The names come from compose/fxa.yml (docker compose up -d --wait fxa-db docker compose exec -T fxa-db sh -c 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mysql -uroot' < fxa.sql docker compose run --rm --no-deps -v "$PWD/old-keys:/old:ro" fxa-keys-owner sh -c ' cp /old/secret-key.json /old/public-key.json /old/vapid-keys.json /fxa-keys/ && cp /old/key.json /fxa-keys/openid-key.json && { [ ! -f /old/newKey.json ] || cp /old/newKey.json /fxa-keys/openid-newKey.json; } && { [ ! -f /old/oldKey.json ] || cp /old/oldKey.json /fxa-keys/openid-oldKey.json; } && chown 10001:10001 /fxa-keys/*.json' docker compose run --rm --no-deps --user root -v /path/to/old/public:/old:ro fxa-profile-worker sh -c ' cp -a /old/. /fxa/packages/fxa-profile-server/var/public/ && chown -R 10001:10001 /fxa/packages/fxa-profile-server/var/public' docker compose up -dSECRET_KEY_FILE,PUBLIC_KEY_FILE,VAPID_KEYS_FILE,FXA_OPENID_KEYFILE,FXA_OPENID_NEWKEYFILE,FXA_OPENID_OLDKEYFILE).fxa-migrationsthen upgrades the schema,fxa-policyinstalls the sign-up policy, and the OAuth clients are registered again forFXA_CONTENT_URL. Leave outsync(the Python syncserver) andffs. Loading into MariaDB (FXA_DB=mariadb) is not covered: keep MySQL. -
Set up the reverse proxy (
proxy/ofprepare_environment.sh, Reverse proxy): the content, auth and profile host names to the new ports, and also<oauth>.<domain>toFXA_AUTH_EXPORT_PORT, because Firefox keeps the OAuth address it read when it signed in. For Sync, either keephttps://<sync>.<domain>with/token/sent to firefox-sync without the prefix (location /token/ { proxy_pass http://127.0.0.1:5000/; }) and the rest to firefox-sync as it is, or change the devices (next step). -
Firefox: the accounts address stays the same (Self-hosted accounts).
- With the
/token/rewrite, the devices stay signed in and upload their data to the empty Sync server. - Without it, sign out on each device (keeping the data), restart Firefox and sign in again with the same email and password: Firefox reads the addresses again from the accounts server. On Android also set
Custom Sync servertoSYNC_PUBLIC_URL/1.0/sync/1.5.
Start with the device that has the most data, as in Start fresh first.
- With the
Checking: the admin UI lists the old accounts with their emails, docker compose exec fxa-db sh -c 'MYSQL_PWD="$MYSQL_ROOT_PASSWORD" mysql -uroot -e "SELECT COUNT(*) FROM fxa.accounts"' gives their number, and an existing account signed in on a new profile gets the bookmarks of its other devices: its keys did not change.
Rollback: stop firefox-sync, start the old stack and point the reverse proxy back. Accounts created and passwords changed in the meantime are not on the old server.
Tested: no.
Other setups¶
Helm charts (for example holysoles/fx-syncstorage-chart, MySQL), the Home Assistant add-on Aghabeiki/firefox-sync-addon (MariaDB) and other packagings of syncstorage-rs work the same way. Find the database type and the database names in their configuration (SYNC_SYNCSTORAGE__DATABASE_URL and SYNC_TOKENSERVER__DATABASE_URL, or syncstorage.database_url and tokenserver.database_url), then start fresh, or dump as in Moving the database. One database for both is split as for NixOS (MySQL or MariaDB), or loaded as it is (PostgreSQL).
Tested: no.