sandcms 0.6.2 → 0.7.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 (260) hide show
  1. package/README.md +14 -10
  2. package/dist/admin/Account.svelte +286 -83
  3. package/dist/admin/Admin.svelte +14 -1
  4. package/dist/admin/ApiKeys.svelte +146 -79
  5. package/dist/admin/AssetAttachment.svelte +10 -12
  6. package/dist/admin/AssetAttachment.svelte.d.ts +0 -1
  7. package/dist/admin/BlueprintFields.svelte +20 -5
  8. package/dist/admin/BlueprintFields.svelte.d.ts +2 -1
  9. package/dist/admin/Collection.svelte +111 -54
  10. package/dist/admin/Dashboard.svelte +3 -37
  11. package/dist/admin/DateField.svelte +75 -0
  12. package/dist/admin/DateField.svelte.d.ts +11 -0
  13. package/dist/admin/Editor.svelte +70 -65
  14. package/dist/admin/Fields.svelte +24 -23
  15. package/dist/admin/Fields.svelte.d.ts +0 -1
  16. package/dist/admin/FocusPicker.svelte +1 -2
  17. package/dist/admin/Gallery.svelte +2 -7
  18. package/dist/admin/Gallery.svelte.d.ts +0 -1
  19. package/dist/admin/GlobalSearch.svelte +54 -26
  20. package/dist/admin/HoverHint.svelte +37 -0
  21. package/dist/admin/HoverHint.svelte.d.ts +8 -0
  22. package/dist/admin/Inbox.svelte +6 -11
  23. package/dist/admin/LinkField.svelte +128 -66
  24. package/dist/admin/LinkField.svelte.d.ts +0 -1
  25. package/dist/admin/Login.svelte +0 -1
  26. package/dist/admin/MediaLibrary.svelte +70 -56
  27. package/dist/admin/MediaPicker.svelte +62 -55
  28. package/dist/admin/MediaPicker.svelte.d.ts +0 -1
  29. package/dist/admin/NotificationSettings.svelte +35 -27
  30. package/dist/admin/RichText.svelte +2 -2
  31. package/dist/admin/RowMenu.svelte +28 -0
  32. package/dist/admin/RowMenu.svelte.d.ts +10 -0
  33. package/dist/admin/SearchList.svelte +51 -14
  34. package/dist/admin/Shell.svelte +64 -29
  35. package/dist/admin/ThemePicker.svelte +72 -0
  36. package/dist/admin/ThemePicker.svelte.d.ts +18 -0
  37. package/dist/admin/UploadButton.svelte +2 -1
  38. package/dist/admin/UploadProgress.svelte +24 -0
  39. package/dist/admin/UploadProgress.svelte.d.ts +7 -0
  40. package/dist/admin/Users.svelte +106 -50
  41. package/dist/admin/client.d.ts +5 -670
  42. package/dist/admin/client.js +20 -1
  43. package/dist/admin/components/ui/alert/alert.svelte.d.ts +3 -13
  44. package/dist/admin/components/ui/attachment/attachment-media.svelte.d.ts +3 -13
  45. package/dist/admin/components/ui/attachment/attachment.svelte.d.ts +6 -26
  46. package/dist/admin/components/ui/badge/badge.svelte.d.ts +7 -25
  47. package/dist/admin/components/ui/button/button.svelte.d.ts +15 -53
  48. package/dist/admin/components/ui/calendar/calendar-caption.svelte +76 -0
  49. package/dist/admin/components/ui/calendar/calendar-caption.svelte.d.ts +19 -0
  50. package/dist/admin/components/ui/calendar/calendar-cell.svelte +19 -0
  51. package/dist/admin/components/ui/calendar/calendar-cell.svelte.d.ts +4 -0
  52. package/dist/admin/components/ui/calendar/calendar-day.svelte +33 -0
  53. package/dist/admin/components/ui/calendar/calendar-day.svelte.d.ts +4 -0
  54. package/dist/admin/components/ui/calendar/calendar-grid-body.svelte +12 -0
  55. package/dist/admin/components/ui/calendar/calendar-grid-body.svelte.d.ts +4 -0
  56. package/dist/admin/components/ui/calendar/calendar-grid-head.svelte +12 -0
  57. package/dist/admin/components/ui/calendar/calendar-grid-head.svelte.d.ts +4 -0
  58. package/dist/admin/components/ui/calendar/calendar-grid-row.svelte +12 -0
  59. package/dist/admin/components/ui/calendar/calendar-grid-row.svelte.d.ts +4 -0
  60. package/dist/admin/components/ui/calendar/calendar-grid.svelte +16 -0
  61. package/dist/admin/components/ui/calendar/calendar-grid.svelte.d.ts +4 -0
  62. package/dist/admin/components/ui/calendar/calendar-head-cell.svelte +19 -0
  63. package/dist/admin/components/ui/calendar/calendar-head-cell.svelte.d.ts +4 -0
  64. package/dist/admin/components/ui/calendar/calendar-header.svelte +19 -0
  65. package/dist/admin/components/ui/calendar/calendar-header.svelte.d.ts +4 -0
  66. package/dist/admin/components/ui/calendar/calendar-heading.svelte +16 -0
  67. package/dist/admin/components/ui/calendar/calendar-heading.svelte.d.ts +4 -0
  68. package/dist/admin/components/ui/calendar/calendar-month-select.svelte +48 -0
  69. package/dist/admin/components/ui/calendar/calendar-month-select.svelte.d.ts +4 -0
  70. package/dist/admin/components/ui/calendar/calendar-month.svelte +15 -0
  71. package/dist/admin/components/ui/calendar/calendar-month.svelte.d.ts +5 -0
  72. package/dist/admin/components/ui/calendar/calendar-months.svelte +19 -0
  73. package/dist/admin/components/ui/calendar/calendar-months.svelte.d.ts +5 -0
  74. package/dist/admin/components/ui/calendar/calendar-nav.svelte +19 -0
  75. package/dist/admin/components/ui/calendar/calendar-nav.svelte.d.ts +5 -0
  76. package/dist/admin/components/ui/calendar/calendar-next-button.svelte +37 -0
  77. package/dist/admin/components/ui/calendar/calendar-next-button.svelte.d.ts +8 -0
  78. package/dist/admin/components/ui/calendar/calendar-prev-button.svelte +37 -0
  79. package/dist/admin/components/ui/calendar/calendar-prev-button.svelte.d.ts +8 -0
  80. package/dist/admin/components/ui/calendar/calendar-year-select.svelte +47 -0
  81. package/dist/admin/components/ui/calendar/calendar-year-select.svelte.d.ts +4 -0
  82. package/dist/admin/components/ui/calendar/calendar.svelte +115 -0
  83. package/dist/admin/components/ui/calendar/calendar.svelte.d.ts +21 -0
  84. package/dist/admin/components/ui/calendar/index.d.ts +19 -0
  85. package/dist/admin/components/ui/calendar/index.js +21 -0
  86. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-checkbox-group.svelte +16 -0
  87. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-checkbox-group.svelte.d.ts +4 -0
  88. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-checkbox-item.svelte +46 -0
  89. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-checkbox-item.svelte.d.ts +9 -0
  90. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-content.svelte +31 -0
  91. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-content.svelte.d.ts +10 -0
  92. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-group-heading.svelte +22 -0
  93. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-group-heading.svelte.d.ts +8 -0
  94. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-group.svelte +7 -0
  95. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-group.svelte.d.ts +4 -0
  96. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-item.svelte +27 -0
  97. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-item.svelte.d.ts +8 -0
  98. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-label.svelte +24 -0
  99. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-label.svelte.d.ts +8 -0
  100. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-portal.svelte +7 -0
  101. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-portal.svelte.d.ts +3 -0
  102. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-radio-group.svelte +16 -0
  103. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-radio-group.svelte.d.ts +4 -0
  104. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-radio-item.svelte +36 -0
  105. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-radio-item.svelte.d.ts +4 -0
  106. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-separator.svelte +17 -0
  107. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-separator.svelte.d.ts +4 -0
  108. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-shortcut.svelte +23 -0
  109. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-shortcut.svelte.d.ts +5 -0
  110. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub-content.svelte +31 -0
  111. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub-content.svelte.d.ts +10 -0
  112. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub-trigger.svelte +29 -0
  113. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub-trigger.svelte.d.ts +7 -0
  114. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub.svelte +7 -0
  115. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub.svelte.d.ts +3 -0
  116. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-trigger.svelte +7 -0
  117. package/dist/admin/components/ui/dropdown-menu/dropdown-menu-trigger.svelte.d.ts +4 -0
  118. package/dist/admin/components/ui/dropdown-menu/dropdown-menu.svelte +7 -0
  119. package/dist/admin/components/ui/dropdown-menu/dropdown-menu.svelte.d.ts +3 -0
  120. package/dist/admin/components/ui/dropdown-menu/index.d.ts +18 -0
  121. package/dist/admin/components/ui/dropdown-menu/index.js +18 -0
  122. package/dist/admin/components/ui/input-otp/index.d.ts +5 -0
  123. package/dist/admin/components/ui/input-otp/index.js +5 -0
  124. package/dist/admin/components/ui/input-otp/input-otp-group.svelte +23 -0
  125. package/dist/admin/components/ui/input-otp/input-otp-group.svelte.d.ts +5 -0
  126. package/dist/admin/components/ui/input-otp/input-otp-separator.svelte +27 -0
  127. package/dist/admin/components/ui/input-otp/input-otp-separator.svelte.d.ts +5 -0
  128. package/dist/admin/components/ui/input-otp/input-otp-slot.svelte +29 -0
  129. package/dist/admin/components/ui/input-otp/input-otp-slot.svelte.d.ts +4 -0
  130. package/dist/admin/components/ui/input-otp/input-otp.svelte +24 -0
  131. package/dist/admin/components/ui/input-otp/input-otp.svelte.d.ts +4 -0
  132. package/dist/admin/components/ui/popover/index.d.ts +9 -0
  133. package/dist/admin/components/ui/popover/index.js +11 -0
  134. package/dist/admin/components/ui/popover/popover-close.svelte +7 -0
  135. package/dist/admin/components/ui/popover/popover-close.svelte.d.ts +4 -0
  136. package/dist/admin/components/ui/popover/popover-content.svelte +31 -0
  137. package/dist/admin/components/ui/popover/popover-content.svelte.d.ts +10 -0
  138. package/dist/admin/components/ui/popover/popover-description.svelte +20 -0
  139. package/dist/admin/components/ui/popover/popover-description.svelte.d.ts +5 -0
  140. package/dist/admin/components/ui/popover/popover-header.svelte +20 -0
  141. package/dist/admin/components/ui/popover/popover-header.svelte.d.ts +5 -0
  142. package/dist/admin/components/ui/popover/popover-portal.svelte +7 -0
  143. package/dist/admin/components/ui/popover/popover-portal.svelte.d.ts +3 -0
  144. package/dist/admin/components/ui/popover/popover-title.svelte +20 -0
  145. package/dist/admin/components/ui/popover/popover-title.svelte.d.ts +5 -0
  146. package/dist/admin/components/ui/popover/popover-trigger.svelte +17 -0
  147. package/dist/admin/components/ui/popover/popover-trigger.svelte.d.ts +4 -0
  148. package/dist/admin/components/ui/popover/popover.svelte +7 -0
  149. package/dist/admin/components/ui/popover/popover.svelte.d.ts +3 -0
  150. package/dist/admin/components/ui/switch/switch.svelte +2 -2
  151. package/dist/admin/components/ui/toggle/toggle.svelte.d.ts +6 -26
  152. package/dist/admin/components/ui/tooltip/index.d.ts +6 -0
  153. package/dist/admin/components/ui/tooltip/index.js +8 -0
  154. package/dist/admin/components/ui/tooltip/tooltip-content.svelte +48 -0
  155. package/dist/admin/components/ui/tooltip/tooltip-content.svelte.d.ts +11 -0
  156. package/dist/admin/components/ui/tooltip/tooltip-portal.svelte +7 -0
  157. package/dist/admin/components/ui/tooltip/tooltip-portal.svelte.d.ts +4 -0
  158. package/dist/admin/components/ui/tooltip/tooltip-provider.svelte +7 -0
  159. package/dist/admin/components/ui/tooltip/tooltip-provider.svelte.d.ts +4 -0
  160. package/dist/admin/components/ui/tooltip/tooltip-trigger.svelte +7 -0
  161. package/dist/admin/components/ui/tooltip/tooltip-trigger.svelte.d.ts +25 -0
  162. package/dist/admin/components/ui/tooltip/tooltip.svelte +7 -0
  163. package/dist/admin/components/ui/tooltip/tooltip.svelte.d.ts +25 -0
  164. package/dist/admin/generated/admin.css +1298 -234
  165. package/dist/admin/slug.d.ts +1 -0
  166. package/dist/admin/slug.js +6 -0
  167. package/dist/admin/theme-context.d.ts +7 -0
  168. package/dist/admin/theme-context.js +3 -0
  169. package/dist/admin/theme.d.ts +7 -0
  170. package/dist/admin/theme.js +14 -0
  171. package/dist/admin/types.d.ts +2 -1
  172. package/dist/admin/uploads.d.ts +8 -1
  173. package/dist/admin/uploads.js +94 -16
  174. package/dist/blueprints/files.js +1 -0
  175. package/dist/blueprints/load.js +7 -2
  176. package/dist/blueprints/types.d.ts +4 -1
  177. package/dist/cli/doctor.d.ts +3 -1
  178. package/dist/cli/doctor.js +85 -30
  179. package/dist/cli/files.d.ts +2 -6
  180. package/dist/cli/files.js +11 -2
  181. package/dist/cli/index.js +99 -31
  182. package/dist/cli/scaffold.js +8 -8
  183. package/dist/cli/setup.js +16 -26
  184. package/dist/cli/upgrade.js +21 -2
  185. package/dist/env.d.ts +32 -0
  186. package/dist/env.js +53 -3
  187. package/dist/server/admin-load.d.ts +13 -5
  188. package/dist/server/admin-load.js +8 -3
  189. package/dist/server/api-access.d.ts +4 -0
  190. package/dist/server/api-access.js +15 -2
  191. package/dist/server/api-pagination.d.ts +3 -0
  192. package/dist/server/api.js +11 -3
  193. package/dist/server/auth.d.ts +11 -9
  194. package/dist/server/auth.js +23 -0
  195. package/dist/server/cms.d.ts +65 -18
  196. package/dist/server/cms.js +62 -6
  197. package/dist/server/db/migration-data.js +4 -0
  198. package/dist/server/db/migrations/0009_local_media.sql +9 -0
  199. package/dist/server/db/migrations/meta/0009_snapshot.json +1763 -0
  200. package/dist/server/db/migrations/meta/_journal.json +7 -0
  201. package/dist/server/db/schema.d.ts +119 -2
  202. package/dist/server/db/schema.js +15 -3
  203. package/dist/server/hooks.js +155 -81
  204. package/dist/server/media/contracts.d.ts +115 -0
  205. package/dist/server/media/contracts.js +12 -0
  206. package/dist/server/media/deletions.d.ts +2 -1
  207. package/dist/server/media/deletions.js +3 -3
  208. package/dist/server/media/delivery.js +7 -11
  209. package/dist/server/media/import-r2.d.ts +56 -0
  210. package/dist/server/media/import-r2.js +342 -0
  211. package/dist/server/media/processor-child.d.ts +2 -0
  212. package/dist/server/media/processor-child.js +236 -0
  213. package/dist/server/media/processor.d.ts +51 -0
  214. package/dist/server/media/processor.js +135 -0
  215. package/dist/server/media/render-math.d.ts +24 -0
  216. package/dist/server/media/render-math.js +50 -0
  217. package/dist/server/media/runner.d.ts +30 -1
  218. package/dist/server/media/runner.js +418 -165
  219. package/dist/server/media/service.d.ts +56 -10
  220. package/dist/server/media/service.js +309 -98
  221. package/dist/server/media/storage.d.ts +5 -0
  222. package/dist/server/media/storage.js +279 -0
  223. package/dist/server/media/svg.d.ts +5 -0
  224. package/dist/server/media/svg.js +142 -0
  225. package/dist/server/media/upload-ticket.d.ts +12 -0
  226. package/dist/server/media/upload-ticket.js +35 -0
  227. package/dist/server/media/verify.d.ts +36 -0
  228. package/dist/server/media/verify.js +109 -0
  229. package/dist/server/platform/http.d.ts +27 -0
  230. package/dist/server/platform/http.js +77 -0
  231. package/dist/server/platform/index.d.ts +52 -0
  232. package/dist/server/platform/index.js +98 -0
  233. package/dist/server/platform/snapshots.d.ts +18 -0
  234. package/dist/server/platform/snapshots.js +110 -0
  235. package/dist/server/platform/volume.d.ts +20 -0
  236. package/dist/server/platform/volume.js +60 -0
  237. package/dist/worker/svg.d.ts +1 -5
  238. package/dist/worker/svg.js +2 -142
  239. package/docs/acceptance.md +6 -4
  240. package/docs/api.md +42 -4
  241. package/docs/cloudflare.md +48 -142
  242. package/docs/content.md +2 -2
  243. package/docs/deployment.md +159 -57
  244. package/docs/forms.md +1 -1
  245. package/docs/media.md +85 -21
  246. package/docs/package.md +21 -18
  247. package/docs/plans/0.7-self-hosted.md +264 -0
  248. package/docs/releases.md +27 -1
  249. package/docs/upgrades.md +44 -6
  250. package/package.json +38 -37
  251. package/templates/Dockerfile +28 -0
  252. package/templates/integration.ts +18 -2
  253. package/templates/railpack.json +1 -1
  254. package/templates/sandcms/blueprints/files/image.yaml +1 -1
  255. package/templates/sandcms/config.yaml +0 -1
  256. package/dist/cli/cloudflare.d.ts +0 -8
  257. package/dist/cli/cloudflare.js +0 -135
  258. package/templates/sandcms/worker/index.ts +0 -1
  259. package/templates/sandcms/worker/local.ts +0 -1
  260. package/templates/sandcms/worker/wrangler.jsonc +0 -6
