From 06074c9cef7081be422d84102ec9eec4b12a4338 Mon Sep 17 00:00:00 2001 From: Preston Date: Tue, 8 Sep 2026 16:32:01 -0500 Subject: [PATCH 1/4] Fix the upgrade guide migration tag and document the tag rule. --- .../03-data-and-the-database/02-database/13-migrations.md | 2 +- .../cli/commands/create-migration/_create-migration.md | 2 +- docs/11-upgrading/01-upgrade-to-four.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/06-concepts/03-data-and-the-database/02-database/13-migrations.md b/docs/06-concepts/03-data-and-the-database/02-database/13-migrations.md index 4bd9be54..30171b62 100644 --- a/docs/06-concepts/03-data-and-the-database/02-database/13-migrations.md +++ b/docs/06-concepts/03-data-and-the-database/02-database/13-migrations.md @@ -57,7 +57,7 @@ $ serverpod create-migration --empty ### Tag migration -Tags can be useful to identify migrations that introduced specific changes to the project. Tags are appended to the migration name and can be added with the `--tag` option. +Tags can be useful to identify migrations that introduced specific changes to the project. Tags are appended to the migration name and can be added with the `--tag` option. A tag can contain only lowercase letters, numbers, and dashes. ```bash $ serverpod create-migration --tag "v1-0-0" diff --git a/docs/06-concepts/cli/commands/create-migration/_create-migration.md b/docs/06-concepts/cli/commands/create-migration/_create-migration.md index b91ac9ab..ea5fdfa4 100644 --- a/docs/06-concepts/cli/commands/create-migration/_create-migration.md +++ b/docs/06-concepts/cli/commands/create-migration/_create-migration.md @@ -2,4 +2,4 @@ The `serverpod create-migration` command compares your current models and database definition to the last migration and writes a new migration for the difference. Run it after changing your model files. -Use `--force` to proceed when a change may drop data, `--tag` to label the revision, or `--empty` to create a migration even when nothing has changed. For the full workflow, see [Migrations](../../data-and-the-database/database/migrations). +Use `--force` to proceed when a change may drop data, `--tag` to label the revision (lowercase letters, numbers, and dashes only), or `--empty` to create a migration even when nothing has changed. For the full workflow, see [Migrations](../../data-and-the-database/database/migrations). diff --git a/docs/11-upgrading/01-upgrade-to-four.md b/docs/11-upgrading/01-upgrade-to-four.md index 5e93e7cf..536b31af 100644 --- a/docs/11-upgrading/01-upgrade-to-four.md +++ b/docs/11-upgrading/01-upgrade-to-four.md @@ -128,7 +128,7 @@ The `hotReload`, `getOpenSessionLog`, and `shutdown` Insights methods are remove Version 4.0 adds a few new internal Serverpod tables and updates some indexes to greatly improve logs performance on Insights. Create a migration that captures these schema deltas so your database can be brought up to date: ```bash -$ serverpod create-migration --tag "upgrade-4.0" +$ serverpod create-migration --tag "upgrade-4-0" ``` This writes a new migration to `_server/migrations/`. It will be applied to your database in the next step. From 0c6b76e2ed9bf76ecaa0b4553fec7e6299750f93 Mon Sep 17 00:00:00 2001 From: Preston Date: Tue, 8 Sep 2026 16:35:44 -0500 Subject: [PATCH 2/4] Make the cookie-auth example enable cookie auth. --- .../04-authentication/10-web-authentication.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/06-concepts/04-authentication/10-web-authentication.md b/docs/06-concepts/04-authentication/10-web-authentication.md index 142837fb..27c70957 100644 --- a/docs/06-concepts/04-authentication/10-web-authentication.md +++ b/docs/06-concepts/04-authentication/10-web-authentication.md @@ -20,14 +20,16 @@ Enable cookie auth by adding an `authCookie` section to your server configuratio ```yaml authCookie: - # secure: false # Uncomment only for http://localhost development. + sameSite: lax allowedOrigins: - https://app.example.com ``` +In `config/development.yaml`, set `secure: false` instead so the cookie is sent over `http://localhost`. The section must contain at least one field: an `authCookie:` key with no children is read as unset, and cookie auth stays off. + `allowedOrigins` is required when `authCookie` is set: it backs the CSRF origin checks and credentialed CORS, which cannot use a wildcard origin. List every browser origin that calls your server. With cookie auth enabled, browsers on origins that are not in the list lose cross-origin access, including to public endpoints. -All `authCookie` fields are optional: +Every field has a default, so any single field enables the section: | Field | Default | Purpose | | ------------- | ------------------------ | -------------------------------------------------------------- | @@ -62,7 +64,7 @@ Everything else is unchanged: sign-in flows, the `client.auth` session manager, 3. Confirm no token appears in **Local Storage** for your app's origin. 4. Reload the page. The user is still signed in. -If sign-in fails, check that every browser origin is listed in `allowedOrigins`, and on `http://localhost` that `authCookie.secure` is `false`. +If sign-in fails, check that every browser origin is listed in `allowedOrigins`, and on `http://localhost` that `authCookie.secure` is `false`. If the app throws `StateError: cookieAuth is enabled but the server returned the auth token in the response body`, the server's `authCookie` section is missing or has no fields; add at least one. ## How it works From fe5ff8726554fae74830383355496e4b10c86ab6 Mon Sep 17 00:00:00 2001 From: Preston Date: Tue, 8 Sep 2026 16:38:11 -0500 Subject: [PATCH 3/4] Add allowedOrigins and authCookie keys to the configuration reference. --- docs/06-concepts/lookups/configuration-reference.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/06-concepts/lookups/configuration-reference.md b/docs/06-concepts/lookups/configuration-reference.md index 8538a40f..5fc343f7 100644 --- a/docs/06-concepts/lookups/configuration-reference.md +++ b/docs/06-concepts/lookups/configuration-reference.md @@ -55,10 +55,17 @@ Ports, hosts, and connection settings for the API, Insights, and web servers, th | SERVERPOD_REDIS_HOST | redis.host | - | The host address of the Redis server | | SERVERPOD_REDIS_PORT | redis.port | - | The port number for the Redis server | | SERVERPOD_REDIS_USER | redis.user | - | The user name for Redis authentication | -| SERVERPOD_REDIS_ENABLED | redis.enabled | false | Indicates if Redis is enabled | +| SERVERPOD_REDIS_ENABLED | redis.enabled | true | Indicates if Redis is enabled. Defaults to `true` when a `redis` section is present; Redis is off when the section is absent or `enabled` is `false`. | | SERVERPOD_REDIS_REQUIRE_SSL | redis.requireSsl | false | Indicates if SSL is required for the Redis connection | | SERVERPOD_MAX_REQUEST_SIZE | maxRequestSize | 524288 | The maximum size of API requests in bytes. Also caps file uploads that post to the API server. | | SERVERPOD_VALIDATE_HEADERS | validateHeaders | true | Validate HTTP headers using the typed API. Set to `false` to accept headers without the required formatting, for example an unwrapped token in the Authorization header. | +| SERVERPOD_ALLOWED_ORIGINS | allowedOrigins | - | Browser origins allowed to make credentialed cross-origin calls, as `scheme://host[:port]`. A YAML list, or comma-separated in the environment variable. Required when `authCookie` is set. See [Web authentication](../authentication/web-authentication).| +| SERVERPOD_AUTH_COOKIE_NAME | authCookie.name | - | Name of the auth cookie. Defaults to `serverpod_auth`. Setting any `authCookie` field enables cookie auth for web clients; an empty `authCookie` section is read as unset. | +| SERVERPOD_AUTH_COOKIE_REFRESH_NAME | authCookie.refreshName | - | Name of the JWT refresh cookie. Defaults to `_refresh`. | +| SERVERPOD_AUTH_COOKIE_DOMAIN | authCookie.domain | - | Cookie `Domain` attribute. Defaults to host-only; set to share the cookie across subdomains. | +| SERVERPOD_AUTH_COOKIE_PATH | authCookie.path | / | Cookie `Path` attribute. | +| SERVERPOD_AUTH_COOKIE_SECURE | authCookie.secure | true | Whether the cookie is only sent over https. Set to `false` only for `http://localhost` development. | +| SERVERPOD_AUTH_COOKIE_SAME_SITE | authCookie.sameSite | lax | Cookie `SameSite` attribute. Valid options are `lax`, `strict`, and `none` (`none` requires `secure`). | | SERVERPOD_SESSION_PERSISTENT_LOG_ENABLED | sessionLogs.persistentEnabled | - | Enables or disables logging session data to the database. Defaults to `true` if a database is configured, otherwise `false`. | | SERVERPOD_SESSION_LOG_CLEANUP_INTERVAL | sessionLogs.cleanupInterval | 24h | How often to run the log cleanup job. Duration string (e.g. `24h`, `2d`). Set to null to disable automated purging. | | SERVERPOD_SESSION_LOG_RETENTION_PERIOD | sessionLogs.retentionPeriod | 90d | How long to keep session log entries. Duration string (e.g. `30d`, `60d`). Set to null to disable time-based cleanup. | From 8fb946d934f7fdcc0cf18667319def1c6b53f71f Mon Sep 17 00:00:00 2001 From: Preston Date: Thu, 10 Sep 2026 10:02:54 -0500 Subject: [PATCH 4/4] Apply review feedback on the redis default and cookie-auth wording. --- docs/06-concepts/04-authentication/10-web-authentication.md | 4 ++-- docs/06-concepts/07-operations/06-scalability.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/06-concepts/04-authentication/10-web-authentication.md b/docs/06-concepts/04-authentication/10-web-authentication.md index 27c70957..f2a06caf 100644 --- a/docs/06-concepts/04-authentication/10-web-authentication.md +++ b/docs/06-concepts/04-authentication/10-web-authentication.md @@ -25,11 +25,11 @@ allowedOrigins: - https://app.example.com ``` -In `config/development.yaml`, set `secure: false` instead so the cookie is sent over `http://localhost`. The section must contain at least one field: an `authCookie:` key with no children is read as unset, and cookie auth stays off. +For local development, use `secure: false` in `config/development.yaml` so the cookie is sent over `http://localhost`. The section must contain at least one field: an `authCookie:` key with no children is read as unset, and cookie auth stays off. `allowedOrigins` is required when `authCookie` is set: it backs the CSRF origin checks and credentialed CORS, which cannot use a wildcard origin. List every browser origin that calls your server. With cookie auth enabled, browsers on origins that are not in the list lose cross-origin access, including to public endpoints. -Every field has a default, so any single field enables the section: +Each field and its default: | Field | Default | Purpose | | ------------- | ------------------------ | -------------------------------------------------------------- | diff --git a/docs/06-concepts/07-operations/06-scalability.md b/docs/06-concepts/07-operations/06-scalability.md index 633c1aae..8412810b 100644 --- a/docs/06-concepts/07-operations/06-scalability.md +++ b/docs/06-concepts/07-operations/06-scalability.md @@ -105,7 +105,7 @@ Keep `websocketPingInterval` (default 30 seconds) in mind under high connection | --- | --- | --- | | `role` / `SERVERPOD_SERVER_ROLE` | `monolith` | Split request nodes from maintenance work. | | `database.maxConnectionCount` | `10` | Pool size times node count must fit Postgres. | -| `redis.enabled` | `false` | Required for shared cache and global events. | +| `redis.enabled` | `true` when a `redis` section is present | Required for shared cache and global events. | | `maxRequestSize` | `524288` | Large uploads increase memory pressure. | | `websocketPingInterval` | `30` (seconds) | Keepalive cost under many open streams. | | `futureCall.concurrencyLimit` | `1` | Caps background CPU and database load. |