Settings¶
Every setting of the stack, once: its name in .env, its Helm value, its default, what it does, and its old name if it was renamed. The tasks that use them are on the other pages: start from the docs index.
How to read the tables:
.env: the setting in the.envof docker compose and the Quadlets.prepare_environment.shwrites it; .env-example has every line with its default. The Quadlets hold their own copy of the values: see Change a setting.- Helm: the value in the chart's values.yaml. "Secret:
KEY" is a key of the chart's Secret or of your existingSecret. "–" means the chart has no such value. - Default: the value of
.env-example(Helm: ofvalues.yaml). "generated" meansprepare_environment.sh(Helm: the chart) generates a random one. "unset" is what compose uses when the line is missing. - Old name: the name before the
SYNC_prefix. Compose still reads it: see Renamed settings.
Sync¶
.env |
Helm | Default | Meaning | Old name |
|---|---|---|---|---|
SYNC_PUBLIC_URL |
syncDomain |
required | the public https:// URL of the Sync server, which the init container sets as the node of the tokenserver. Firefox uses <it>/1.0/sync/1.5 |
SYNCSTORAGE_DOMAIN |
SYNC_MAX_USERS |
maxUsers |
1 (Helm "1") |
how many accounts can use the server: N, fixed:N, initial:N or unlimited. The forms: Limits |
MAX_USERS |
SYNC_ALLOWED_ACCOUNTS |
allowedAccounts |
empty: off | invite-only Sync, the uids that can start to sync: <uid>,..., fixed:<uid>,..., admin or initial:<uid>,.... The forms: Limits |
|
SYNC_MASTER_SECRET |
Secret: SYNC_MASTER_SECRET |
generated | signs the Sync tokens. A new one signs every Firefox out | |
SYNC_METRICS_HASH_SECRET |
Secret: METRICS_HASH_SECRET |
generated | the key of the hash of the account ids in the metrics | METRICS_HASH_SECRET |
SYNC_EXPORT_PORT |
– (the Service, port syncstorage.service.port, 8000) |
127.0.0.1:5000 |
where the host publishes the Sync server for your reverse proxy: [address:]port. A port alone in .env publishes it on every interface: Host names and ports. The setup takes the next free port when something else listens there, as for every *_EXPORT_PORT (Ports in use) |
CONTAINER_EXPORT_PORT |
FXA_OAUTH_SERVER_URL |
fxa.oauthServerUrl |
https://oauth.accounts.firefox.com/v1 |
where the tokenserver checks the sign-in tokens. Self-hosted accounts: http://fxa-auth:9000/v1 always, container-to-container: inside the stack the accounts API listens on 9000, whatever the host port FXA_AUTH_EXPORT_PORT is (Sign-in keys: connection refused; Helm: the chart sets it with fxa.enabled) |
|
FXA_EMAIL_DOMAIN |
fxa.emailDomain |
api.accounts.firefox.com |
the tokenserver keeps each account as <uid>@FXA_EMAIL_DOMAIN. Self-hosted accounts: the host of FXA_AUTH_URL (Helm: set by the chart). A new value makes every account a new one |
|
COMPOSE_FILE |
– | unset: docker-compose.yml, Sync on MariaDB (installs from before compose/) |
the compose files, separated by :: compose/sync.yml, the Sync database's, the accounts', the reverse proxy's (The compose files) |
|
COMPOSE_PROJECT_NAME |
– | unset: the directory of the first compose file | the compose project, which names the containers and volumes: prepare_environment.sh writes the checkout's directory, as compose names it (lowercase, a-z 0-9 _ -, no _ or - first), and keeps a name already there. A copy of the checkout keeps the name of the original, and its docker compose down -v removes the original's volumes: a copy, or a second stack, needs a name of its own here. The setup and --upgrade warn when the name is not the directory's (The compose files) |
|
COMPOSE_PROFILES |
admin.enabled, backup.enabled |
unset: none | the optional services that run, the whole list comma-separated: admin, backup, pairing (self-hosted accounts), see Optional services |
Images¶
Which tags exist, and what each image is: Images. When to pin them: Upgrading.
.env |
Helm | Default | Meaning | Old name |
|---|---|---|---|---|
IMAGE_REPOSITORY |
image.repository |
ghcr.io/porelli/firefox-sync |
the registry and repository of the Sync, init and admin UI images | REPOSITORY |
SYNC_IMAGE |
– (follows database.backend) |
syncstorage-rs-mysql |
the Sync server's image: syncstorage-rs-mysql (MariaDB, MySQL) or syncstorage-rs-postgres |
SYNCSTORAGE_IMAGE |
SYNC_IMAGE_TAG |
image.syncstorageTag |
latest |
its tag | SYNCSTORAGE_IMAGE_TAG |
SYNC_INIT_IMAGE |
– (follows database.backend) |
syncstorage-rs-mysql-init |
the init container's image: syncstorage-rs-mysql-init or syncstorage-rs-postgres-init |
SYNCSTORAGE_INIT_IMAGE |
SYNC_INIT_IMAGE_TAG |
image.initTag |
latest |
its tag | SYNCSTORAGE_INIT_IMAGE_TAG |
ADMIN_IMAGE |
image.adminTag (the tag only) |
unset: <IMAGE_REPOSITORY>:admin-latest |
the admin UI's whole image name, also that of fxa-policy (compose and the Quadlets) |
|
| – | image.pullPolicy |
IfNotPresent |
with IfNotPresent a node that has latest does not pull a newer one: Helm |
The accounts' images are under Accounts, the database images under Databases.
Databases¶
The stack's own database containers. For a server you run yourself, see also Your own database server. The users and their grants: Database users.
.env |
Helm | Default | Meaning | Old name |
|---|---|---|---|---|
SYNC_DB |
database.backend |
mariadb |
the Sync database containers: mariadb or mysql (MySQL instead of MariaDB). PostgreSQL: compose/sync-postgres.yml in COMPOSE_FILE (Helm: postgres) |
|
SYNC_MARIADB_IMAGE |
database.image.mariadb |
unset: mariadb:lts (Helm docker.io/library/mariadb:lts) |
with SYNC_DB=mariadb, the MariaDB image of the Sync databases and of their backups. Pins: Database majors |
|
SYNC_MYSQL_IMAGE |
database.image.mysql |
unset: mysql:lts (Helm docker.io/library/mysql:lts) |
with SYNC_DB=mysql, the MySQL image of the Sync databases and of their backups. Pins: Database majors |
|
SYNC_POSTGRES_IMAGE |
database.image.postgres |
unset: postgres:latest; prepare_environment.sh writes the major it finds |
the PostgreSQL image of the Sync database and of its backups, compose's and the Quadlets'. Pin the major: PostgreSQL | |
SYNC_TOKENSERVER_DB_PASSWORD |
Secret: TOKENSERVER_DB_PASSWORD |
generated | the tokenserver user's password (MariaDB, MySQL) | MARIADB_TOKENSERVER_PASSWORD |
SYNC_STORAGE_DB_PASSWORD |
Secret: STORAGE_DB_PASSWORD |
generated | the storage user's password (MariaDB, MySQL) | MARIADB_SYNCSTORAGE_PASSWORD |
SYNC_POSTGRES_PASSWORD |
Secret: POSTGRES_PASSWORD |
generated | the password of SYNC_POSTGRES_USER: the container's superuser; on your own server, the owner of the database |
POSTGRES_PASSWORD |
SYNC_POSTGRES_APP_USER |
database.postgresSyncUser |
empty (prepare_environment.sh: syncserver_app; Helm syncserver_app) |
the Sync server's own role in the PostgreSQL container, no superuser. Empty (an install from before, or your own server): the Sync server connects as SYNC_POSTGRES_USER |
|
SYNC_POSTGRES_APP_PASSWORD |
Secret: POSTGRES_SYNC_PASSWORD |
generated | its password | |
ADMIN_DB_NAME |
database.admin.name |
ffs_admin |
the admin UI's own database, on the tokenserver's server | |
ADMIN_DB_USER |
database.admin.user |
ffs_admin_ui |
the admin UI's user of that database, and only of it | |
ADMIN_DB_SYNC_USER |
database.admin.syncUser |
ffs_admin_sync |
the admin UI's reader of the Sync data, with nothing on ffs_admin |
|
ADMIN_DB_PASSWORD |
Secret: ADMIN_DB_PASSWORD |
generated | the password of both admin UI users. Empty: an install from before it, see The admin UI's own database | |
| – | database.persistence.size, .storageClass |
8Gi, the cluster's default |
the volumes of the database servers. Set them before the first install: Volumes | |
| – | database.resources |
none | requests and limits of each database server: Resources |
Your own database server¶
How to set it up: Your own database server. The accounts' database settings are under Accounts.
.env |
Helm | Default | Meaning | Old name |
|---|---|---|---|---|
SYNC_DB_CONTAINERS |
database.bundled |
1 (Helm true) |
0 (Helm false): no Sync database containers, use your own server |
|
SYNC_DB_TLS_VERIFY |
database.external.tlsVerify |
true (Helm false) |
whether the init container's client (and the chart's backups) checks the server's certificate. false for your own MySQL, whose certificate is self-signed. The Sync server itself connects without TLS |
|
SYNC_DB_BOOTSTRAP_USER |
database.external.bootstrap.user |
empty | an account that can create users, as which the stack applies the setup migrations your server lacks itself at every start; empty: it only checks them. See Let the stack apply them | |
SYNC_DB_BOOTSTRAP_PASSWORD |
Secret: SYNC_DB_BOOTSTRAP_PASSWORD |
empty | its password | |
SYNC_TOKENSERVER_DB_HOST |
database.external.host |
tokenserver_db |
the tokenserver's server: a host name or IPv4 address the containers reach (Helm: required) | MARIADB_TOKENSERVER_SERVER |
SYNC_TOKENSERVER_DB_PORT |
database.external.port |
3306 (Helm empty: 3306, or 5432 for postgres) |
its port | MARIADB_TOKENSERVER_SERVER_PORT |
SYNC_TOKENSERVER_DB_NAME |
database.external.tokenserverDatabase |
tokenserver |
the tokenserver database | MARIADB_TOKENSERVER_DATABASE |
SYNC_TOKENSERVER_DB_USER |
database.external.tokenserverUser |
tokenserver |
its user | MARIADB_TOKENSERVER_USER |
SYNC_STORAGE_DB_HOST |
database.external.storageHost |
syncstorage_db (Helm empty: host) |
the storage database's server | MARIADB_SYNCSTORAGE_SERVER |
SYNC_STORAGE_DB_PORT |
database.external.storagePort |
3306 (Helm empty: port) |
its port | MARIADB_SYNCSTORAGE_SERVER_PORT |
SYNC_STORAGE_DB_NAME |
database.external.storageDatabase |
syncstorage |
the storage database | MARIADB_SYNCSTORAGE_DATABASE |
SYNC_STORAGE_DB_USER |
database.external.storageUser |
syncstorage |
its user | MARIADB_SYNCSTORAGE_USER |
SYNC_POSTGRES_HOST |
database.external.host |
postgres_db |
the PostgreSQL server. With the database container the Quadlets reach it as firefox-sync-postgres-db, whatever this says |
POSTGRES_SERVER |
SYNC_POSTGRES_PORT |
database.external.port |
5432 |
its port | POSTGRES_SERVER_PORT |
SYNC_POSTGRES_NAME |
database.external.postgresDatabase |
syncserver |
the one Sync database | POSTGRES_DATABASE |
SYNC_POSTGRES_USER |
database.external.postgresUser |
syncserver |
in the stack's container its superuser; on your own server the owner of that database, no superuser | POSTGRES_USER |
The passwords are under Databases. With your own server and the Helm chart, existingSecret is required: see existingSecret.
Backups¶
How they work: Backups.
.env |
Helm | Default | Meaning | Old name |
|---|---|---|---|---|
COMPOSE_PROFILES with backup (Quadlets: firefox-sync-backup.timer) |
backup.enabled |
off | the nightly backups | |
BACKUP_TIME |
backup.schedule (cron, UTC) |
03:00 (Helm "0 3 * * *") |
when they run, UTC | |
BACKUP_KEEP |
backup.keep |
7 |
the newest runs kept; older ones are deleted | |
| – | backup.activeDeadlineSeconds |
82800 |
a run still going after this many seconds is stopped and fails | |
| – | backup.persistence.size, .storageClass |
10Gi, the cluster's default |
the backups' PVC; it grows with a StorageClass of allowVolumeExpansion: Volumes |
|
| – | backup.resources |
none | the backup container and the Job that binds its PVC |
Admin UI¶
What it does: Admin UI.
.env |
Helm | Default | Meaning | Old name |
|---|---|---|---|---|
COMPOSE_PROFILES with admin |
admin.enabled |
off | the admin UI | |
ADMIN_PASSWORD |
admin.password (Secret: ADMIN_PASSWORD) |
generated (Helm empty: generated) | the sign-in password. Empty in the Secret: no password sign-in | |
ADMIN_EXPORT_PORT |
– (kubectl port-forward, or admin.ingress.*) |
127.0.0.1:8090 |
where the host publishes the admin UI | |
ADMIN_TZ |
admin.tz |
empty: UTC | the time zone of the pages and the alerts, for example Europe/Rome |
|
ADMIN_METRICS_TOKEN |
admin.metricsToken (Secret: ADMIN_METRICS_TOKEN) |
empty: off | the bearer token of the Prometheus metrics at /metrics: Prometheus |
|
ADMIN_UPDATE_CHECK |
admin.updateCheck |
true |
compare the running versions with the newest releases on GitHub | |
ADMIN_PUBLIC_CHECK |
admin.publicCheck |
true |
every hour, check the public https:// URLs, their certificates and the sign-up gate: Public checks |
|
| – | admin.podStatus |
false |
the admin UI reads the pods of the release (a Role to get and list pods in its namespace) to tell a part starting from a crashed one right after a start; off: a time-bounded wait, see Startup grace. Docker and Podman: never (their socket would give the admin UI the host) | |
ADMIN_STALE_DAYS |
admin.staleDays |
90 |
accounts not synced for this many days are marked inactive | |
ADMIN_RETENTION_DAYS |
admin.retentionDays |
30 |
days of metrics and events kept: Maintenance and retention | |
ADMIN_AUDIT_RETENTION_DAYS |
admin.auditRetentionDays |
365 |
days the events of the admins (who did what) and the backup runs are kept | |
ADMIN_PURGE |
admin.purge |
empty: only with "Purge now" | 1: every day, delete the Sync data nobody reads any more: Storage |
|
ADMIN_DELETE_UNCONFIRMED_DAYS |
admin.deleteUnconfirmedDays |
empty: never | self-hosted accounts: every day, delete the accounts that never confirmed their email after this many days (at least 1) | |
ADMIN_UNCONFIRMED_HOURS |
admin.unconfirmedHours |
empty: 72 |
self-hosted accounts: an account that has not confirmed its email this many hours after its sign-up is marked unconfirmed in the accounts list | |
ADMIN_SIGNUP_BURST |
admin.signupBurst |
10 |
self-hosted accounts: an alert when more accounts than this are created in an hour (0: never) |
|
ADMIN_ERROR_RATE_PERCENT |
admin.errorRatePercent |
10 |
an alert on a spike of Sync errors: this share (%) of the requests in 15 minutes, and 3 times the share of the day before (0: never) |
|
ADMIN_ERROR_RATE_MIN_ERRORS |
admin.errorRateMinErrors |
20 |
the fewest errors for that alert | |
ADMIN_DB_GROWTH_MB |
admin.dbGrowthMb |
1024 |
an alert when a database grows more than this many MB in a day (0: never) |
|
ADMIN_DB_GROWTH_FACTOR |
admin.dbGrowthFactor |
5 |
an alert when a database grows more than this many times its usual daily growth, from 100 MB and 3 days of history (0: never): Errors and growth |
|
ADMIN_GATE_EXPORT_PORT |
– (the Service <release>-firefox-sync-admin, port 8081) |
127.0.0.1:8091 |
self-hosted accounts: where the host publishes the sign-up gate, for POST /v1/account/create of FXA_AUTH_URL: Reverse proxy |
|
| – | admin.resources |
none | the admin UI's container and its init container | |
| – | admin.ingress.enabled, .className, .host, .tls.enabled, .tls.secretName, .annotations |
off | the admin UI's own Ingress, never on the Sync server's host: Admin UI |
Admin UI sign-in¶
How each way works: Signing in.
.env |
Helm | Default | Meaning | Old name |
|---|---|---|---|---|
ADMIN_OIDC_ISSUER |
admin.oidc.issuer |
empty: off | the OpenID Connect issuer URL. With ADMIN_FXA_CLIENT_ID it defaults to FXA_CONTENT_URL |
|
ADMIN_OIDC_CLIENT_ID |
admin.oidc.clientId |
empty | the client id | |
ADMIN_OIDC_CLIENT_SECRET |
admin.oidc.clientSecret (Secret: ADMIN_OIDC_CLIENT_SECRET) |
empty: a public client (PKCE only) | the client secret | |
ADMIN_OIDC_REDIRECT_URL |
admin.oidc.redirectUrl |
empty | the exact public callback URL, https://<admin host>/auth/callback |
|
ADMIN_OIDC_SCOPES |
admin.oidc.scopes |
empty: openid email profile |
the scopes asked for | |
ADMIN_OIDC_NAME |
admin.oidc.name |
empty: single sign-on |
the label of the sign-in button | |
ADMIN_OIDC_GROUPS_CLAIM |
admin.oidc.groupsClaim |
empty: groups |
the claim with the groups, for ADMIN_ALLOWED_GROUPS |
|
ADMIN_OIDC_TRUST_UNVERIFIED_EMAIL |
admin.oidc.trustUnverifiedEmail |
empty: refused | true: accept emails without email_verified=true. Risky; needed with the self-hosted accounts |
|
ADMIN_AUTH_HEADER |
admin.trustedHeader.header |
empty: off | the header with the email, set by a forward-auth proxy: Trusted header | |
ADMIN_AUTH_GROUPS_HEADER |
admin.trustedHeader.groupsHeader |
empty: none | the header with the comma-separated groups | |
ADMIN_TRUSTED_PROXIES |
admin.trustedHeader.trustedProxies |
empty | the CIDRs of the proxy as the admin UI sees it. Required with the header: from other addresses it is ignored | |
ADMIN_ALLOWED_USERS |
admin.allowed.users |
empty: nobody by email | with OpenID Connect or the header, who is an admin: emails and @domains, comma-separated |
|
ADMIN_ALLOWED_GROUPS |
admin.allowed.groups |
empty: none | the same, by group | |
ADMIN_INSECURE_COOKIE |
admin.insecureCookie |
empty: Secure only |
1, true or yes (empty, 0, false or no: off; anything else stops the admin UI): the session cookie also goes over plain HTTP other than http://localhost, where anybody on the way can take it. Needed for an http:// ADMIN_OIDC_REDIRECT_URL; the Configuration page lists it as a setting that disagrees |
|
ADMIN_FXA_CLIENT_ID |
fxa.adminClientId, with admin.fxaSignIn |
empty (Helm: derived from the namespace and the release, Sign in with the accounts) | sign in with the self-hosted accounts: an OAuth client id (16 hex characters), registered at every start with ADMIN_OIDC_REDIRECT_URL: Self-hosted accounts |
|
ADMIN_FXA_CLIENT_SECRET |
fxa.adminClientSecret (Secret: ADMIN_FXA_CLIENT_SECRET) |
empty | keep it empty: the accounts service refuses PKCE from clients with a secret, and the admin UI always uses PKCE |
Notifications¶
The alerts and the emails of the admin UI: Alerts. The same SMTP server sends the self-hosted accounts' emails, so in the chart it is the top-level smtp.*, not under admin.
.env |
Helm | Default | Meaning | Old name |
|---|---|---|---|---|
ADMIN_ALERT_EMAIL |
admin.alertEmail |
empty: nobody | where the alerts go by email | |
ADMIN_NOTIFY |
admin.notify (a list; Secret: ADMIN_NOTIFY) |
empty: nowhere | the other destinations of the alerts, their URLs comma-separated, in single quotes: Destinations. The URLs hold tokens: keep .env private |
|
FXA_SMTP_HOST |
smtp.host |
a placeholder (Helm empty: no emails) | the SMTP server | |
FXA_SMTP_PORT |
smtp.port |
587 |
its port | |
FXA_SMTP_USER |
smtp.user |
empty: none | its user | |
FXA_SMTP_PASS |
smtp.password (Secret: FXA_SMTP_PASS) |
empty | its password | |
FXA_SMTP_SECURE |
smtp.secure |
false |
true: TLS from the start (port 465); false: STARTTLS |
|
FXA_SMTP_SENDER |
smtp.sender |
"Mozilla accounts <no-reply@<your domain>>" |
the From of the emails. Empty, the admin UI uses ADMIN_ALERT_EMAIL |
|
ADMIN_SMTP_INSECURE_AUTH |
smtp.insecureAuth |
empty: refused | 1, true or yes (as ADMIN_INSECURE_COOKIE): the admin UI sends FXA_SMTP_PASS also to an SMTP server that offers no TLS, in clear (a relay on the host or a network you trust only) |
admin.password, smtp.password, admin.oidc.clientSecret, admin.metricsToken and admin.notify end up in a Secret: how, with and without existingSecret, is in The Secret.
Accounts¶
The self-hosted Mozilla accounts, with compose/fxa.yml in COMPOSE_FILE: Self-hosted accounts. With the Helm chart, fxa.enabled: true: Self-hosted accounts. The chart's values with no .env counterpart are in Helm only.
.env |
Helm | Default | Meaning | Old name |
|---|---|---|---|---|
FXA_IMAGE |
fxa.image.repository (empty: image.repository) |
ghcr.io/porelli/firefox-sync |
the accounts' image. Mozilla's own: docker.io/mozilla/fxa-mono (amd64 only) |
|
FXA_VERSION |
fxa.image.tag |
fxa-mono-latest |
its tag: the newest tested release, or a pinned one such as fxa-mono-v1.349.0. Upgrading |
|
FXA_ARCH |
– (the node's) | amd64 |
amd64 or arm64, set by prepare_environment.sh (amd64 with Mozilla's images) |
|
FXA_CONTENT_URL |
fxa.contentUrl |
required | the public URL of the accounts pages, for example https://accounts.example.com |
|
FXA_AUTH_URL |
fxa.authUrl |
required | the public URL of the accounts API | |
FXA_PROFILE_URL |
fxa.profileUrl |
required | the public URL of the profile server | |
FXA_DB |
fxa.database.backend |
mysql |
the accounts database: mysql or mariadb (MySQL or MariaDB). With compose, mariadb also needs compose/fxa-mariadb.yml in COMPOSE_FILE, not compose/fxa-mysql.yml |
|
FXA_MYSQL_IMAGE |
fxa.database.image.mysql |
unset: mysql:lts (Helm docker.io/library/mysql:lts) |
with FXA_DB=mysql, the image of fxa-db and of its backups. Pins: Database majors |
|
FXA_MYSQL_ARGS |
– (from fxa.database.image.mysql: the native password options on a MySQL 8 pin, Database majors) |
empty | extra options of fxa-db's mysqld. On mysql:8 for accounts images without mozilla/fxa#21709: --mysql-native-password=ON --authentication-policy=mysql_native_password |
|
FXA_MARIADB_IMAGE |
fxa.database.image.mariadb |
unset: mariadb:lts (Helm docker.io/library/mariadb:lts) |
with FXA_DB=mariadb, the image of fxa-db and of its backups |
|
FXA_DB_CONTAINERS |
fxa.database.bundled (0: false) |
1 (Helm true) |
0: no fxa-db container, use your own MySQL or MariaDB server |
|
FXA_MYSQL_HOST |
fxa.database.external.host |
fxa-db (Helm: <release>-firefox-sync-fxa-db while bundled) |
the accounts' database server | |
FXA_MYSQL_PORT |
fxa.database.external.port |
3306 (Helm empty: 3306) |
its port | |
FXA_MYSQL_USER |
fxa.database.external.user |
root (Helm: root while bundled, else fxa) |
the accounts services' user (on your own server, for example fxa) |
|
FXA_MYSQL_PASSWORD |
Secret: FXA_MYSQL_PASSWORD |
generated | its password | |
FXA_MYSQL_POLICY_USER |
fxa.database.external.policyUser |
empty: FXA_MYSQL_USER (Helm ffs_policy) |
the user that installs the sign-up policy and grants the admin UI's user | |
FXA_MYSQL_POLICY_PASSWORD |
Secret: FXA_MYSQL_POLICY_PASSWORD |
empty (Helm: never generated) | its password (not used while FXA_MYSQL_POLICY_USER is empty) |
|
FXA_DB_BOOTSTRAP_USER |
fxa.database.external.bootstrap.user |
empty | as SYNC_DB_BOOTSTRAP_USER, for database-setup-fxa.sql on your own accounts server |
|
FXA_DB_BOOTSTRAP_PASSWORD |
Secret: FXA_DB_BOOTSTRAP_PASSWORD |
empty | its password | |
FXA_ADMIN_DB_PASSWORD |
Secret: FXA_ADMIN_DB_PASSWORD |
generated | the password of the admin UI's user ffs_admin of the accounts database (a user, not the database ADMIN_DB_NAME) |
|
FXA_AUTH_SECRET, FXA_OAUTH_SECRET, FXA_PROFILE_SECRET, FXA_FLOW_ID_KEY, FXA_SESSION_TOKEN_HANDLE_KEY, FXA_CONTENT_SESSION_SECRET |
Secret: the same names | generated | the accounts services' secrets | |
FXA_SIGNUPS |
fxa.signups |
open |
who can create an account: open, allowlist or closed: Who can sign up |
|
FXA_SIGNUP_ALLOWLIST |
fxa.signupAllowlist (a list, or one string) |
empty | with allowlist, the emails and @domains allowed, comma-separated |
|
FXA_MAX_ACCOUNTS |
fxa.maxAccounts |
initial:unlimited |
the most accounts that can be created: Limits | |
FXA_CLIENT_ADDRESS_DEPTH |
fxa.clientAddressDepth |
2 |
the reverse proxies in front of the accounts API, plus 1: where the rate limits find the client IP address (Client IP address) | |
FXA_ACCESS_TOKEN_LIFETIME |
fxa.accessTokenLifetime |
"60 minutes" |
the lifetime of Firefox's access tokens (Mozilla's default: "365 minutes") |
|
FXA_ACCOUNT_EVENTS |
fxa.accountEvents |
false |
true: record the security history of every account, with IP addresses: Security history |
|
FXA_PAIRING_URL |
fxa.pairing.url |
unset: Mozilla's channel server | your own pairing server for the QR code, for example wss://pairing.example.com, with pairing in COMPOSE_PROFILES (Helm: fxa.pairing.enabled) |
|
FXA_PAIRING_REPOSITORY |
fxa.pairing.repository |
unset: FXA_IMAGE (Helm empty: the accounts' repository) |
the pairing server's image repository: it follows the accounts' image, a mirror too | |
FXA_PAIRING_VERSION |
fxa.pairing.tag |
fxa-channelserver-latest |
its tag, or a pinned one such as fxa-channelserver-<release> |
|
FXA_PAIRING_IMAGE |
fxa.pairing.image |
unset: <FXA_PAIRING_REPOSITORY>:<FXA_PAIRING_VERSION> |
a full image reference that wins over both, for example Mozilla's own docker.io/mozilla/channelserver:<tag> (amd64 only), which Mozilla's accounts image (FXA_IMAGE=docker.io/mozilla/fxa-mono) needs: it has no pairing server. |
|
FXA_PAIRING_TRUSTED_PROXIES |
fxa.pairing.trustedProxies |
unset: 127.0.0.1,172.16.0.0/12,10.0.0.0/8,192.168.0.0/16 |
the proxies the pairing server trusts for the client address (not with the Quadlets: they have no pairing server) | |
FXA_LOG_LEVEL |
fxa.logLevel |
unset: INFO |
the log level of the auth server: ERROR, WARN, INFO, DEBUG or TRACE |
|
FXA_CONTENT_EXPORT_PORT |
– (the Service <release>-firefox-sync-fxa-content, port 3030) |
127.0.0.1:3030 |
where the host publishes the accounts pages | |
FXA_AUTH_EXPORT_PORT |
– (-fxa-auth, 9000) |
127.0.0.1:9000 |
the accounts API, for your reverse proxy only: a port of the host, never in FXA_OAUTH_SERVER_URL |
|
FXA_PROFILE_EXPORT_PORT |
– (-fxa-profile, 1111) |
127.0.0.1:1111 |
the profile server | |
FXA_PROFILE_STATIC_EXPORT_PORT |
– (-fxa-profile, 1112) |
127.0.0.1:1112 |
the profile server's static files (avatars) | |
FXA_PAIRING_EXPORT_PORT |
– (-fxa-pairing, 8000) |
127.0.0.1:8058 |
the pairing server |
Which host name goes to which port: Host names and ports. These are ports of the host: the setup (and --upgrade) takes the next free one where something else listens (Ports in use); inside the stack the containers keep their own ports.
Reverse proxy¶
What prepare_environment.sh writes into proxy/ from .env, the configuration of the reverse proxy, takes these too (Reverse proxy): after a change, ./prepare_environment.sh --render-proxy. The Helm chart has its Ingresses instead (Kubernetes).
.env |
Helm | Default | Meaning | Old name |
|---|---|---|---|---|
PROXY |
– | own |
which reverse proxy: own (yours, with the file of proxy/), caddy (the bundled Caddy: compose/caddy.yml in COMPOSE_FILE, or its Quadlet) or traefik (labels for your Traefik: proxy/traefik-compose.yml in COMPOSE_FILE). --upgrade puts the file of PROXY in COMPOSE_FILE, and takes out the other's |
|
PROXY_ADMIN_ALLOW |
– | 127.0.0.1,::1 |
who reaches the admin UI's public address (ADMIN_OIDC_REDIRECT_URL) through the proxy: addresses and CIDRs, comma-separated; empty: anybody. Not the containers' networks behind published ports (The admin UI) |
|
PROXY_CERTS |
– | per-host |
your own proxy's certificates in proxy/nginx.conf, Caddyfile, traefik.yml: per-host (certbot's, /etc/letsencrypt/live/<host>/; Caddy gets its own) or one, one certificate for every host name, such as a wildcard (Certificates) |
|
PROXY_CERT_FILE, PROXY_CERT_KEY_FILE |
– | empty | PROXY_CERTS=one: the certificate (with its chain) and its key, as your proxy reads them: nginx's ssl_certificate, Caddy's tls, Traefik's tls.certificates |
|
PROXY_NGINX_SSL_INCLUDE |
– | empty: the two files | PROXY_CERTS=one: an nginx file of yours with the ssl_* lines, which each server block includes instead |
|
PROXY_CERT_NAMES |
– | empty | PROXY_CERTS=one: the names the certificate is for, comma-separated (*.example.com,example.com): the setup, --upgrade and --render-proxy warn of a host name it does not cover (a wildcard covers one label only) |
|
CADDY_IMAGE |
– | caddy:latest |
PROXY=caddy: its image |
|
CADDY_HTTP_PORT, CADDY_HTTPS_PORT |
– | 80, 443 |
PROXY=caddy: the ports of this host it listens on, on the host's network (Rootless Podman and ports under 1024) |
|
CADDY_ACME_CA |
– | letsencrypt |
PROXY=caddy: where its certificates come from, letsencrypt, staging (Let's Encrypt's test CA) or internal (Caddy's own CA) |
|
CADDY_ACME_EMAIL |
– | empty: none | PROXY=caddy: the email Let's Encrypt writes to about the certificates |
|
TRAEFIK_NETWORK |
– | empty: <COMPOSE_PROJECT_NAME>-proxy |
with PROXY=traefik the network the public containers join, for Traefik alone (Traefik labels) |
|
TRAEFIK_ENTRYPOINTS |
– | websecure |
the routers' HTTPS entry points, comma-separated (also of proxy/traefik.yml) |
|
TRAEFIK_HTTP_ENTRYPOINT |
– | web |
the HTTP entry point redirected to HTTPS; empty: no redirect | |
TRAEFIK_CERTRESOLVER |
– | empty: Traefik's default certificate | the certificate resolver of the routers |
Generated passwords and secrets¶
prepare_environment.sh generates every password and secret of the choices you made (letters and digits), writes them to .env (this user's only), names them in its review, and lists them at its end with what each is for. Those you typed (the SMTP password, a client secret, a bootstrap password you gave) are not listed. On a terminal it shows the admin UI's password once; in a log it says where it is. Each can be changed later:
| Setting | What for | To change it |
|---|---|---|
ADMIN_PASSWORD |
the admin UI's sign-in password, the one you use yourself; empty when you chose single sign-on only ("Keep a password as a fallback?": no) | .env, then docker compose up -d (Quadlets: ./prepare_environment.sh --render-units, then restart the units it names). Keep it in your password manager |
SYNC_MASTER_SECRET |
signs the Sync tokens | .env, then restart. A new one signs every Firefox out of Sync until it signs in again; their data stays |
SYNC_METRICS_HASH_SECRET |
the key of the hashed account ids in the metrics | .env, then restart. The hashes start over |
ADMIN_DB_PASSWORD, SYNC_POSTGRES_APP_PASSWORD, FXA_ADMIN_DB_PASSWORD |
database users the stack sets again at every start | .env, then restart (your own server: Change a database password) |
SYNC_TOKENSERVER_DB_PASSWORD, SYNC_STORAGE_DB_PASSWORD, SYNC_POSTGRES_PASSWORD, FXA_MYSQL_PASSWORD, FXA_MYSQL_POLICY_PASSWORD, SYNC_DB_BOOTSTRAP_PASSWORD, FXA_DB_BOOTSTRAP_PASSWORD |
database users whose password the database has too | in the database first, then .env: Change a database password |
FXA_AUTH_SECRET, FXA_OAUTH_SECRET, FXA_PROFILE_SECRET, FXA_FLOW_ID_KEY, FXA_SESSION_TOKEN_HANDLE_KEY, FXA_CONTENT_SESSION_SECRET |
the self-hosted accounts services' own keys | .env, then restart; only if one leaked: the accounts' sessions and tokens signed with it stop working, and people sign in again |
FXA_OAUTH_SECRET also gives the key of the accounts' tokens for the password, email and 2-step changes (mfa.jwt.secretKey, an HMAC-SHA256 of it, config/fxa/oauth-clients.js): a new one ends those that are open, the person confirms with a code again. MFA__JWT__KEY in the environment of fxa-auth overrides it.
ADMIN_FXA_CLIENT_ID, also generated, is no secret: the id of the admin UI's sign-in client of the self-hosted accounts.
Helm only¶
Values of the chart with no .env counterpart, besides those in the tables above. Each is described in values.yaml.
| Helm | Default | Meaning |
|---|---|---|
nameOverride, fullnameOverride |
empty | the names of the chart's objects: Limits |
existingSecret |
empty: the chart generates <release>-firefox-sync |
a Secret of your own: existingSecret |
database.allowMajorUpgrade |
false |
true lets one helm upgrade move the bundled MariaDB or MySQL to another major (never PostgreSQL); set it back to false after: Database majors |
fxa.database.allowMajorUpgrade |
false |
the same for the bundled accounts database (fxa.enabled) |
fxa.enabled |
false |
the self-hosted accounts: Self-hosted accounts |
fxa.database.external.* |
your own accounts database server, with fxa.database.bundled: false: in the Accounts table |
|
fxa.database.persistence.size, .storageClass |
8Gi, the default class |
the bundled accounts database's volume, set before the first install: Volumes |
fxa.database.resources, fxa.redis.resources, fxa.resources.*, fxa.pairing.resources |
memory requests (pairing: none) | the accounts' containers: Resources and PodSecurity |
fxa.redis.image |
docker.io/library/redis:alpine |
the accounts' Redis: Database majors |
fxa.keys.existingSecret |
empty: the PVC <release>-firefox-sync-fxa-keys |
a Secret with the accounts' signing keys: The signing keys |
fxa.keys.persistence.size, .storageClass |
1Gi, the default class |
the keys' PVC; it grows with a StorageClass of allowVolumeExpansion: Volumes |
fxa.profileImages.persistence.size, .storageClass |
1Gi, the default class |
the avatars' PVC, <release>-firefox-sync-fxa-profile-images, as the keys' |
fxa.pairing.enabled |
false |
the chart's own pairing server, at fxa.pairing.url: Pairing |
fxa.ingress.enabled, .className, .annotations, .tls.enabled, .tls.secretNames.content, .auth, .profile, .pairing |
off | the accounts' Ingresses, one per host: Kubernetes |
fxa.extraCaCerts.configMap, .key |
empty, ca.crt |
a ConfigMap with a CA the accounts and the admin UI trust, for your SMTP server or your own HTTPS hosts |
fxa.volumeOwnerInit |
true |
false: no root init container, fsGroup instead: Resources and PodSecurity |
fxa.networkPolicy.enabled |
true |
NetworkPolicies for the accounts' Redis and database: NetworkPolicies |
fxa.networkPolicy.servers.enabled, .ingressController.namespaceSelector, .podSelector, .extraFrom |
off | NetworkPolicies for the accounts' public servers too, from your Ingress controller: NetworkPolicies |
admin.fxaSignIn |
false |
sign in to the admin UI with the self-hosted accounts: Sign in with the accounts |
syncstorage.replicas |
1 |
keep 1: the migrations and the max users init run in its init containers |
syncstorage.resources, syncstorage.initResources |
none | the Sync server and its init containers: Resources |
syncstorage.service.port |
8000 |
the Sync server's Service port |
ingress.enabled, .className, .host, .tls.enabled, .tls.secretName, .annotations |
off; host empty: that of syncDomain |
the Sync server's Ingress: Ingress |
imagePullSecrets |
none | pull secrets for every pod |
nodeSelector, tolerations, affinity |
none | where every pod of the chart runs |
podAnnotations |
none | annotations on every pod |
Not in .env¶
The admin UI and the backup script also read these variables, from their container's environment only. Neither compose nor the Quadlets pass them from .env, and the chart does not set them: they are for the tests.
| Variable | Default | Meaning |
|---|---|---|
HEALTH_CHECK_SECONDS |
60 |
how often the admin UI checks the components |
METRICS_FLUSH_SECONDS |
60 |
how often it writes its metrics |
ALERT_INTERVAL_SECONDS |
600 |
the alerts are collected and sent at most this often |
FXA_INIT_TIMEOUT |
120 |
seconds the admin UI waits at its start for the accounts' tables, which the migrations create |
BACKUP_LOCK_WAIT |
3600 |
seconds a backup run waits for another one to finish |
BACKUP_RETRY_PAUSE |
10 |
seconds before a dump is tried again after a table changed or was dropped while it ran (error 1412 or 1146, PostgreSQL's "relation does not exist") |