Install with Podman¶
This page installs the Sync server with rootless Podman, in one of two ways: Quadlets, which run the stack as systemd units of your user (recommended), or docker compose on the Podman socket. Read What you need first.
Requirements¶
- Podman 4.4 or later (install), set up for rootless use (Podman's rootless tutorial).
- For docker compose on the Podman socket:
docker compose, the version of docker compose. The Docker daemon is not needed. - A host name with HTTPS, proxied to the port of the Sync server: your reverse proxy, or the bundled Caddy. See Reverse proxy.
The stack uses named volumes only, so rootless Podman handles their ownership, and SELinux labels stay on.
| Quadlets | docker compose on the Podman socket | |
|---|---|---|
| MariaDB, MySQL, PostgreSQL | yes | yes |
| self-hosted accounts | yes | yes |
Quadlets¶
Quadlets are unit files that Podman turns into systemd services: see podman-systemd.unit(5).
-
Clone the repository and run the setup script:
git clone https://github.com/porelli/firefox-sync.git cd firefox-sync ./prepare_environment.shIt detects Podman and asks how the stack runs:
quadlets(the default). Its other questions are those of docker compose, and so are its answers by name (deploy=quadlets). It writes.env, copies the units of config/quadlet/ with your values into~/.config/containers/systemd/(the backup timer into~/.config/systemd/user/), and reloads systemd. The units hold no secret: the passwords, keys and tokens of a unit's container, andADMIN_NOTIFY, are in its environment file next to it,firefox-sync-<name>.env, readable by you only, which the unit reads (EnvironmentFile=). Values there are as they are in.env, without the escapes of systemd. -
Start the Sync server:
systemctl --user start firefox-sync-syncstorage.serviceIts dependencies start first: the databases, the migrations, the init container and, when you enabled it, the admin UI.
-
Let your units start at boot without a login:
loginctl enable-linger $USERQuadlets are generated units: their
[Install]section starts them at boot, andsystemctl enabledoes not work on them.
To install the units somewhere else than ~/.config/containers/systemd/, set QUADLET_DIR when you run the script:
QUADLET_DIR=/path/to/units ./prepare_environment.sh
Other choices of the setup script, with Quadlets:
- MySQL instead of MariaDB: see Databases.
- PostgreSQL: see Databases.
- Your own database server: see Databases.
- The admin UI: see Admin UI.
- The nightly backups: answered yes, it enables
firefox-sync-backup.timer, see Backups. The pairing server is not asked: the Quadlets have none. - The reverse proxy: its configuration is in
proxy/(Your own proxy), with the ports of this host the units publish (PublishPort=): one in use takes the next free port, said, and the script's last lines list the host names your proxy serves and their ports (Ports in use). Answeredcaddy, the bundled Caddy gets a unit of its own,firefox-sync-caddy.service, on the host's network: start it withsystemctl --user start firefox-sync-caddy.service. On ports 80 and 443, rootless Podman needsnet.ipv4.ip_unprivileged_port_start=80, which the script checks: see Rootless Podman and ports under 1024. The labels for Traefik are not offered: they are for docker compose.
Self-hosted accounts¶
If you chose to self-host Mozilla accounts, the script also installs their units, firefox-sync-fxa-*. Start them:
systemctl --user start firefox-sync-fxa-content.service firefox-sync-fxa-profile.service \
firefox-sync-fxa-profile-worker.service firefox-sync-fxa-profile-static.service
Their database, the migrations and the auth server start as dependencies. The rest of the setup is in Self-hosted accounts.
Check the units¶
Status and logs:
systemctl --user status firefox-sync-syncstorage.service
journalctl --user -u firefox-sync-syncstorage.service -f
journalctl --user -u 'firefox-sync-*' -f
Health: every unit that keeps running has the healthcheck of its compose service, with the same timings. podman ps shows (healthy) next to each. One at a time:
podman healthcheck run firefox-sync-syncstorage; echo $? # 0: healthy
The one-shot units have no healthcheck: the migrations, the init container, fxa-keys-owner, fxa-policy and the backups. systemctl --user status <unit> says how they ended.
Restart and stop:
systemctl --user restart firefox-sync-syncstorage.service
systemctl --user stop firefox-sync-syncstorage.service firefox-sync-syncstorage-db.service firefox-sync-tokenserver-db.service
With PostgreSQL the database unit is firefox-sync-postgres-db.service.
A new admin UI container restarts the Sync server: see Sync metrics.
Podman before 5: the units start before their database is healthy
Podman 4.9 (Ubuntu 24.04) orders the units on the start of their container, not on its health: Notify=healthy needs Podman 5. Where compose waits for a healthy database, the next unit retries on its own instead: the migrations of the Sync server for 2 minutes, those of the accounts for 5. Restart=always starts again what gave up.
Change a setting¶
The installed units and their environment files hold their own copy of the values of .env: a change of .env alone does nothing. To change a setting, or to pin an image (SYNC_IMAGE_TAG, ADMIN_IMAGE, SYNC_MARIADB_IMAGE...):
- Change it in
.env. -
Render the units again from
.env:./prepare_environment.sh --render-unitsIt asks nothing and keeps every password and secret. It reads
.envas compose does (single and double quotes with their escapes, a comment after the value,export,$$; not the${NAME}of other values), writes only the units and environment files that change and lists them, keeps all those of before inquadlets.before-<UTC time>/of the checkout (readable by you only), and reloads systemd. Run again, it changes nothing. Without installed units (a compose install) it refuses;./prepare_environment.sh --render-units --freshinstalls the units of.env. Before that it does to.envwhat--upgradedoes (Quadlets): on an.envof this release, nothing. -
Restart the units it listed. A new image: pull it first (
podman pull, the name of itsImage=line). For exampleSYNC_MAX_USERSis in the init container and, with the admin UI, in its unit; the migrations run again before the Sync server starts:systemctl --user restart firefox-sync-tokenserver-db-init.service firefox-sync-syncstorage.serviceWith the admin UI, also restart
firefox-sync-admin.servicewhenSYNC_MAX_USERSchanges between a plain number andinitial:N(Limits).
On a running install, ./prepare_environment.sh first asks whether to upgrade it (the default: the same as --upgrade) or set it up again. Don't set it up again (new) there: that writes a new .env from .env-example, with new passwords and secrets that the databases don't have. It keeps the old file as .env.before-setup-<UTC time>.
Upgrading the images: see Upgrading.
docker compose on the Podman socket¶
docker compose v2 can drive Podman through its Docker-compatible API, with the same compose files as Docker.
-
Run the setup script, and choose
composefor how the stack runs (deploy=composeby name):./prepare_environment.sh -
Start the Podman API socket of your user, and point
docker composeto it:systemctl --user enable --now podman.socket export DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock -
Check the optional services in
COMPOSE_PROFILESof.env, as for docker compose. -
Start the stack:
docker compose up -dCOMPOSE_FILEin.envhas the files of your choices (The compose files) and compose/podman.yml, which gives the Sync server's healthcheck more time, for slower rootless starts.
Everything else works as in docker compose: logs with docker compose logs -f, docker compose down to stop.
The bundled Caddy (PROXY=caddy) on the Podman socket runs on the host's network, as the Quadlets' does: on ports 80 and 443 it needs net.ipv4.ip_unprivileged_port_start=80 (Rootless Podman and ports under 1024). The labels for Traefik work there too, Traefik reading the Podman socket (Traefik labels).
Why not podman-compose?¶
The stack starts in a precise order: the databases, then a one-shot container running the migrations, then the one-shot init that installs the limit of users, and only then the public Sync server, so that nobody can sign in before the limit exists.
podman-compose links containers with podman create --requires. Podman refuses to start a container whose required container has already exited ("generating dependency graph for container"), so the init and the Sync server never start. podman-compose also does not check that a one-shot container exited successfully. Use Quadlets or docker compose instead.
Something fails: see Troubleshooting.