docs: add default Spanner/MySQL config guide and one-shot MySQL compose

taddes · taddes · commit 48461dfea69a · 2026-06-17T16:37:58.000-04:00
Add a short How-To page describing the out-of-the-box configuration for the standard MySQL and Spanner builds, the minimum required settings, and where the full reference lives. Add a one-shot MySQL docker compose recipe (DB + server, migrations applied automatically, sync-1.5 service + node bootstrapped) so the stack comes up ready to serve. The primary recipe builds the image from source (works from a checkout with no published tag); an alternative uses a published image, noting that images are tagged by commit SHA with no `latest` tag, so SYNCSERVER_VERSION must be pinned. Register the new page in the book summary and How-To index. Closes STOR-477
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -37,6 +37,7 @@
 [Mozilla Accounts Server - FxA](mozilla-accounts.md)
 
 - [How To Guides](how-to/index.md)
+    - [Default Configuration for Spanner & MySQL Builds](how-to/default-config.md)
     - [Run Your Own Sync-1.5 Server with Docker](how-to/how-to-run-with-docker.md)
     - [Run Your Own Sync-1.5 Server (legacy)](how-to/how-to-run-sync-server.md)
     - [Configure Sync Server for TLS (legacy)](how-to/how-to-config-tls.md)
diff --git a/docs/src/how-to/default-config.md b/docs/src/how-to/default-config.md
@@ -0,0 +1,68 @@
+# Default Configuration for Spanner & MySQL Builds
+
+This page describes the out-of-the-box configuration needed to run the two
+standard `syncstorage-rs` builds:
+
+- **MySQL build** — the default `cargo build` / `make run_mysql` target and the
+  `syncstorage-rs-mysql` Docker image. Both Syncstorage and Tokenserver run
+  against MySQL.
+- **Spanner build** — `make run_spanner` and the `syncstorage-rs-spanner`
+  Docker image. This mirrors production: Syncstorage runs against Google Cloud
+  Spanner while Tokenserver runs against MySQL.
+
+Annotated, copy-paste-ready templates live in the repo:
+
+| Build | Template |
+| --- | --- |
+| MySQL | [`config/local.example.toml`](https://github.com/mozilla-services/syncstorage-rs/blob/master/config/local.example.toml) |
+| Spanner | [`config/local.example.spanner.toml`](https://github.com/mozilla-services/syncstorage-rs/blob/master/config/local.example.spanner.toml) |
+
+Copy one to `config/local.toml` and edit the values marked `REQUIRED`:
+
+```sh
+cp config/local.example.toml config/local.toml          # MySQL
+# or
+cp config/local.example.spanner.toml config/local.toml  # Spanner
+```
+
+Every setting can also be supplied as an environment variable prefixed with
+`SYNC_` (nested keys use `__`). For example `syncstorage.database_url` becomes
+`SYNC_SYNCSTORAGE__DATABASE_URL`. Environment variables take precedence over the
+config file. The complete list of options and their defaults is in the
+[Application Configuration](../config.md) reference, and the source of truth is
+the doc-commented `Settings` structs in the `*-settings` crates.
+
+## Minimum required settings
+
+Most settings have sensible defaults. Regardless of backend you must supply:
+
+| Setting | Why |
+| --- | --- |
+| [`master_secret`](../config.md#SYNC_MASTER_SECRET) | Derives the Hawk signing/token secrets. No default. |
+| [`syncstorage.database_url`](../config.md#SYNC_SYNCSTORAGE__DATABASE_URL) | No usable default; the server fails fast at startup if unset. |
+| [`tokenserver.database_url`](../config.md#SYNC_TOKENSERVER__DATABASE_URL) | Required when `tokenserver.enabled = true` (fails fast if unset). |
+
+Backend-specific notes:
+
+- **MySQL:** set `tokenserver.node_type = "mysql"`. Syncstorage MySQL schema
+  migrations run automatically at startup; set
+  `tokenserver.run_migrations = true` to apply the Tokenserver schema too.
+- **Spanner:** `syncstorage.database_url` must use the
+  `spanner://projects/.../instances/.../databases/...` form — the `spanner://`
+  scheme is what selects the Spanner backend. Leave `tokenserver.node_type` at
+  its default (`"spanner"`). To run against the local emulator instead of GCP,
+  set `syncstorage.spanner_emulator_host` (e.g. `localhost:9010`); for real
+  Spanner, point `GOOGLE_APPLICATION_CREDENTIALS` at a service-account key.
+
+## Run it out of the box with Docker
+
+For a zero-to-running MySQL stack (database + server, schema applied
+automatically, ready to serve), see the
+[one-shot MySQL `docker compose`](how-to-run-with-docker.md#docker-compose-one-shot-with-mysql)
+recipe. It brings up MySQL and the server, runs migrations, and bootstraps the
+storage node so that `curl http://localhost:8000/__heartbeat__` succeeds with no
+further setup.
+
+A Spanner stack cannot be fully zero-config: real Spanner requires GCP
+credentials, and the local emulator requires extra wiring (see
+`docker/docker-compose.spanner.yaml` and `make run_spanner`).
diff --git a/docs/src/how-to/how-to-run-with-docker.md b/docs/src/how-to/how-to-run-with-docker.md
@@ -10,7 +10,7 @@ Images are available for both
 and
 [PostgreSQL](https://github.com/mozilla-services/syncstorage-rs/pkgs/container/syncstorage-rs%2Fsyncstorage-rs-postgres)
 as the database.  Differences in configuration or deployment steps will be
-noted. 
+noted.
 
 Tagged release builds are available on ghcr.io. To pin to a specific version,
 set `SYNCSERVER_VERSION` to the desired release tag (e.g., `SYNCSERVER_VERSION=v1.45.0`)
@@ -142,6 +142,145 @@ Next, start the service with `docker compose`:
 docker compose -f docker-compose.one-shot.yaml up -d
 ```
 
+## Docker Compose, One-Shot with MySQL
+
+This recipe brings up everything needed for a working MySQL-backed server in a
+single command: a MySQL database for Syncstorage and one for Tokenserver, plus
+the server itself. Syncstorage applies its schema migrations automatically at
+startup, `SYNC_TOKENSERVER__RUN_MIGRATIONS` applies the Tokenserver schema, and
+`SYNC_TOKENSERVER__INIT_NODE_URL` bootstraps the `sync-1.5` service and storage
+node records — so the stack is ready to serve with no manual database setup.
+
+### Option A: build from source (works from a checkout)
+
+Run this from a clone of the repository; the build `context` is the repo root,
+so the MySQL build of the server is compiled locally and the recipe does not
+depend on any published image. Save the yaml below into a file, e.g.
+`docker-compose.one-shot.yaml`.
+
+```yaml
+services:
+  syncserver:
+    build:
+      context: .
+      args:
+        SYNCSTORAGE_DATABASE_BACKEND: mysql
+        TOKENSERVER_DATABASE_BACKEND: mysql
+    container_name: syncserver
+    ports:
+      - "8000:8000"
+    environment:
+      SYNC_HOST: "0.0.0.0"
+      SYNC_PORT: "8000"
+      SYNC_MASTER_SECRET: "${SYNC_MASTER_SECRET:-changeme_secret_key}"
+      SYNC_SYNCSTORAGE__DATABASE_URL: "mysql://sync:sync@sync-db:3306/syncstorage"
+      SYNC_TOKENSERVER__DATABASE_URL: "mysql://sync:sync@tokenserver-db:3306/tokenserver"
+      SYNC_TOKENSERVER__ENABLED: "true"
+      SYNC_TOKENSERVER__NODE_TYPE: "mysql"
+      SYNC_TOKENSERVER__RUN_MIGRATIONS: "true"
+      SYNC_TOKENSERVER__FXA_EMAIL_DOMAIN: "api.accounts.firefox.com"
+      SYNC_TOKENSERVER__FXA_OAUTH_SERVER_URL: "https://oauth.accounts.firefox.com"
+      SYNC_HUMAN_LOGS: "${SYNC_HUMAN_LOGS:-false}"
+      RUST_LOG: "${RUST_LOG:-info}"
+      SYNC_TOKENSERVER__INIT_NODE_URL: "${SYNC_TOKENSERVER__INIT_NODE_URL:-http://localhost:${SYNC_PORT:-8000}}"
+    depends_on:
+      sync-db:
+        condition: service_healthy
+      tokenserver-db:
+        condition: service_healthy
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/__heartbeat__"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
+  sync-db:
+    image: docker.io/library/mysql:8.0
+    container_name: syncserver-sync-db
+    command: --explicit_defaults_for_timestamp
+    environment:
+      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
+      MYSQL_DATABASE: syncstorage
+      MYSQL_USER: sync
+      MYSQL_PASSWORD: sync
+    volumes:
+      - sync_db_data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin -h 127.0.0.1 -usync -psync ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    restart: unless-stopped
+
+  tokenserver-db:
+    image: docker.io/library/mysql:8.0
+    container_name: syncserver-tokenserver-db
+    command: --explicit_defaults_for_timestamp
+    environment:
+      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
+      MYSQL_DATABASE: tokenserver
+      MYSQL_USER: sync
+      MYSQL_PASSWORD: sync
+    volumes:
+      - tokenserver_db_data:/var/lib/mysql
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin -h 127.0.0.1 -usync -psync ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+    restart: unless-stopped
+
+volumes:
+  sync_db_data:
+    driver: local
+  tokenserver_db_data:
+    driver: local
+```
+
+Next, build and start the service with `docker compose`:
+
+```sh
+docker compose -f docker-compose.one-shot.yaml up -d --build
+```
+
+Once the `syncserver` container reports healthy, confirm it is serving:
+
+```sh
+curl http://localhost:8000/__heartbeat__
+```
+
+### Option B: use a published image
+
+Mozilla also publishes prebuilt images on ghcr.io. Note that these are
+currently tagged by commit SHA — there is **no `latest` or semver tag** — so
+you must pin `SYNCSERVER_VERSION` to a tag listed on the
+[`syncstorage-rs-mysql` packages page](https://github.com/mozilla-services/syncstorage-rs/pkgs/container/syncstorage-rs%2Fsyncstorage-rs-mysql).
+To use a published image, replace the `syncserver` service's `build:` block with
+an `image:` reference; the `sync-db`, `tokenserver-db`, and `volumes` sections
+are unchanged:
+
+```yaml
+services:
+  syncserver:
+    image: ghcr.io/mozilla-services/syncstorage-rs/syncstorage-rs-mysql:${SYNCSERVER_VERSION:?set SYNCSERVER_VERSION to a published tag}
+    platform: linux/amd64
+    container_name: syncserver
+    # ...the remaining syncserver settings are identical to Option A
+```
+
+Then start it with the tag pinned (published images are `linux/amd64`):
+
+```sh
+SYNCSERVER_VERSION=<published-tag> docker compose -f docker-compose.one-shot.yaml up -d
+```
+
+> Set `SYNC_MASTER_SECRET` to your own value for anything beyond local
+> experimentation; the default above is a placeholder.
+
 ## Configuring Firefox (Desktop)
 
 Firefox itself needs to be configured to use the self-hosted Sync server.
diff --git a/docs/src/how-to/index.md b/docs/src/how-to/index.md
@@ -2,6 +2,7 @@
 
 Collection of How To guides for various Sync-related operations.
 
+- [Default Configuration for Spanner & MySQL Builds](default-config.md)
 - [Run Your Own Sync-1.5 Server with Docker](how-to-run-with-docker.md)
 - [Run Your Own Sync-1.5 Server (legacy)](how-to-run-sync-server.md)
 - [Configure Sync Server for TLS (legacy)](how-to-config-tls.md)
