Skip to content

firefox-sync documentation

Self-host Firefox Sync with Docker, Podman or Kubernetes: your bookmarks, passwords, history and tabs stay on your own server instead of Mozilla's, and optionally the Mozilla accounts too. The images are built from Mozilla's code with as few changes as possible, see why these images.

This is the index of every page. New here: read What you need, then follow Choose your path.

What you need

  • A server that runs containers: Docker with the compose plugin, Podman, or a Kubernetes cluster.
  • A host name with HTTPS for the Sync server, for example sync.example.com, behind your reverse proxy (the setup writes its configuration, or runs a bundled Caddy) or an Ingress. See Reverse proxy.
  • A database. By default the stack runs its own MariaDB containers. It can run MySQL or PostgreSQL instead, or use a server you already run: see Databases.
  • For self-hosted accounts only: more host names, more memory and an SMTP server. See their requirements.

Each install page lists what its platform needs on top of this.

Choose your path

  1. Install the stack, one of:

  2. Point your reverse proxy to it, with the configuration the setup wrote into proxy/, or let the bundled Caddy do it.

  3. Decide who can use your server.
  4. Set up Firefox on every device.
  5. Turn on the backups.

Optional, at any time: self-hosted accounts, the admin UI, your own database server.

The admin UI's overview

The admin UI: accounts, storage, health, setup checks and alerts.

Every page

Setting up:

  • install/compose.md: docker compose
  • install/podman.md: rootless Podman, with Quadlets or docker compose on the Podman socket
  • install/helm.md: Kubernetes with the Helm chart
  • reverse-proxy.md: host names and ports, request size, the sign-up gate, pairing, the client IP address, publishing the admin UI
  • access-control.md: access control, which setting decides who can sync, reach the server and run it
  • limits.md: who can use your server, SYNC_MAX_USERS, invite-only Sync (SYNC_ALLOWED_ACCOUNTS) and FXA_MAX_ACCOUNTS
  • single-sign-on.md: single sign-on (Authelia) and client certificates in front of the accounts pages and the admin UI, and why not the other hosts
  • firefox.md: Firefox on desktop, Android and iOS, with Mozilla's accounts or yours
  • accounts.md: self-hosted Mozilla accounts, and their telemetry, all off
  • databases.md: choosing a backend, the supported versions, your own database server

Running it:

  • backups.md: what to keep, the backup service, copying off, restoring
  • upgrading.md: new images, the earlier firefox-sync release (and Watchtower on its images), renamed settings, database majors. What changed in each release: CHANGELOG.md
  • migrating.md: from another Sync server, or from docker compose to Kubernetes
  • troubleshooting.md: symptoms and fixes, by area

The admin UI:

Reference:

For contributors:

Getting help

Search or open an issue. Give your install method, your database backend, the versions you run and the logs, with the secrets removed.