@@ -1,34 +1,69 @@
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; we recommend [Dokploy](https://dokploy.com) or [Openship](https://openship.io).
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
19
+
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 | Either overlap (start the new container, then stop the old) or stop-then-start. Stop timeout of at least 30 s |
25
+ | Reverse proxy | TLS, routes the site's hostnames, passes `Host` unchanged, overwrites the client-IP header it sets |
26
+ | Health check | The image's `HEALTHCHECK`, or `GET /_sandcms/health` |
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 |
17
29
 
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).
30
+ The proxy needs no raised timeouts or body limits: uploads arrive in 8 MB chunks, and every other request is under 1 MB.
19
31
 
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.
32
+ Do not put the volume on an object-store mount or an unproven network filesystem; SQLite needs local file locking.
21
33
 
22
- ## Host configuration
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
+ ```
23
47
 
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.
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
+
66
+ `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` are deprecated. They are read only by `sandcms media import-r2`; remove them once the [R2 import](cloudflare.md) is done.
32
67
 
33
68
  ### Environment validation
34
69
 
@@ -42,13 +77,57 @@ SANDCMS_SECRET
42
77
  - Must be at least 32 characters
43
78
  ```
44
79
 
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).
80
+ 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).
81
+
82
+ ## Server build configuration
83
+
84
+ 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` and `SANDCMS_DATABASE=/data/sandcms.sqlite`. It has a `HEALTHCHECK` on `/_sandcms/health` and no `VOLUME` instruction; the host mounts the volume. `.dockerignore` excludes local credentials, databases, media and build/test artifacts. Do not create accounts during image builds.
85
+
86
+ 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`.
87
+
88
+ The starter's `vite.config.ts` contains this server configuration. Merge it into existing sites, preserving other plugins and SSR options:
89
+
90
+ ```ts
91
+ sveltekit({ adapter: adapter(), preprocess: vitePreprocess() }),
92
+ // …
93
+ ssr: {
94
+ external: ['bun:sqlite', 'sharp'],
95
+ noExternal: ['@better-auth/core']
96
+ }
97
+ ```
98
+
99
+ - Do not set `paths.origin`. The site derives its origin from each request's `Host` header, so a domain change needs no rebuild.
100
+ - `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.
101
+ - 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).
102
+
103
+ `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.
104
+
105
+ ## Health check
106
+
107
+ `GET /_sandcms/health` returns 200 when the process serves requests and the database opens. It is a liveness check only: a full disk or a media problem shows in the admin and in `sandcms doctor`, and does not restart the site in a loop. The health route is exempt from the hostname redirect, so the host can call it on any address.
108
+
109
+ ## Deploys and volume checks
110
+
111
+ Both deploy styles work. Hosts that overlap (start the new container, wait until it is ready, switch traffic, then stop the old one, as Openship does on a Docker server) give zero-downtime deploys; hosts that stop the old container first have a few seconds of downtime. During an overlap both containers use the same SQLite database, which SQLite handles on a local volume. Background work coordinates through database leases: one image is processed at a time and one server writes the hourly snapshot. Use a stop timeout of at least 30 seconds so uploads in progress finish.
46
112
 
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.
113
+ With auto-migrate, the new container applies pending migrations while the old one is still serving. SandCMS migrations are additive, so the old code keeps working for the short overlap. Run a single replica per site; scaling out to several long-running replicas is not supported.
48
114
 
