sandcms 0.6.3 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/README.md +15 -11
  2. package/dist/admin/Account.svelte +2 -0
  3. package/dist/admin/Admin.svelte +21 -6
  4. package/dist/admin/AssetAttachment.svelte +9 -6
  5. package/dist/admin/AssetAttachment.svelte.d.ts +3 -1
  6. package/dist/admin/BlueprintFields.svelte +0 -3
  7. package/dist/admin/BlueprintFields.svelte.d.ts +0 -1
  8. package/dist/admin/Editor.svelte +5 -10
  9. package/dist/admin/Fields.svelte +2 -8
  10. package/dist/admin/Fields.svelte.d.ts +0 -1
  11. package/dist/admin/Gallery.svelte +221 -80
  12. package/dist/admin/Gallery.svelte.d.ts +0 -1
  13. package/dist/admin/Inbox.svelte +3 -2
  14. package/dist/admin/LinkField.svelte +0 -3
  15. package/dist/admin/LinkField.svelte.d.ts +0 -1
  16. package/dist/admin/MediaLibrary.svelte +10 -7
  17. package/dist/admin/MediaPicker.svelte +43 -35
  18. package/dist/admin/MediaPicker.svelte.d.ts +0 -1
  19. package/dist/admin/Navigation.svelte +13 -2
  20. package/dist/admin/Pages.svelte +195 -0
  21. package/dist/admin/Pages.svelte.d.ts +7 -0
  22. package/dist/admin/Shell.svelte +27 -5
  23. package/dist/admin/SortableList.svelte +82 -61
  24. package/dist/admin/SortableList.svelte.d.ts +3 -1
  25. package/dist/admin/ThemePicker.svelte +72 -0
  26. package/dist/admin/ThemePicker.svelte.d.ts +18 -0
  27. package/dist/admin/UploadButton.svelte +2 -1
  28. package/dist/admin/UploadProgress.svelte +24 -0
  29. package/dist/admin/UploadProgress.svelte.d.ts +7 -0
  30. package/dist/admin/Users.svelte +8 -3
  31. package/dist/admin/client.d.ts +3 -670
  32. package/dist/admin/client.js +2 -1
  33. package/dist/admin/components/ui/alert/alert.svelte.d.ts +3 -13
  34. package/dist/admin/components/ui/attachment/attachment-media.svelte.d.ts +3 -13
  35. package/dist/admin/components/ui/attachment/attachment.svelte.d.ts +6 -26
  36. package/dist/admin/components/ui/badge/badge.svelte.d.ts +7 -25
  37. package/dist/admin/components/ui/button/button.svelte.d.ts +15 -53
  38. package/dist/admin/components/ui/toggle/toggle.svelte.d.ts +6 -26
  39. package/dist/admin/generated/admin.css +823 -115
  40. package/dist/admin/navigation.d.ts +9 -0
  41. package/dist/admin/navigation.js +20 -1
  42. package/dist/admin/theme-context.d.ts +7 -0
  43. package/dist/admin/theme-context.js +3 -0
  44. package/dist/admin/theme.d.ts +7 -0
  45. package/dist/admin/theme.js +14 -0
  46. package/dist/admin/types.d.ts +3 -1
  47. package/dist/admin/uploads.d.ts +8 -1
  48. package/dist/admin/uploads.js +94 -16
  49. package/dist/blueprints/files.js +1 -0
  50. package/dist/blueprints/labels.d.ts +6 -0
  51. package/dist/blueprints/labels.js +14 -0
  52. package/dist/blueprints/load.js +16 -2
  53. package/dist/blueprints/types.d.ts +4 -1
  54. package/dist/cli/admin.d.ts +39 -0
  55. package/dist/cli/admin.js +95 -0
  56. package/dist/cli/backup.js +4 -4
  57. package/dist/cli/doctor.d.ts +10 -1
  58. package/dist/cli/doctor.js +98 -33
  59. package/dist/cli/email-test.d.ts +3 -0
  60. package/dist/cli/email-test.js +20 -0
  61. package/dist/cli/files.d.ts +2 -6
  62. package/dist/cli/files.js +12 -2
  63. package/dist/cli/index.js +401 -95
  64. package/dist/cli/rebaseline.d.ts +10 -0
  65. package/dist/cli/rebaseline.js +117 -0
  66. package/dist/cli/scaffold.js +8 -8
  67. package/dist/cli/setup.js +16 -26
  68. package/dist/cli/upgrade.js +34 -7
  69. package/dist/env.d.ts +26 -2
  70. package/dist/env.js +48 -6
  71. package/dist/notification-fields.js +2 -1
  72. package/dist/server/admin-load.d.ts +85 -5
  73. package/dist/server/admin-load.js +26 -1
  74. package/dist/server/api-access.d.ts +4 -0
  75. package/dist/server/api-access.js +15 -2
  76. package/dist/server/api-keys.d.ts +96 -0
  77. package/dist/server/api-keys.js +115 -0
  78. package/dist/server/api-pagination.d.ts +3 -0
  79. package/dist/server/api.js +21 -63
  80. package/dist/server/auth.d.ts +10 -9
  81. package/dist/server/cms.d.ts +63 -21
  82. package/dist/server/cms.js +64 -7
  83. package/dist/server/db/auto-migrate.d.ts +0 -4
  84. package/dist/server/db/auto-migrate.js +12 -3
  85. package/dist/server/db/legacy.d.ts +13 -0
  86. package/dist/server/db/legacy.js +60 -0
  87. package/dist/server/db/migration-data.js +2 -34
  88. package/dist/server/db/migrations/{0000_foundation.sql → 0000_baseline.sql} +120 -4
  89. package/dist/server/db/migrations/meta/0000_snapshot.json +578 -3
  90. package/dist/server/db/migrations/meta/_journal.json +2 -58
  91. package/dist/server/db/schema.d.ts +119 -2
  92. package/dist/server/db/schema.js +23 -9
  93. package/dist/server/db/store.d.ts +25 -2
  94. package/dist/server/db/store.js +90 -26
  95. package/dist/server/forms.js +2 -1
  96. package/dist/server/hooks.js +155 -81
  97. package/dist/server/media/contracts.d.ts +115 -0
  98. package/dist/server/media/contracts.js +12 -0
  99. package/dist/server/media/deletions.d.ts +2 -1
  100. package/dist/server/media/deletions.js +3 -3
  101. package/dist/server/media/delivery.js +7 -11
  102. package/dist/server/media/processor-child.d.ts +2 -0
  103. package/dist/server/media/processor-child.js +236 -0
  104. package/dist/server/media/processor.d.ts +51 -0
  105. package/dist/server/media/processor.js +135 -0
  106. package/dist/server/media/render-math.d.ts +24 -0
  107. package/dist/server/media/render-math.js +50 -0
  108. package/dist/server/media/runner.d.ts +30 -1
  109. package/dist/server/media/runner.js +418 -165
  110. package/dist/server/media/service.d.ts +53 -11
  111. package/dist/server/media/service.js +307 -98
  112. package/dist/server/media/storage.d.ts +5 -0
  113. package/dist/server/media/storage.js +279 -0
  114. package/dist/server/media/upload-ticket.d.ts +12 -0
  115. package/dist/server/media/upload-ticket.js +35 -0
  116. package/dist/server/media/verify.d.ts +64 -0
  117. package/dist/server/media/verify.js +201 -0
  118. package/dist/server/platform/http.d.ts +27 -0
  119. package/dist/server/platform/http.js +77 -0
  120. package/dist/server/platform/index.d.ts +52 -0
  121. package/dist/server/platform/index.js +98 -0
  122. package/dist/server/platform/snapshots.d.ts +18 -0
  123. package/dist/server/platform/snapshots.js +110 -0
  124. package/dist/server/platform/volume.d.ts +20 -0
  125. package/dist/server/platform/volume.js +60 -0
  126. package/docs/acceptance.md +7 -5
  127. package/docs/api.md +56 -4
  128. package/docs/cloudflare.md +26 -152
  129. package/docs/content.md +20 -5
  130. package/docs/deployment.md +222 -57
  131. package/docs/email.md +6 -0
  132. package/docs/forms.md +2 -2
  133. package/docs/media.md +94 -21
  134. package/docs/package.md +21 -18
  135. package/docs/plans/0.7-self-hosted.md +264 -0
  136. package/docs/releases.md +37 -1
  137. package/docs/upgrades.md +72 -9
  138. package/package.json +37 -44
  139. package/templates/Dockerfile +32 -0
  140. package/templates/integration.ts +26 -5
  141. package/templates/openship.json +9 -0
  142. package/templates/railpack.json +1 -1
  143. package/templates/sandcms/blueprints/files/image.yaml +1 -1
  144. package/templates/sandcms/config.yaml +1 -1
  145. package/dist/cli/cloudflare.d.ts +0 -8
  146. package/dist/cli/cloudflare.js +0 -135
  147. package/dist/server/db/migrations/0001_independent_password_resets.sql +0 -3
  148. package/dist/server/db/migrations/0002_email_failure_reason.sql +0 -1
  149. package/dist/server/db/migrations/0003_direct_r2_uploads.sql +0 -10
  150. package/dist/server/db/migrations/0004_agent_api_keys.sql +0 -38
  151. package/dist/server/db/migrations/0005_api_retention_and_pagination.sql +0 -3
  152. package/dist/server/db/migrations/0006_durable_media_deletion.sql +0 -7
  153. package/dist/server/db/migrations/0007_content_and_job_indexes.sql +0 -2
  154. package/dist/server/db/migrations/0008_search_text_cache.sql +0 -45
  155. package/dist/server/db/migrations/meta/0001_snapshot.json +0 -1197
  156. package/dist/server/db/migrations/meta/0002_snapshot.json +0 -1204
  157. package/dist/server/db/migrations/meta/0003_snapshot.json +0 -1281
  158. package/dist/server/db/migrations/meta/0004_snapshot.json +0 -1546
  159. package/dist/server/db/migrations/meta/0005_snapshot.json +0 -1572
  160. package/dist/server/db/migrations/meta/0006_snapshot.json +0 -1627
  161. package/dist/server/db/migrations/meta/0007_snapshot.json +0 -1643
  162. package/dist/server/db/migrations/meta/0008_snapshot.json +0 -1711
  163. package/dist/worker/index.d.ts +0 -10
  164. package/dist/worker/index.js +0 -460
  165. package/dist/worker/local.d.ts +0 -5
  166. package/dist/worker/local.js +0 -57
  167. package/dist/worker/source.d.ts +0 -2
  168. package/dist/worker/source.js +0 -31
  169. package/dist/worker/uploads.d.ts +0 -22
  170. package/dist/worker/uploads.js +0 -48
  171. package/templates/sandcms/worker/index.ts +0 -1
  172. package/templates/sandcms/worker/local.ts +0 -1
  173. package/templates/sandcms/worker/wrangler.jsonc +0 -6
  174. /package/dist/{worker → server/media}/svg.d.ts +0 -0
  175. /package/dist/{worker → server/media}/svg.js +0 -0
