firefox-sync

The purpose of this repository is to provide a docker-compose that can be used to self host what otherwise Firefox sync would send to Mozilla's servers. A Mozilla account is required to use this self-hosted setup.

🐳 Docker and 🦭 Podman supported - See PODMAN.md for Podman-specific instructions, including rootless setup and Quadlet integration.

• ⚠️ The project is under development
• ⚠️ Expect bugs, breaking changes and headache
• ⚠️ This is not endorsed or supported by Mozilla in any way or form
• ⚠️ Do not solely relay on this project to store your bookmarks, passwords and/or other important items

1. - syncstorage-rs does NOT support account allowlisting. This means that ANY person that has network access to your server can use it.
   • This has been implemented with a SQL trigger workaround that prevents the token database to insert more rows when a new user tries to use the server. This is tested and prevents a new account from using your server if the number of MAX_USERS defined in your .env file is already reached.
   • Possible alternative (better) solutions:
     • implement the feature directly in syncstorage-rs
     • add the entire rest of the Mozilla stack so that authentication is performed and validated locally

Mozilla's server side components are open source and Firefox allows to easily change the official endpoints. Some documentation is provided to install the each component on your own server but this is neither officially supported or very well maintained. Furthermore, there are no official Docker images that can be used to avoid installing everything manually; all the instructions and artifacts provided are focused on setting up a developer environment rather than a production self hosted service. For example, syncstorage-rs has a docker release on docker-hub but it is targeted to work exclusively with Google Spanner which is what Mozilla uses to provide the service.

• GitHub workflows to create docker images as vanilla as possible from Mozilla's code
• Docker compose to setup required component to self host Mozilla sync components
• examples to configure other parts of the infrastructure
• instructions to setup your browser to use the self hosted infrastructure
• run Mozilla accounts (fxa), is out of scope. You will need to use the Mozilla's servers to authenticate or setup your own (example)

All the images are updated weekly to the latest tag available from Mozilla's official repositories

• ghcr.io/porelli/firefox-sync:syncstorage-rs-mysql-latest
  • GitHub workflow and logs
  • Base image: Mozilla's container
  • Base image differences: image built with SYNCSTORAGE_DATABASE_BACKEND=mysql and TOKENSERVER_DATABASE_BACKEND=mysql (DATABASE_BACKEND=mysql for releases before 0.23) to use the MySQL-compatible interface instead of Google Spanner
  • source code: https://github.com/mozilla-services/syncstorage-rs
    • code changes: none
• ghcr.io/porelli/firefox-sync:syncstorage-rs-mysql-init-latest
  • GitHub workflow and logs
  • Base image: MariaDB's container
  • Purpose: Post-migration database initialization and handling of MAX_USERS
  • Base image differences: added db_init.sh and db_init.sql scripts
  • source code: https://github.com/MariaDB/server
    • code changes: none
• ghcr.io/porelli/firefox-sync:syncstorage-rs-postgres-latest
  • same as syncstorage-rs-mysql but built with SYNCSTORAGE_DATABASE_BACKEND=postgres and TOKENSERVER_DATABASE_BACKEND=postgres to use PostgreSQL
• ghcr.io/porelli/firefox-sync:syncstorage-rs-postgres-init-latest
  • Base image: PostgreSQL's container
  • Purpose: Post-migration database initialization and handling of MAX_USERS
  • Base image differences: added db_init.sh and db_init.sql scripts
  • source code: https://github.com/postgres/postgres
    • code changes: none

1. clone this repository
2. run ./prepare_environment.sh to automatically prepare your .env file and conf examples according with your variables
   • you can choose between MariaDB (default, docker-compose.yml) and PostgreSQL (docker-compose.postgres.yml) as database backend. For PostgreSQL, the script sets COMPOSE_FILE in .env so that docker compose picks the right file automatically
   • you can pin the syncstorage image to a specific tag (default: latest)
3. setup your reverse proxy server
   1. if you use nginx, check the syncstorage-rs.conf as example
4. start docker compose:

   docker compose up -d

   • with Podman, use the Quadlets below or docker compose with the Podman socket, see PODMAN.md. podman-compose is not supported because it cannot run the one-shot migration and init containers before the service (why)
5. OPTIONAL: Install the systemd service
   • Docker: See firefox-sync.service
   • Podman: See PODMAN.md for Quadlet setup (recommended)
   • All containers are set to restart automatically

For native systemd integration with Podman, see the comprehensive Podman Guide. Quadlets are currently provided for MariaDB only.

Quick start:

./prepare_environment.sh  # Choose option 1 (Quadlets, the default) when prompted
systemctl --user start firefox-sync-syncstorage.service

Every image build runs the tests in tests/ before the multi-arch tags (e.g. syncstorage-rs-mysql-latest) are published:

• tests/e2e.sh <mysql|postgres>: starts the docker compose stack and checks start-up order, MAX_USERS, domain changes, a Firefox-like sign-in and sync through the tokenserver (test_client_flow.py, using upstream's mock FxA server) and runs upstream's storage and tokenserver integration tests
• tests/podman.sh: rootless Podman, with Quadlets and with docker compose on the Podman socket, configured with prepare_environment.sh

Both can be run locally against any published tag, e.g. TAG=latest tests/e2e.sh mysql.

Pre-requisite: if you already logged into your Firefox account you need to temporarily disconnect it

The below examples assume your server respond to this domain: firefox-sync.example.com

1. point a browser tab to about:config and search for identity.sync.tokenserver.uri
2. change it from the default to https://firefox-sync.example.com/1.0/sync/1.5
3. log in to Firefox and start syncing.

1. check logs pointing a browser tab to about:sync-log

1. go to App Menu ⋮ > Settings > About Firefox and click the logo 5 times. You should see a debug menu enabled notification
2. go back to the main setting menu and you will see Sync Debug at the top, just under the Synchronize and save your data box. Tap on it
3. tap on Custom Sync server and set it to https://firefox-sync.example.com/1.0/sync/1.5
4. log in to Firefox and start syncing.

1. go to App Menu ≡ > Settings and tap 5 times on the version number (i.e.: Firefox 127.1 (42781)) towards the bottom
2. go back at the top of the main setting menu and you will see Advanced Sync Settings at the top, just under the Sync and Save Data. Tap on it
3. activate Use Custom FxA Content Server and set Custom Account Content Server URI to https://firefox-sync.example.com/1.0/sync/1.5
4. log in to Firefox and start syncing.

• Mozilla for Firefox and opensourcing all their software, including the backend
• jeena for fxsync-docker which is the inspiration for this project