49
- ## Migrate and bootstrap the actual production volume
115
+ The generated integration passes `server: true` to `createCMS()`; customized integrations need it too. Two checks then catch a wrong volume before content is written:
50
116
 
51
- After building and mounting the volume, use the host's operator command facility or a temporary container with the **same** volume:
117
+ - 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.
118
+ - 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.
119
+
120
+ ## First start
121
+
122
+ 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`.
123
+ 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.
124
+ 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.
125
+
126
+ 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).
127
+
128
+ 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.
129
+
130
+ 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
131
 
53
132
  ```sh
54
133
  bun x --no-install sandcms migrate --check --database /data/sandcms.sqlite
@@ -56,15 +135,17 @@ bun x --no-install sandcms migrate --database /data/sandcms.sqlite
56
135
  bun x --no-install sandcms user bootstrap --database /data/sandcms.sqlite --email admin@example.com
57
136
  ```
58
137
 
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.
138
+ 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.
139
+
140
+ From 0.5.0, retained incremental migrations upgrade supported databases. Changed pre-0.5.0 baselines still require a fresh database; see the [upgrade workflow](upgrades.md). The app refuses to start with pending or incompatible migrations. Each numbered migration runs transactionally.
60
141
 
61
142
  ### Automatic migration on start
62
143
 
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.
144
+ 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. 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. Leave the variable unset to keep the explicit operator workflow.
64
145
 
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.
146
+ ### Users
66
147
 
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:
148
+ 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
149
 
69
150
  ```sh