@@ -1,34 +1,70 @@
1
1
  # Deployment and operations
2
2
 
3
- Run one long-lived Bun website container with a persistent writable volume. The public website, admin, auth, SQLite, and job runner stay in that process. The project media Worker/R2 bucket are deployed separately; follow [Cloudflare setup and proxy caching](cloudflare.md) for those resources and the website CDN.
3
+ A SandCMS site is one long-lived Bun container with one persistent volume. The public website, admin, auth, SQLite, the job runner, the image processor and hourly database snapshots all run in that container, and everything they store lives under `/data`:
4
4
 
5
- The repository pins Bun 1.4.0, SvelteKit 3.0.0, Svelte 5.57.1, and official `@sveltejs/adapter-bun` 1.0.0. The production adapter output is tested under Bun. Build tooling also uses pinned Node 26.8.1. [Railpack detects Bun from packageManager or its lockfile](https://railpack.com/languages/bun/); `railpack.json` makes the build/start commands explicit.
5
+ ```text
6
+ /data
7
+ sandcms.sqlite (+ -wal, -shm, .guard.sqlite) site-id
8
+ media/originals/{id}
9
+ media/variants/{id}/{version}/{preset}-{size}.{format}
10
+ media/tmp/…
11
+ backups/latest.sqlite backups/previous.sqlite
12
+ ```
6
13
 
7
- ## Server build configuration
14
+ No external service is needed. Any Docker host that meets the requirements below works. [OpenShip](https://openship.io), [Dokploy](https://dokploy.com) and [Coolify](https://coolify.io) are covered in [platform settings](#platform-settings).
8
15
 
9
- The starter includes this server configuration in `vite.config.ts`. For existing sites, merge it into the developer-owned configuration, preserving other plugins and SSR options:
16
+ The repository pins Bun 1.4.4, SvelteKit 3.2.0, Svelte 5.57.3, and official `@sveltejs/adapter-bun` 1.0.1. The production adapter output is tested under Bun. Build tooling runs on Bun too; no Node install is needed.
10
17
 
11
- ```ts
12
- ssr: {
13
- external: ['bun:sqlite'],
14
- noExternal: ['@better-auth/core']
15
- }
16
- ```
18
+ ## What the host must provide
17
19
 
18
- Vite bundles `@better-auth/core` using its server export conditions to retain native async request storage. Keep it out of `ssr.external`, which takes precedence over `noExternal`. The official Bun adapter uses Vite's server output without a second bundle pass unless executable compilation is enabled. See [Vite SSR options](https://vite.dev/config/ssr-options) and the [Bun adapter](https://svelte.dev/docs/kit/adapter-bun).
20
+ | Requirement | Detail |
21
+ | ------------- | ------------------------------------------------------------------------------------------------------------------- |
22
+ | Container | Built from the site's `Dockerfile` (or Railpack), one replica |
23
+ | Volume | One persistent volume mounted at `/data`, on a local filesystem, **used by this site only** |
24
+ | Deploys | Overlap: start the new container, switch traffic once it is healthy, then stop the old one. See [deploys](#deploys) |
25
+ | Reverse proxy | TLS, routes the site's hostnames, passes `Host` unchanged, overwrites the client-IP header it sets |
26
+ | Health check | Gates the traffic switch: the image's `HEALTHCHECK`, or `GET /_sandcms/health` failing on any 5xx |
27
+ | Memory | A container memory limit that covers one image decode at `media.maxPixels` (see [memory](#memory-and-image-limits)) |
28
+ | Backups | A scheduled copy of the whole volume to off-server storage |
19
29
 
20
- Rebuild and restart the website after this configuration change. It requires no database reset or Worker update. Setup and upgrade preserve existing Vite files and report the required change.
30
+ The proxy needs no raised timeouts or body limits: uploads arrive in 8 MB chunks, and every other request is under 1 MB.
21
31
 
22
- ## Host configuration
32
+ Do not put the volume on an object-store mount or an unproven network filesystem; SQLite needs local file locking.
23
33
 
24
- - Build: `bun run build`; start: `bun build/index.js`.
25
- - Mount a local persistent volume at `/data`, and set `SANDCMS_DATABASE=/data/sandcms.sqlite`.
26
- - Set `BODY_SIZE_LIMIT=1M` for the Bun adapter’s normal JSON requests. Media bytes upload directly to private R2 using presigned URLs; configure [Worker signing credentials and bucket CORS](cloudflare.md#direct-upload-configuration).
27
- - Set `SANDCMS_ORIGIN=https://your-site.example` and configure `paths.origin` in the SvelteKit Vite plugin to the same public origin at build time. The official adapter does not read `ORIGIN`.
28
- - Supply a stable random `SANDCMS_SECRET` with at least 32 characters and the project's `SANDCMS_WORKER_TOKEN`.
29
- - Set `SANDCMS_WORKER_URL` only if overriding the tracked media URL for this environment.
30
- - Set `PORT` to the host's assigned port. Route both the public website and `/admin` to this container.
31
- - Keep one application instance per database volume; the SQLite volume must support local filesystem locking. Do not use an object-store mount or an unproven network filesystem.
34
+ ## Environment
35
+
36
+ ```dotenv
37
+ SANDCMS_ORIGIN=https://www.example.com
38
+ SANDCMS_SECRET=<32+ random characters>
39
+ SANDCMS_DATABASE=/data/sandcms.sqlite
40
+ SANDCMS_AUTO_MIGRATE=true
41
+ BODY_SIZE_LIMIT=10M
42
+ SANDCMS_TRUSTED_PROXY_HEADER=x-real-ip # the header your proxy sets
43
+ ADDRESS_HEADER=x-real-ip
44
+ # SANDCMS_INDEXING=false # preview sites only
45
+ # SANDCMS_BOOTSTRAP_EMAIL=you@example.com # first start only
46
+ ```
47
+
48
+ | Variable | Purpose |
49
+ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
50
+ | `SANDCMS_ORIGIN` | Canonical public origin. Requests for other hostnames redirect here. Changing it needs a restart, not a rebuild. |
51
+ | `SANDCMS_SECRET` | Stable random secret, at least 32 characters. Signs sessions and upload tickets. |
52
+ | `SANDCMS_DATABASE` | SQLite path on the volume. Its directory is the data directory. |
53
+ | `SANDCMS_MEDIA_DIR` | Optional. Defaults to `<database directory>/media`. Keep it on the same volume. |
54
+ | `SANDCMS_AUTO_MIGRATE` | `true` applies pending migrations on start, after a verified snapshot. See [automatic migration](#automatic-migration-on-start). |
55
+ | `BODY_SIZE_LIMIT` | The Bun adapter's limit for all routes. Must be at least the 8 MB chunk size; `10M` is recommended and set by the starter image. |
56
+ | `SANDCMS_REQUEST_LIMIT` | Optional. Largest body in bytes for every route except upload chunks (default 1 MB). Larger bodies get 413 before being read. |
57
+ | `SANDCMS_TRUSTED_PROXY_HEADER` | Client-IP header used for CMS rate limits. See [client IP](#client-ip-behind-a-reverse-proxy). |
58
+ | `ADDRESS_HEADER` | The Bun adapter's client-IP header for `event.getClientAddress()`. Set it to the same header. |
59
+ | `SANDCMS_INDEXING` | `false` sends `X-Robots-Tag: noindex` and a disallow-all `robots.txt`. Unset means indexed. |
60
+ | `SANDCMS_BOOTSTRAP_EMAIL` | On a start with no users, creates this administrator and logs a one-time password. Remove it after first sign-in. |
61
+ | `SANDCMS_CANONICAL_REDIRECT` | `false` turns off the redirect of other hostnames to `SANDCMS_ORIGIN`. Unset means on. See [first start](#first-start). |
62
+ | `SANDCMS_SITE_RENAME` | `true` for one start after renaming the project in `config.yaml`, so the volume's `site-id` follows. Remove it afterwards. |
63
+ | `SANDCMS_ALLOW_UNMOUNTED_DATA` | `true` allows a new production database outside a mounted volume. Only for hosts without container volumes. |
64
+ | `PORT` | The port the server listens on (3000 in the starter image). |
65
+ | `SHUTDOWN_TIMEOUT` | The Bun adapter's drain time in seconds after SIGTERM. The starter image sets `8`, inside the 10 s stop timeout hosts default to. |
66
+
67
+ `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` were removed in 0.8.0 and are no longer read; remove them from the environment. See [Cloudflare](cloudflare.md).
32
68
 
33
69
  ### Environment validation
34
70
 
@@ -42,13 +78,62 @@ SANDCMS_SECRET
42
78
  - Must be at least 32 characters
43
79
  ```
44
80
 
45
- Configure a container health check (for example `GET /admin/login`) so that a deployment with a broken environment never replaces the running release. Builds skip the required checks, so secrets need not be present in the build environment. Values are all runtime (`static: false`); none are inlined into the bundle. `SANDCMS_WORKER_TOKEN` stays optional so local development works without Cloudflare media. Declare your own variables in the same `defineEnvVars` call; see [SvelteKit environment variables](https://svelte.dev/docs/kit/environment-variables).
81
+ With a health check configured, a deployment with a broken environment never goes live. Builds skip the required checks, so secrets need not be present in the build environment. Values are all runtime (`static: false`); none are inlined into the bundle. Declare your own variables in the same `defineEnvVars` call; see [SvelteKit environment variables](https://svelte.dev/docs/kit/environment-variables).
82
+
83
+ ## Server build configuration
84
+
85
+ New sites get a multi-stage `Dockerfile` on the pinned Bun image: it installs with the frozen lockfile, builds, and runs `bun build/index.js` on port 3000 with `BODY_SIZE_LIMIT=10M`, `SHUTDOWN_TIMEOUT=8`, `SANDCMS_AUTO_MIGRATE=true` and `SANDCMS_DATABASE=/data/sandcms.sqlite`. Its `HEALTHCHECK` probes `/_sandcms/health` every 5 seconds and turns unhealthy after 24 failures (about two minutes, the budget for migrations). It has no `VOLUME` instruction; the host mounts the volume. New sites also get an `openship.json` that OpenShip reads when the project is created (see [OpenShip](#openship)). `.dockerignore` excludes local credentials, databases, media and build/test artifacts. Do not create accounts during image builds.
86
+
87
+ Existing sites can keep building with Railpack and `railpack.json`, or copy the starter `Dockerfile` from the package (`node_modules/sandcms/templates/Dockerfile`). Either way, start the server with `bun build/index.js`.
88
+
89
+ The starter's `vite.config.ts` contains this server configuration. Merge it into existing sites, preserving other plugins and SSR options:
90
+
91
+ ```ts
92
+ sveltekit({ adapter: adapter(), preprocess: vitePreprocess() }),
93
+ // …
94
+ ssr: {
95
+ external: ['bun:sqlite', 'sharp'],
96
+ noExternal: ['@better-auth/core']
97
+ }
98
+ ```
99
+
100
+ - Do not set `paths.origin`. The site derives its origin from each request's `Host` header, so a domain change needs no rebuild.
101
+ - `sharp` stays external so its native binary loads at runtime. The image processor runs as a child process from the package's `sandcms/media-processor` entry.
102
+ - Vite bundles `@better-auth/core` using its server export conditions to retain native async request storage. Keep it out of `ssr.external`, which takes precedence over `noExternal`. See [Vite SSR options](https://vite.dev/config/ssr-options) and the [Bun adapter](https://svelte.dev/docs/kit/adapter-bun).
103
+
104
+ `cmsHandle` must run first in `sequence()` in `src/hooks.server.ts`: it serves health checks, redirects other hostnames, enforces the request body limit and receives upload chunks before anything else reads the request.
105
+
106
+ ## Health check
107
+
108
+ `GET /_sandcms/health` returns 200 when the CMS has started and the database answers, and 503 when the database query fails. The CMS starts on the first request, which is usually this check: it applies pending migrations (with `SANDCMS_AUTO_MIGRATE=true`) and checks the schema first, and answers 500 while that fails. Hosts therefore switch traffic to a new container only after its migrations succeeded. A full disk or a media problem does not fail the check; it shows in the admin and in `sandcms doctor`. The health route is exempt from the hostname redirect, so the host can call it on any address.
109
+
110
+ ## Deploys
111
+
112
+ Deploys overlap: the host starts the new container next to the old one, waits until its health check passes, switches traffic, then stops the old container. Nobody sees downtime, and a release that fails to start never goes live. Per platform, see [platform settings](#platform-settings).
113
+
114
+ - **Shared volume.** Both containers use the same SQLite database for a short time. SQLite handles two processes on a local volume; background work coordinates through database leases (one image is processed at a time, one server writes the hourly snapshot), and sessions, rate limits and upload progress are database rows, so visitors and editors keep working across the switch. Keep `SANDCMS_SECRET` the same across deploys. Run a single replica per site; several long-running replicas are not supported.
115
+ - **Migrations.** The new container migrates on its first health check while the old one still serves. Every migration must therefore keep the previous release working on the migrated database; the old release only checks the schema when it starts and keeps serving afterwards. A previous release that starts again on that database (a restart, a crash, a rollback) accepts migrations it does not know as long as none is marked breaking; see [compatible migrations](upgrades.md#compatible-migrations).
116
+ - **Breaking releases.** A release whose notes say it contains a breaking migration cannot overlap. Deploy it stop-first: stop the site, deploy, and let the new container migrate on start. The previous release refuses that database afterwards, so rolling back means restoring the `before-migrate` snapshot.
117
+ - **Shutdown.** The old container gets SIGTERM, stops accepting connections, finishes requests in progress for up to `SHUTDOWN_TIMEOUT` seconds (8 in the starter image), stops background work and exits. Hosts send SIGKILL after their stop timeout, 10 seconds unless configured, so keep `SHUTDOWN_TIMEOUT` below it. Uploads are sent in 8 MB chunks and resume, so a cut-off chunk is simply sent again; unfinished image processing is picked up by the new container once its lease expires (at most two minutes).
118
+
119
+ ### Volume checks
120
+
121
+ The generated integration passes `server: true` to `createCMS()`; customized integrations need it too. Two checks then catch a wrong volume before content is written:
122
+
123
+ - On first start the server writes `/data/site-id` (a random ID and the project `name` from `config.yaml`). It refuses to start on a volume whose `site-id` names another project, so two sites cannot share a volume by mistake. After renaming the project, start once with `SANDCMS_SITE_RENAME=true`: the server rewrites `site-id` with the new name, keeps its ID and logs the change. Then remove the variable.
124
+ - In production, the server refuses to create a new database outside a mounted volume, where content would be lost when the container is replaced. The data directory may be the mount (`/data`) or inside one (`/data/db`). Set `SANDCMS_ALLOW_UNMOUNTED_DATA=true` only on hosts without container volumes where the directory does persist.
46
125
 
47
- `.dockerignore` excludes local credentials, databases, local R2 state, and build/test artifacts from the build context. Do not create accounts during image builds. The adapter may report `bun:sqlite` as an external module during bundling; it is intentionally provided by Bun at runtime.
126
+ ## First start
48
127
 
49
- ## Migrate and bootstrap the actual production volume
128
+ 1. Create the app on the host with its own volume and the environment above. Use a temporary hostname, `SANDCMS_INDEXING=false` and `SANDCMS_BOOTSTRAP_EMAIL`.
129
+ 2. Deploy. With `SANDCMS_AUTO_MIGRATE=true` the first start creates the database; with `SANDCMS_BOOTSTRAP_EMAIL` and no users, it creates that administrator and logs a one-time password. Sign in and change it.
130
+ 3. **Launch:** point the domain's DNS at the host, add the hostnames on the platform, set `SANDCMS_ORIGIN` to the final origin, remove `SANDCMS_INDEXING` and `SANDCMS_BOOTSTRAP_EMAIL`, and restart. Other hostnames, including the temporary one, now get a 308 redirect to the origin.
50
131
 
51
- After building and mounting the volume, use the host's operator command facility or a temporary container with the **same** volume:
132
+ The redirect compares the hostname of the request as the Bun adapter sees it: the `Host` header, or the header named by `HOST_HEADER`. A proxy that passes `Host` unchanged needs nothing else. A proxy that rewrites `Host` to an internal name (nginx does by default with `proxy_pass`) must forward the public name, for example in `X-Forwarded-Host` with `HOST_HEADER=x-forwarded-host`; otherwise every request would be redirected. `SANDCMS_CANONICAL_REDIRECT=false` turns the redirect off. The redirect is also off when `NODE_ENV` is not `production` (the starter image sets it).
133
+
134
+ Prerendered pages and files in `static/` are served without hooks, so they skip the redirect and the indexing header. `sandcms doctor` warns when a site has them.
135
+
136
+ Without shell access to bootstrap, the operator commands below are an alternative. Run them through the host's command facility or a one-off container with the **same** volume:
52
137
 
53
138
  ```sh
54
139
  bun x --no-install sandcms migrate --check --database /data/sandcms.sqlite
@@ -56,15 +141,17 @@ bun x --no-install sandcms migrate --database /data/sandcms.sqlite
56
141
  bun x --no-install sandcms user bootstrap --database /data/sandcms.sqlite --email admin@example.com
57
142
  ```
58
143
 
59
- In this source repository's demo image, use `bun dist/cli/index.js` in place of `bun x --no-install sandcms`. From 0.5.0, apply retained incremental migrations to upgrade supported databases. Changed pre-0.5.0 baselines still require a fresh database. If retaining the old state, take a verified backup with the matching old package before updating. See [upgrade workflow](upgrades.md). The app refuses to start with pending or incompatible migrations. Each numbered migration runs transactionally. Bootstrap only works when the selected database has no users, generates a password, and prints it once. A local account does not create a production account.
144
+ In this source repository's demo image, use `bun dist/cli/index.js` in place of `bun x --no-install sandcms`. Bootstrap only works when the selected database has no users, generates a password, and prints it once. A local account does not create a production account.
145
+
146
+ From 0.8.0, retained incremental migrations on the 0.8.0 baseline upgrade supported databases. A 0.7.x database is converted once with `sandcms rebaseline`; older ones are first upgraded with 0.7.x. See the [upgrade workflow](upgrades.md). The app refuses to start with pending or incompatible migrations, or after a newer release's breaking migration. Each numbered migration runs transactionally.
60
147
 
61
148
  ### Automatic migration on start
62
149
 
63
- Set `SANDCMS_AUTO_MIGRATE=true` to apply pending migrations when the website starts instead of running `sandcms migrate` separately. The generated integration passes it to `createCMS({ autoMigrate })`; customized integrations must add `autoMigrate: env.SANDCMS_AUTO_MIGRATE` themselves when reading `$app/env/private` (the value is already a boolean), or `autoMigrate: process.env.SANDCMS_AUTO_MIGRATE === 'true'` when still reading `process.env`. Before migrating an existing database, the website writes a verified snapshot to `<database>.before-migrate-<timestamp>-<id>.sqlite` beside it and logs its path; empty databases are initialized without a snapshot, and a non-empty database with no migration history is refused. Incompatible or modified histories are still rejected without changes, a failed migration rolls back and stops startup, and concurrent starts apply each migration once. Snapshots are not pruned automatically; remove them after verifying the upgrade. Auto-migration does not create accounts; still run `user bootstrap` on a fresh volume. Leave it unset to keep the explicit operator workflow.
150
+ Set `SANDCMS_AUTO_MIGRATE=true` to apply pending migrations when the website starts instead of running `sandcms migrate` separately. The generated integration passes it to `createCMS({ autoMigrate })`; customized integrations must add `autoMigrate: env.SANDCMS_AUTO_MIGRATE` themselves when reading `$app/env/private` (the value is already a boolean), or `autoMigrate: process.env.SANDCMS_AUTO_MIGRATE === 'true'` when still reading `process.env`. Before migrating an existing database, the website writes a verified snapshot to `<database>.before-migrate-<timestamp>-<id>.sqlite` beside it and logs its path; the newest three are kept. A start that fails is retried by every request and health check; those retries reuse the process's snapshot instead of writing a new one each time. Empty databases are initialized without a snapshot, and a non-empty database with no migration history is refused. Incompatible or modified histories are still rejected without changes, and a failed migration rolls back and stops startup. The starter image sets it, so overlapping deploys migrate before traffic switches. Set it to `false` to keep the explicit operator workflow.
64
151
 
65
- For a one-off Docker command, override Railpack's shell entrypoint with `--entrypoint bun`, then pass `dist/cli/index.js migrate` after the image name. Mount the same `/data` volume and supply runtime variables. See the [local container drill](acceptance.md) for the tested setup.
152
+ ### Users
66
153
 
67
- A new user added later must have an operator/admin-supplied password. The CLI prompts without echo; automation may use `--password-stdin`. Both paths require a change at first login. Password and 2FA recovery invalidate sessions and write audit metadata:
154
+ A new user added later must have an operator- or admin-supplied password. The CLI prompts without echo; automation may use `--password-stdin`. Both paths require a change at first login. Password and 2FA recovery invalidate sessions and write audit metadata:
68
155
 
69
156
  ```sh
70
157
  bun x --no-install sandcms user add --email editor@example.com --role editor
@@ -72,60 +159,138 @@ bun x --no-install sandcms user reset-password --email editor@example.com
72
159
  bun x --no-install sandcms user reset-2fa --email editor@example.com
73
160
  ```
74
161
 
75
- HTTPS origins use secure cookies. CMS writes validate origin, authentication is enforced server-side, and logins have per-email and per-client limits. By default the application does not read proxy IP headers. Only set `SANDCMS_TRUSTED_PROXY_HEADER` after the reverse proxy strips/replaces the chosen header and the application cannot be reached around that proxy. Configure the adapter's client-address handling consistently. A wrongly trusted forwarded header defeats client rate limiting.
162
+ Operators can also see and change accounts from the server, for example when the only admin has left or a laptop is lost. Every change is recorded in the audit log with the actor `operator`:
163
+
164
+ ```sh
165
+ bun x --no-install sandcms user list # roles, 2FA, active sessions; --json for scripts
166
+ bun x --no-install sandcms user set-role --email editor@example.com --role admin
167
+ bun x --no-install sandcms user remove --email editor@example.com
168
+ bun x --no-install sandcms user sign-out --email editor@example.com
169
+ bun x --no-install sandcms user sign-out --all # everyone, without changing passwords
170
+ bun x --no-install sandcms key list
171
+ bun x --no-install sandcms key revoke --email editor@example.com # every key of that user
172
+ ```
173
+
174
+ `set-role` and `remove` keep at least one admin. Removing a user deletes their sessions and API keys; their content is kept. `remove` and `sign-out --all` ask for confirmation and need `--yes` in a non-interactive shell such as `docker exec` without `-t`. `sandcms --help` lists every command; `sandcms <command> --help` shows its options.
175
+
176
+ To let an agent or script use the content API, create a key from the CLI with `sandcms key create --email editor@example.com --name NAME --scope write`; see [API keys from the CLI](api.md#from-the-cli).
76
177
 
77
- ## Client IP behind Dokploy and Cloudflare
178
+ HTTPS origins use secure cookies. CMS writes validate origin, authentication is enforced server-side, and logins have per-email and per-client limits.
78
179
 
79
- For a Cloudflare-proxied website routed through Dokploy's reverse proxy, configure the trust boundary first:
180
+ ## Client IP behind a reverse proxy
80
181
 
81
- 1. Restrict the website's origin ingress to [Cloudflare traffic](https://developers.cloudflare.com/fundamentals/security/protect-your-origin-server/). Keep the Bun container port private so requests cannot bypass Dokploy's proxy.
82
- 2. Preserve Cloudflare's `CF-Connecting-IP` through Dokploy's proxy. Strip or replace untrusted copies on any other ingress; do not accept arbitrary client-supplied values. Cloudflare supplies the visitor address in [this single-address header](https://developers.cloudflare.com/fundamentals/reference/http-headers/).
83
- 3. Set both runtime variables in Dokploy and restart the website. `sandcms setup` adds commented examples to `.env.local`; copying those values into Dokploy is a manual deployment step. The comments alone do not enable proxy trust:
182
+ By default the application reads no proxy IP headers, and every visitor appears to come from the proxy. To rate-limit per visitor:
183
+
184
+ 1. Find the header your proxy sets to the client address: Traefik (Dokploy) and nginx commonly use `X-Real-IP`; Cloudflare in front of the proxy sets `CF-Connecting-IP`.
185
+ 2. Make sure the proxy **overwrites** that header on every request, and that the container port is not reachable around the proxy. Otherwise a visitor can supply any address.
186
+ 3. Set both variables to that header and restart:
84
187
 
85
188
  ```dotenv
86
- SANDCMS_TRUSTED_PROXY_HEADER=cf-connecting-ip
87
- ADDRESS_HEADER=cf-connecting-ip
189
+ SANDCMS_TRUSTED_PROXY_HEADER=x-real-ip
190
+ ADDRESS_HEADER=x-real-ip
88
191
  ```
89
192
 
90
- `SANDCMS_TRUSTED_PROXY_HEADER` controls CMS login and access-link rate limits. The [Bun adapter's `ADDRESS_HEADER`](https://svelte.dev/docs/kit/adapter-bun) controls `event.getClientAddress()`, including website form actions. `XFF_DEPTH` is unnecessary for this single-address header. The CMS falls back to `event.getClientAddress()` if its configured header is absent or empty; the Bun adapter throws if its configured `ADDRESS_HEADER` is absent. Ensure requests that resolve a client address pass through the configured proxy chain.
193
+ `SANDCMS_TRUSTED_PROXY_HEADER` controls CMS login and access-link rate limits. The [Bun adapter's `ADDRESS_HEADER`](https://svelte.dev/docs/kit/adapter-bun) controls `event.getClientAddress()`, including website form actions. Use a single-address header; with `X-Forwarded-For`, the adapter also needs `XFF_DEPTH`. The CMS falls back to `event.getClientAddress()` if its header is absent or empty; the Bun adapter throws if its `ADDRESS_HEADER` is absent. A wrongly trusted header defeats client rate limiting.
91
194
 
92
- Run `sandcms doctor` with the deployment environment. It warns when `SANDCMS_ORIGIN` uses HTTPS and no CMS proxy header is set; this warning does not verify ingress rules or the actual headers.
195
+ With Cloudflare proxying in front of the host, use `cf-connecting-ip` instead, restrict the host's ingress to [Cloudflare traffic](https://developers.cloudflare.com/fundamentals/security/protect-your-origin-server/), and replace untrusted copies on any other ingress.
93
196
 
94
- On staging, temporarily log only the resolved address immediately before a form submission:
197
+ `sandcms doctor` warns when `SANDCMS_ORIGIN` uses HTTPS and no CMS proxy header is set; it does not verify the proxy. To check, temporarily log `event.getClientAddress()` in a form action on staging, submit from two networks, and confirm each shows its own public IP and that a supplied spoofed header has no effect. Remove the logging afterwards.
95
198
 
96
- ```ts
97
- console.info('staging form client address', event.getClientAddress());
98
- ```
199
+ ## Backups and restore
200
+
201
+ Back up the **whole volume** on a schedule, to storage off the server. The site may keep running while the copy is taken.
202
+
203
+ A file copy of a live SQLite database can be torn, so the site also writes a verified snapshot of its database every hour to `/data/backups/latest.sqlite`, keeping the one before as `previous.sqlite`. It catches up shortly after start when the last snapshot is older than an hour. Snapshots run in a separate process, so they do not hold up requests. Any volume backup therefore contains a consistent database. `sandcms doctor` reports the snapshot age.
204
+
205
+ **Restore:**
206
+
207
+ 1. Stop the site and disable automatic restarts.
208
+ 2. Restore the volume from the backup.
209
+ 3. Restore the database from the snapshot inside it, using a one-off container with the same volume:
210
+
211
+ ```sh
212
+ bun x --no-install sandcms restore --database /data/sandcms.sqlite --from /data/backups/latest.sqlite
213
+ ```
99
214
 
100
- Submit from two different networks and check the server logs: each should show that visitor's public IP rather than the same proxy IP. Confirm one visitor reaching the form limit does not block the other, and check that a supplied spoofed `CF-Connecting-IP` cannot override the address through the public ingress. Remove the temporary logging after verification. This staging check remains operator-owned until deployment access is available.
215
+ 4. Start the site, and check for media rows without files:
101
216
 
102
- ## Consistent backups
217
+ ```sh
218
+ bun x --no-install sandcms media verify
219
+ ```
220
+
221
+ Always restore the database from the snapshot; the copy of the live database in the volume backup may be torn. The snapshot can be up to an hour older than the media files in the same backup, so recent edits can be lost and recent uploads can exist as files without rows (they are harmless). `media verify --repair` re-renders missing variants and marks images whose original is missing as failed; see [media](media.md#checking-and-repairing-files).
222
+
223
+ The restore command verifies the backup and schema, obtains an exclusive lock on `sandcms.sqlite.guard.sqlite`, creates a verified `before-restore` safety snapshot, checkpoints WAL, and replaces the target. Every CMS database connection holds a shared guard lock for its lifetime, so an in-use restore is refused. Keep the guard file with the database; do not delete it to bypass the check. `--yes` is an explicit noninteractive confirmation; it does not bypass locking.
224
+
225
+ For an extra copy outside the volume, `sandcms backup` writes a verified snapshot to any path:
103
226
 
104
227
  ```sh
105
- bun x --no-install sandcms backup --database /data/sandcms.sqlite --output /backups/site-2026-09-25.sqlite
228
+ bun x --no-install sandcms backup --database /data/sandcms.sqlite --output /data/backups/manual-2026-11-17.sqlite
106
229
  ```
107
230
 
108
- This uses SQLite `VACUUM INTO`, validates integrity, foreign keys and migration history, then installs the snapshot at the requested path. The output is a local artifact with restrictive permissions. Never copy a live WAL-mode `.sqlite` file by itself. Scheduling, destination, encryption, retention, and deletion policy belong to the operator.
231
+ It uses SQLite `VACUUM INTO`, validates integrity, foreign keys and migration history, and writes the file with restrictive permissions. Never copy a live WAL-mode `.sqlite` file by itself.
232
+
233
+ ## Rollback
109
234
 
110
- ## Offline restore drill
235
+ Use the platform's rollback to return to the previous image. All three platforms below start the previous image on the current volume, and none of them undoes database changes. When the bad release's migrations were compatible (the normal case), the previous release accepts the migrated database and starts normally.
111
236
 
112
- 1. Stop every website process using the volume; disable automatic restarts during the restore.
113
- 2. Run a one-off command/container mounting the same volume and backup.
114
- 3. Restore, explicitly confirming the displayed target:
237
+ After a breaking migration, the previous release refuses the database. Stop the site and restore the `before-migrate` snapshot that the migration logged, then roll back:
115
238
 
116
239
  ```sh
117
- bun x --no-install sandcms restore --database /data/sandcms.sqlite --from /backups/site-2026-09-25.sqlite
240
+ bun x --no-install sandcms restore --database /data/sandcms.sqlite --from /data/sandcms.sqlite.before-migrate-<timestamp>-<id>.sqlite
118
241
  ```
119
242
 
120
- The CLI verifies the backup and schema, obtains an exclusive lock on `sandcms.sqlite.guard.sqlite`, creates a verified `before-restore` safety snapshot, checkpoints WAL, and replaces the target. Every CMS database connection holds a shared guard lock for its lifetime, so an in-use restore is refused. Keep the guard file with the database; do not delete it to bypass the check. Raw external SQLite tools that do not honor this guard must also be stopped. `--yes` is an explicit noninteractive restore confirmation; it does not bypass locking.
243
+ Content edited after the migration is lost.
244
+
245
+ ## Memory and image limits
246
+
247
+ Images are decoded in a child process, one at a time, so a decode that exceeds the container's memory limit kills the child, not the web server; the image is retried and then marked failed. Give the container enough memory for one decode at `media.maxPixels` (100 megapixels by default) on top of the web server. Lower `media.maxPixels` on small servers. See [media limits](media.md#limits).
248
+
249
+ ## Platform settings
250
+
251
+ OpenShip, Dokploy and Coolify all build the site from its `Dockerfile` on push, mount a named volume and put a reverse proxy with Let's Encrypt in front. They differ in what they overlap by default and in what decides the switch. These settings were checked against each platform's source code (OpenShip 1.0.1, Dokploy 0.31.4, Coolify 4.7.6).
252
+
253
+ | | OpenShip | Dokploy | Coolify |
254
+ | --------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
255
+ | Overlaps by default | No: set the route strategy to `container-ip` | Yes (`start-first`) | Yes, unless host ports, a fixed container name or a custom IP are set |
256
+ | Switches traffic when | Its readiness probe passes (the `HEALTHCHECK` is ignored) | The `HEALTHCHECK` is healthy | The `HEALTHCHECK` is healthy |
257
+ | Stop timeout | 10 s, not configurable | 10 s, configurable | 30 s, configurable |
258
+ | Failed deploy | Old container keeps serving; reported, with an email | Old container keeps serving through a Swarm rollback, but the deploy is reported as **successful** | Old container keeps serving; reported |
259
+ | Rollback | Previous image, current volume | Previous image, current volume (needs a registry) | Previous image, current volume |
260
+ | Auto-deploy on push | Off by default; GitHub, or a deploy webhook for other hosts | When enabled; GitHub, GitLab, Gitea, Bitbucket | On by default; GitHub, GitLab, Gitea, Bitbucket |
261
+
262
+ All three run pushes for one site one at a time, so two deploys of a site never overlap each other. Keep **preview deployments off**: Dokploy gives previews the production volume, where they would migrate the live database, and Coolify copies production secrets into previews.
263
+
264
+ ### OpenShip
265
+
266
+ OpenShip stops the old container first unless the project's route strategy is `container-ip`, which cannot be set from the repository:
267
+
268
+ 1. Run OpenShip on a Linux Docker host (overlap does not work with Docker Desktop) with `curl` installed: a readiness probe that cannot run counts as passed.
269
+ 2. Before creating site projects, run `openship settings route-strategy container-ip` once. It applies to projects you create afterwards; change existing ones under the project's Advanced settings.
270
+ 3. Create the project from the site's Git repository. The generated `openship.json` seeds the `/data` volume and a readiness probe on `/_sandcms/health` that fails the deploy (`onFailure: "fail"`) when the site does not become healthy within 180 seconds. OpenShip reads it only when the project is created; later changes go in the project settings. Projects that deploy a prebuilt image need the same readiness settings entered there.
271
+ 4. Turn on auto-deploy (Source tab, or `openship project git auto-deploy <id> --enable`); it is off by default.
272
+
273
+ OpenShip's release commands are not needed: the health check runs migrations before the switch. Keep secrets out of `ARG` lines in a customized `Dockerfile`; OpenShip passes every project variable as a build argument.
274
+
275
+ ### Dokploy
276
+
277
+ Dokploy deploys every application as a Docker Swarm service that starts the new task first and routes to it once the image's `HEALTHCHECK` passes.
121
278
 
122
- Restart the application and verify content, sign-in, media links, and inbox. Restoring SQLite does not restore deleted R2 objects; an operator requiring media disaster recovery must back up the R2 bucket separately. The CMS does not select that storage or policy.
279
+ - Mount a named volume at `/data`. Volume names are global on a server, so give each site its own, such as `sandcms-<slug>-data`.
280
+ - Set **Stop Grace Period** to `10000000000` (10 s, in nanoseconds) or more, and leave **Update Config** empty. If you set it, give all of `Parallelism: 1`, `Order: start-first` and `FailureAction: rollback`: a partial setting replaces Dokploy's defaults and Swarm then pauses instead of rolling back.
281
+ - Set the domain's container port to 3000, keep one replica, enable Auto Deploy for the site's branch, and keep Preview Deployments off.
282
+ - Dokploy reports a deploy as done before the new container is healthy. Check the service after a deploy; a failed health check shows as a Swarm rollback, not as a failed deploy.
283
+ - Dokploy's Rollbacks feature needs a registry and drops the stop grace period; set it again after a rollback. Volume backups are full archives. Traefik sets `X-Real-IP`.
123
284
 
124
- ## Dokploy example and pending host proof
285
+ ### Coolify
125
286
 
126
- In Dokploy, select Railpack, mount the persistent volume, configure runtime secrets, and run the production bootstrap command against that volume. Deploy a second image to prove content survives replacement, then perform the offline restore drill. Actual Dokploy access was intentionally deferred, so this host proof remains a release gate.
287
+ Coolify starts the new container next to the old one, waits for the `HEALTHCHECK` (it reads its timings from the `Dockerfile`), waits a short drain period, then stops the old container.
127
288
 
128
- The team's discussed nightly 03:00 backup to Hetzner Object Storage with 30-day expiry is an operator choice, not a package default. A host-managed named-volume backup may stop the container for consistency; the portable CLI snapshot remains available on other hosts.
289
+ - Leave Coolify's own health check off; the image's `HEALTHCHECK` is used. Coolify's HTTP check would need `curl` or `wget` in the image.
290
+ - Do not map host ports, do not enable a consistent container name, and do not set a custom IP; each of these makes Coolify stop the old container first.
291
+ - Mount a volume at `/data`, set **Ports Exposes** to 3000, and keep one server per site.
292
+ - Leave the pre- and post-deployment commands empty: the pre-deployment command runs in the old container and cannot migrate.
293
+ - Auto-deploy is on by default. Coolify's deploy API needs `POST` (`GET` returns 405).
129
294
 
130
295
  ## Transactional email
131
296
 
package/docs/email.md CHANGED
@@ -38,6 +38,12 @@ const cms = createCMS({
38
38
  });
39
39
  ```
40
40
 
41
+ To check the settings from the server, send a test message. It uses the same variables as the website and prints the categorized reason on failure:
42
+
43
+ ```sh
44
+ bun x --no-install sandcms email test --to you@example.com
45
+ ```
46
+
41
47
  ## Sending
42
48
 
43
49
  Call from server code and await the result:
package/docs/forms.md CHANGED
@@ -11,9 +11,9 @@ const result = await cms.forms.submit('registration', validatedData, {
11
11
 
12
12
  The helper accepts plain JSON objects up to 64 KB, rejects cycles, non-finite numbers, reserved keys, and excessive nesting, silently ignores filled honeypots, and applies a durable per-form/per-client limit of five accepted attempts per minute. Supply a server-derived client identity. Never pass a browser-provided identity or trust proxy headers without configuring your host's trusted proxy chain.
13
13
 
14
- Behind Dokploy and Cloudflare, configure both `ADDRESS_HEADER` and `SANDCMS_TRUSTED_PROXY_HEADER` as described in the [client IP recipe](deployment.md#client-ip-behind-dokploy-and-cloudflare). The CMS setting alone does not change `event.getClientAddress()` in website form actions; without adapter configuration, visitors can share the proxy's five-attempt bucket.
14
+ Behind a reverse proxy, configure both `ADDRESS_HEADER` and `SANDCMS_TRUSTED_PROXY_HEADER` as described in the [client IP recipe](deployment.md#client-ip-behind-a-reverse-proxy). The CMS setting alone does not change `event.getClientAddress()` in website form actions; without adapter configuration, visitors can share the proxy's five-attempt bucket.
15
15
 
16
- Form YAML supplies stable IDs, labels, optional nested field groups, list `columns`, and `export` ordering. Each accepted submission stores its own blueprint snapshot so prior labels and export columns remain readable after changes. Both CMS roles can read, mark read/unread, export CSV, and delete. Export preserves historical field labels and guards formula-like spreadsheet cells.
16
+ Form YAML supplies stable IDs, labels, optional nested field groups, list `columns`, and `export` ordering. Each accepted submission stores its own blueprint snapshot so prior labels and export columns remain readable after changes. Both CMS roles can read, mark read/unread, export CSV, and delete. Export preserves historical field labels and guards formula-like spreadsheet cells. Operators can write the same CSV from the server with `sandcms forms export FORM_ID --output PATH`; the file is created readable only by its owner because it contains personal data.
17
17
 
18
18
  `src/routes/(site)/registration` demonstrates native `use:enhance`, participant name, birth date, contact/address, program selection, gender, prior experience, and conditional guardian contact. The server independently checks the participant's age and requires guardian contact under 18; changing client-side markup cannot bypass that validation.
19
19