70
151
  bun x --no-install sandcms user add --email editor@example.com --role editor
@@ -72,60 +153,81 @@ bun x --no-install sandcms user reset-password --email editor@example.com
72
153
  bun x --no-install sandcms user reset-2fa --email editor@example.com
73
154
  ```
74
155
 
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.
156
+ HTTPS origins use secure cookies. CMS writes validate origin, authentication is enforced server-side, and logins have per-email and per-client limits.
76
157
 
77
- ## Client IP behind Dokploy and Cloudflare
158
+ ## Client IP behind a reverse proxy
78
159
 
79
- For a Cloudflare-proxied website routed through Dokploy's reverse proxy, configure the trust boundary first:
160
+ By default the application reads no proxy IP headers, and every visitor appears to come from the proxy. To rate-limit per visitor:
80
161
 
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:
162
+ 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`.
163
+ 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.
164
+ 3. Set both variables to that header and restart:
84
165
 
85
166
  ```dotenv
86
- SANDCMS_TRUSTED_PROXY_HEADER=cf-connecting-ip
87
- ADDRESS_HEADER=cf-connecting-ip
167
+ SANDCMS_TRUSTED_PROXY_HEADER=x-real-ip
168
+ ADDRESS_HEADER=x-real-ip
88
169
  ```
89
170
 
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.
171
+ `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
172
 
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.
173
+ 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
174
 
94
- On staging, temporarily log only the resolved address immediately before a form submission:
175
+ `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
176
 
96
- ```ts
97
- console.info('staging form client address', event.getClientAddress());
98
- ```
177
+ ## Backups and restore
178
+
179
+ Back up the **whole volume** on a schedule, to storage off the server. The site may keep running while the copy is taken.
180
+
181
+ 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.
182
+
183
+ **Restore:**
184
+
185
+ 1. Stop the site and disable automatic restarts.
186
+ 2. Restore the volume from the backup.
187
+ 3. Restore the database from the snapshot inside it, using a one-off container with the same volume:
99
188
 
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.
189
+ ```sh
190
+ bun x --no-install sandcms restore --database /data/sandcms.sqlite --from /data/backups/latest.sqlite
191
+ ```
101
192
 
102
- ## Consistent backups
193
+ 4. Start the site, and check for media rows without files:
194
+
195
+ ```sh
196
+ bun x --no-install sandcms media verify
197
+ ```
198
+
199
+ 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).
200
+
201
+ 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.
202
+
203
+ For an extra copy outside the volume, `sandcms backup` writes a verified snapshot to any path:
103
204
 
104
205
  ```sh
105
- bun x --no-install sandcms backup --database /data/sandcms.sqlite --output /backups/site-2026-09-25.sqlite
206
+ bun x --no-install sandcms backup --database /data/sandcms.sqlite --output /data/backups/manual-2026-11-17.sqlite
106
207
  ```
107
208
 
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.
209
+ 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.
109
210
 
110
- ## Offline restore drill
211
+ ## Rollback
111
212
 
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:
213
+ Use the platform's rollback to return to the previous image. If the bad deploy applied a migration, the old code refuses the newer database; also stop the site and restore the `before-migrate` snapshot that the migration logged:
115
214
 
116
215
  ```sh
117
- bun x --no-install sandcms restore --database /data/sandcms.sqlite --from /backups/site-2026-09-25.sqlite
216
+ bun x --no-install sandcms restore --database /data/sandcms.sqlite --from /data/sandcms.sqlite.before-migrate-<timestamp>-<id>.sqlite
118
217
  ```
119
218
 
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.
219
+ Content edited after the migration is lost.
220
+
221
+ ## Memory and image limits
121
222
 
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.
223
+ 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).
123
224
 
124
- ## Dokploy example and pending host proof
225
+ ## Recommended platforms
125
226
 
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.
227
+ Dokploy and Openship both provide everything in [the requirements](#what-the-host-must-provide): Git deploys, a reverse proxy with Let's Encrypt, named volumes, scheduled volume backups to S3-compatible storage, and rollback.
127
228
 
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.
229
+ - **Dokploy.** Volume names are global on a server, so give each site its own, such as `sandcms-<slug>-data`. Either update order works. Rollback needs a registry configured. Volume backups are full archives. Traefik sets `X-Real-IP`.
230
+ - **Openship.** On a Docker server it deploys by overlap, with no downtime. Supports incremental volume backups and validates a restore before replacing data. Not yet tested by us with SandCMS.
129
231
 
130
232
  ## Transactional email
131
233
 
package/docs/forms.md CHANGED
@@ -11,7 +11,7 @@ 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
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.
17
17
 
package/docs/media.md CHANGED
@@ -1,16 +1,46 @@
1
1
  # Media
2
2
 
3
- The website's Bun process owns SQLite and the durable media job runner. Image processing and private storage run separately. Public images use the website's media route, which supports browser and CDN caching. See [Cloudflare setup and operations](cloudflare.md) for local development, Worker/R2 provisioning, proxy configuration, and copy-paste cache rules.
3
+ Images are stored and processed by the site itself. The website's Bun process owns SQLite, the durable media job runner and the files under the media directory; a child process decodes and encodes images with [sharp](https://sharp.pixelplumbing.com) (libvips). Public images use the website's media route, which supports browser and CDN caching. No external service is involved.
4
4
 
5
- Input is capped at the configured limit (at most 100 MB), SVG at 1 MB, raster dimensions at 100 megapixels, and each encoded output at 20 MB. Encoded variants are bounded and buffered before writing to R2, which requires a known body length. These limits bound local resource use; verify the preset matrix and practical limits against staging before release.
5
+ ## Storage
6
6
 
7
- Raster encoding uses [Cloudflare remote transformations](https://developers.cloudflare.com/images/optimization/transformations/transform-via-workers/) with a 100 MB / 100 MP input ceiling. Dimension inspection also uses remote transformations (`format=json`, `anim=false`), avoiding the Images binding’s input limit. Validated dimensions are saved as R2 custom metadata and reused for variants; older originals without this metadata are inspected remotely on rebuild. The `IMAGES` binding is no longer required. Originals stream through private R2 staging objects for validation before promotion, so the Worker does not buffer a 100 MB upload. Inspection reads staging objects through five-minute signed URLs scoped to the asset and upload attempt; these URLs are never returned to clients. Failed validation removes staging objects. After an interrupted Worker invocation, abandoned `incoming/` objects can be removed with an R2 lifecycle rule restricted to that prefix.
7
+ Media lives in `SANDCMS_MEDIA_DIR`, by default `media/` next to the database (`/data/media` in the starter image), on the same volume:
8
+
9
+ ```text
10
+ media/originals/{id} uploaded files, never modified or served
11
+ media/variants/{id}/{version}/{preset}-{size}.{format} encoded variants, served at /_sandcms/media/{key}
12
+ media/tmp/{id}/… upload chunks and processing scratch files
13
+ ```
14
+
15
+ Every file is written to a temporary path, flushed to disk and renamed before the database records it, so a crash never leaves a half-written original or variant behind a database row. An existing original is never replaced. Width, height and each variant's ETag are stored in SQLite. Temporary files older than a day are removed at start and hourly.
16
+
17
+ Back up the media directory with the rest of the volume; see [backups](deployment.md#backups-and-restore). Media usage and free disk space are shown in the admin and by `sandcms doctor`.
18
+
19
+ ## Formats and limits
20
+
21
+ Accepted input: JPEG, PNG, WebP, AVIF, GIF, TIFF and SVG. Output is WebP, AVIF and JPEG; SVG is served as a sanitized SVG. TIFF originals are never served directly, only their variants. HEIC is not supported.
22
+
23
+ ### Limits
24
+
25
+ | Setting | Default | Range | Applies to |
26
+ | ------------------- | ----------- | ------------------------- | --------------------------------------------------------- |
27
+ | `media.uploadLimit` | 100,000,000 | 1 – 500,000,000 bytes | Each uploaded file |
28
+ | `media.maxPixels` | 100,000,000 | 1,000,000 – 1,000,000,000 | Decoded raster area (width × height, after EXIF) |
29
+ | `media.maxStorage` | none | bytes | Originals plus variants; uploads are refused when reached |
30
+
31
+ SVG is limited to 1 MB. An upload is also refused (507) unless the disk has free space of at least three times its size, plus the size of other uploads in progress, plus 5 GB. Memory use grows with `maxPixels`: the container needs room for one decode at that size, see [memory](deployment.md#memory-and-image-limits).
32
+
33
+ ```yaml
34
+ media:
35
+ uploadLimit: 200000000 # 200 MB
36
+ maxPixels: 150000000 # 150 MP
37
+ maxStorage: 50000000000 # 50 GB
38
+ ```
8
39
 
9
40
  ## Presets
10
41
 
11
42
  ```yaml
12
43
  media:
13
- workerUrl: https://your-project-media.example.workers.dev
14
44
  defaultFileBlueprint: image
15
45
  uploadLimit: 100000000
16
46
  presets:
@@ -22,7 +52,7 @@ media:
22
52
  formats: { webp: 85 }
23
53
  ```
24
54
 
25
- Sizes are longest-side pixels. Outputs preserve aspect ratio and do not upscale unless an optional `aspectRatio` (width divided by height, 0.01–100) requests a crop. Cropped outputs also never upscale; small originals produce smaller variants with the requested ratio, subject to pixel rounding. Formats are WebP, AVIF, and JPEG, each with quality 1–100. The default upload cap and configured maximum are 100 MB (100,000,000 bytes). Raster input is additionally limited to 100 megapixels. SVG is limited to 1 MB and is sanitized using a strict XML parser and allowlists; scripts, foreign content, external references, event handlers, and styles are removed. Document types/entities are rejected. The sanitized derivative receives restrictive CSP and nosniff headers, and is not resized or encoded as WebP.
55
+ Sizes are longest-side pixels. Outputs preserve aspect ratio and do not upscale unless an optional `aspectRatio` (width divided by height, 0.01–100) requests a crop. Cropped outputs also never upscale; small originals produce smaller variants with the requested ratio, subject to pixel rounding. Formats are WebP, AVIF, and JPEG, each with quality 1–100. SVG is sanitized using a strict XML parser and allowlists; scripts, foreign content, external references, event handlers, and styles are removed. Document types/entities are rejected. The sanitized derivative receives restrictive CSP and nosniff headers, and is not resized or encoded as WebP.
26
56
 
27
57
  ## Focal points
28
58
 
@@ -45,21 +75,23 @@ card:
45
75
  formats: { webp: 80, avif: 65 }
46
76
  ```
47
77
 
48
- Crops use [Cloudflare gravity coordinates](https://developers.cloudflare.com/images/optimization/features/#gravity--g). Presets without `aspectRatio` preserve the full image. Focus changes automatically queue new immutable variant keys when cropping is configured; current variants stay available until the complete new set is ready. Unrelated metadata edits do not rebuild images. The reserved `sandcms-preview` preset supplies an uncropped WebP for the picker on raster files with a focus field.
78
+ Crops resize the image to cover the requested ratio, then cut out the region centred as close to the focal point as the edges allow. Presets without `aspectRatio` preserve the full image. Focus changes automatically queue new immutable variant keys when cropping is configured; current variants stay available until the complete new set is ready. Unrelated metadata edits do not rebuild images. The reserved `sandcms-preview` preset supplies an uncropped WebP for the picker on raster files with a focus field.
49
79
 
50
- Existing project-owned blueprints/configuration are preserved during upgrades: add the field and ratio explicitly, deploy the current Worker first with `sandcms worker update`, then deploy the website and run `sandcms media rebuild` to prepare existing files and previews. The protocol-6 Worker accepts older protocol-3/4/5 website requests; new website processes reject older Workers. No database migration is required.
80
+ Existing project-owned blueprints/configuration are preserved during upgrades: add the field and ratio explicitly, then run `sandcms media rebuild` to prepare existing files and previews. No database migration is required.
51
81
 
52
82
  ## Privacy and publication
53
83
 
54
- Originals remain in private R2 storage. Only the processor can mint a five-minute HMAC-signed source URL for one raster asset; it is never included in CMS responses or public media metadata. A media asset becomes publicly accessible only when at least one **published snapshot** references it through a media field, media list, or gallery (including nested fields). Uploading to the library, saving a draft, and preparing variants grant no public access. Sharing an asset with published content makes its active variants public even if it is also used in drafts.
84
+ Originals stay private on the volume; no route serves them. A media asset becomes publicly accessible only when at least one **published snapshot** references it through a media field, media list, or gallery (including nested fields). Uploading to the library, saving a draft, and preparing variants grant no public access. Sharing an asset with published content makes its active variants public even if it is also used in drafts.
85
+
86
+ `cmsHandle` serves public variants at `/_sandcms/media/{key}`. It checks the current published references and the active variant set, then streams the file from disk. Removing the last published reference—by unpublishing, deleting content, or publishing a replacement—revokes access at the origin. Cached copies can remain available. Draft edits leave the existing published snapshot and its images live. Requests reaching the origin cannot access historical variant sets after replacement; previously cached versions can remain available.
55
87
 
56
- `cmsHandle` serves public variants at `/_sandcms/media/{key}`. It checks the current published references and active variant set before fetching bytes from the Worker's authenticated `/internal/media/{key}` endpoint. Direct Worker `/media/` URLs no longer work. Removing the last published reference—by unpublishing, deleting content, or publishing a replacement—revokes access at the origin. Cached copies can remain available. Draft edits leave the existing published snapshot and its images live. Requests reaching the origin cannot access historical variant sets after replacement; previously cached versions can remain available.
88
+ Editor previews use `/api/cms/media/{key}` and require an active admin/editor session with no pending password change. Query-based transformations are rejected; only named variants exist.
57
89
 
58
- Editor previews use `/api/cms/media/{key}` and require an active admin/editor session with no pending password change. Originals have no editor or public delivery endpoint. Query-based transformations are rejected. Processing uses remote transformations against the Worker’s `/internal/source/{id}` endpoint. Every source request verifies its asset-scoped signature and expiry, then streams the original with `private, no-store`. Unsigned requests, changed signatures, expired URLs, and non-GET methods receive 404. The source handler never performs transformations, avoiding fetch loops. Treat signed URLs as credentials: keep them out of application logs and client responses. Cloudflare caches transformed results internally by source URL; expiry is checked at the source and does not purge Cloudflare’s transformation cache. Signed source URLs must remain secret even after expiry. This processing cache is separate from published website delivery.
90
+ Variant responses carry `Content-Type`, `Content-Length`, a strong `ETag`, `Content-Security-Policy: default-src 'none'; style-src 'none'; sandbox`, `Cross-Origin-Resource-Policy: cross-origin` and `X-Content-Type-Options: nosniff`. A file missing on disk returns 404.
59
91
 
60
- Successful public responses use `Cache-Control: public, max-age=86400, s-maxage=2592000`: one day of browser freshness and 30 days in shared caches. Public responses preserve ETags and support `If-None-Match` revalidation for GET and HEAD, including weak validators, lists, and `*`. The CMS checks current access before and after the Worker request, including before returning a cacheable `304`. Cache hits bypass these checks. Cached availability after unpublishing, deletion, or variant replacement is intentional; immediate revocation is not promised. Cache retention is not guaranteed, so a cold location can return 404 while a warm cache still serves the image.
92
+ Successful public responses use `Cache-Control: public, max-age=86400, s-maxage=2592000`: one day of browser freshness and 30 days in shared caches. Public responses preserve ETags and support `If-None-Match` revalidation for GET and HEAD, including weak validators, lists, and `*`. The CMS checks current access before returning a body or a cacheable `304`. Cache hits bypass these checks. Cached availability after unpublishing, deletion, or variant replacement is intentional; immediate revocation is not promised. Cache retention is not guaranteed, so a cold location can return 404 while a warm cache still serves the image.
61
93
 
62
- Editor previews and all delivery errors use `Cache-Control: private, no-store` and omit ETags. Preview responses vary by cookie; public responses are independent of sessions. Never cache private previews. Already downloaded images cannot be recalled. See [Cloudflare cache setup, verification, and removal](cloudflare.md#website-proxy-and-public-image-caching).
94
+ Editor previews and all delivery errors use `Cache-Control: private, no-store` and omit ETags. Preview responses vary by cookie; public responses are independent of sessions. Never cache private previews. Already downloaded images cannot be recalled. For CDN cache rules in front of the site, see [optional CDN caching](cloudflare.md#optional-cdn-caching).
63
95
 
64
96
  Publication does not move files or require cache registration. Uploads get distinct asset IDs and preset changes produce distinct variant URLs. Rebuilds reuse existing completed variants rather than overwriting them. Do not replace bytes under an existing URL: processing changes that alter output must introduce a new variant version. The public policy deliberately does not advertise `immutable`.
65
97
 
@@ -71,8 +103,7 @@ Import the Svelte component from the package root and pass the asset returned by
71
103
  `cms.media.publicAsset(id)`:
72
104
 
73
105
  Each variant includes a `url` using the CMS public or authenticated preview route.
74
- The component needs no URL configuration. `SANDCMS_WORKER_URL` (falling back to
75
- `media.workerUrl` in YAML) configures only the server's private Worker connection.
106
+ The component needs no URL configuration.
76
107
 
77
108
  ```svelte
78
109
  <script lang="ts">
@@ -111,24 +142,57 @@ The component emits a `<picture>` with AVIF, WebP, then JPEG sources when availa
111
142
  and adds no styling or admin dependencies. Consumers control layout with their own CSS.
112
143
  `imageSources(asset, preset)` remains available for custom markup.
113
144
 
114
- ## Processing and rebuild
145
+ ## Uploads
115
146
 
116
- The authenticated CMS initializes a metadata-only upload session and returns a 15-minute S3 presigned PUT URL for a private `incoming/<asset>/<attempt>` object. The browser sends the file directly to R2, then calls the idempotent completion endpoint. A durable job verifies the actual object size and MIME type, validates a separate private snapshot (or sanitizes SVG), and conditionally creates the original before queuing variants. Reusing the PUT URL cannot overwrite an accepted original. New uploads never enter SQLite as BLOBs. Existing BLOB uploads from older releases continue through the legacy runner and are removed after successful transfer. Interrupted browser transfers require the file to be sent again. Unfinished sessions expire after 15 minutes; the runner deletes their staging objects and marks the asset failed. Finalization failures retain staging for retries. Configure a one-day `incoming/` lifecycle rule to remove abandoned objects, including objects recreated using an unexpired PUT URL. Completion retries do not transfer the file again. Variant jobs for the same image are claimed together and encoded in one Worker request, up to 16 per request and four concurrently inside the Worker. Each variant reports success or failure separately, so only failed variants retry. The website runs up to four images in parallel and continues immediately while work remains. Jobs have durable attempts, bounded leases, retry delays, and failure state. Restarting the website resumes pending/expired jobs. The media library shows processing/ready/failed and permits retries. An asset's old active set remains available throughout a rebuild.
147
+ Files upload to the site itself in 8 MB chunks, so no request is large or long enough to hit a reverse proxy's default limits:
148
+
149
+ 1. The admin (or an [API client](api.md#media-uploads)) asks to start an upload with the file's name, type and size. The CMS checks the blueprint's accepted types, `uploadLimit`, disk space and quota, and returns a chunk URL with a signed upload ticket.
150
+ 2. Chunks are sent one at a time with `PUT {url}?index=N`. Each chunk is stored on disk as it streams in; re-sending a chunk replaces it. A `GET {url}` lists the chunks already stored, so an interrupted upload resumes where it stopped, also after a site restart.
151
+ 3. Completion assembles the chunks and checks the total size. A background job then validates the file and stores the original: SVGs go through the sanitizer; raster files must decode as the declared type within `maxPixels`. Variant jobs are queued after that.
152
+
153
+ The ticket is bound to the asset, the upload attempt, the declared type and size, and the user who started it (their session or any of their API keys may send chunks). An upload with no chunk for 15 minutes expires; the asset is marked failed and its chunks are removed. Upload bytes never enter SQLite. Existing BLOB uploads from earlier releases still finish through the legacy runner.
154
+
155
+ `cms.media.upload(file)` stores a file from server code through the same validation, without HTTP.
156
+
157
+ ## Processing
158
+
159
+ Images are processed one at a time per site by a child process running sharp, so a huge decode cannot take down the web server. Each batch decodes the original once, auto-rotates it from EXIF orientation, converts it to sRGB, and encodes every requested variant from that master. Variants never upscale. Each finished variant is written and recorded before the next starts, so a retry skips finished variants. Jobs have durable attempts, leases, retry delays and failure state; restarting the website resumes them. If the child exits, for example when the container's memory limit is reached, the batch fails at once and each unfinished variant counts as a failed attempt; a variant that fails four times marks the asset failed. The media library shows processing/ready/failed and permits retries. An asset's old active set stays available throughout a rebuild.
160
+
161
+ The child runs at low CPU priority (`nice 10`), so page requests always win over background processing within a site. It uses one libvips thread by default. Set `SANDCMS_MEDIA_THREADS` (for example `2`–`4`) to let a site finish large batches sooner when the server is idle; Docker's default CPU weights still split CPU evenly between busy containers, so leave the host's CPU limit unset or generous rather than low. Processing stays one image at a time, so memory use does not grow with the thread count beyond libvips' per-thread buffers.
162
+
163
+ Only the JPEG, PNG, WebP, AVIF, GIF and TIFF decoders are enabled, and the decoded format must match the declared type, so an SVG named `.png` is rejected rather than rasterized.
117
164
 
118
165
  ```sh
119
166
  bun x --no-install sandcms media rebuild
120
167
  ```
121
168
 
122
- Rebuild compares the current preset hash, schedules missing sets, shows progress, and exits nonzero for failures. It does not delete old variants. Ordinary image reuse does not enqueue transformations. Configure a later reviewed cleanup operation if you need to remove unreferenced historical variant keys.
169
+ Rebuild compares the current preset hash, schedules missing sets, shows progress, and exits nonzero for failures. It does not delete old variants. `media rebuild --force` also re-encodes the active variants of every ready raster image under the same version and URLs; use it after an [R2 import](cloudflare.md) to replace variants encoded by Cloudflare. Rebuilds wait while the website's processor is busy, and never start the website's background tasks. Configure a later reviewed cleanup operation if you need to remove unreferenced historical variant keys.
170
+
171
+ ### Changes from Cloudflare processing (0.7.0)
172
+
173
+ - Animated GIF and WebP inputs are flattened to their first frame.
174
+ - Metadata is stripped from variants except the EXIF copyright and artist fields.
175
+ - HEIC input is not supported.
176
+ - Inputs are no longer capped at 100 MB / 100 MP or a 20 MB output; `uploadLimit` and `maxPixels` set the limits.
177
+ - Imported variants keep their Cloudflare encoding until `media rebuild --force`; new variants are encoded by sharp under the same preset version.
178
+
179
+ ### Checking and repairing files
180
+
181
+ ```sh
182
+ bun x --no-install sandcms media verify
183
+ bun x --no-install sandcms media verify --repair
184
+ ```
185
+
186
+ `media verify` lists media rows whose original or active variants are missing on disk, for example after restoring a database snapshot that is newer than the media in a backup, and exits nonzero when any are missing. `--repair` queues missing variants to be rendered again when the original exists, and marks an image failed with "Original file is missing. Upload this image again." when it does not. Uploads in progress are not checked.
123
187
 
124
- Editable asset fields come from file blueprints. If a blueprint declares a photographer relation, it references that field’s configured collection. Publish a photographer's rename to update public credits; deletion clears the credit. Deletion displays known draft/published usages and allows confirmation without additional permission escalation.
188
+ ## Deletion
125
189
 
126
- Deletion clears draft/published references and revokes active variants immediately, then records cleanup in the durable `media_deletions` queue. Assets remain `deleting` until storage cleanup succeeds. Cleanup waits for active uploads and transformations to finish or their leases to expire; processing cannot restore the asset or schedule more work. Storage failures retry automatically, including after a website restart. The library polls pending deletions and excludes them from image pickers.
190
+ Editable asset fields come from file blueprints. If a blueprint declares a photographer relation, it references that field's configured collection. Publish a photographer's rename to update public credits; deletion clears the credit. Deletion displays known draft/published usages and allows confirmation without additional permission escalation.
127
191
 
128
- The Worker keeps a small permanent `deleted/<asset>` marker to reject late requests and remove writes that raced with deletion. Keep this prefix private and do not expire its markers. An unexpired presigned PUT can still recreate an incoming staging object, so retain the one-day `incoming/` lifecycle rule; that object cannot be promoted to an original. Deploy the updated Worker before the website, as described in [upgrades](upgrades.md#durable-media-deletion).
192
+ Deletion clears draft/published references and revokes active variants immediately, then records cleanup in the durable `media_deletions` queue. Assets remain `deleting` until their files are removed. Cleanup waits for active uploads and processing to finish or their leases to expire; processing cannot restore the asset or schedule more work, and a file written after the deletion is removed again. Failures retry automatically, including after a website restart. The library polls pending deletions and excludes them from image pickers.
129
193
 
130
194
  ## Bulk uploads and galleries
131
195
 
132
- The library and multi-image pickers accept multiple files in one selection. Files upload sequentially directly to private R2 staging, in selection order. The CMS receives only metadata and completion requests. Progress counts completed attempts; errors name each failed file, and later files still upload. Successful uploads remain available when another file fails. The browser retains failed files for transfer retries; use the library's processing retry for files already accepted by the server.
196
+ The library and multi-image pickers accept multiple files in one selection. Files upload sequentially in selection order, each in chunks with a progress bar; a failed chunk is retried before the file is reported as failed. Errors name each failed file, and later files still upload. Successful uploads remain available when another file fails. Use the library's processing retry for files already accepted by the server.
133
197
 
134
198
  Use a `gallery` field for ordered images. Its file blueprint defines available metadata; `overrides` explicitly enables per-placement editing of selected fields. A gallery without overrides displays images and ordering controls only. See [gallery configuration](content.md#galleries-and-project-specific-metadata). Both galleries and `media-list` fields support drag handles and arrow controls for ordering.