sandcms 0.7.0 → 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 (111) hide show
  1. package/README.md +4 -4
  2. package/dist/admin/Admin.svelte +7 -5
  3. package/dist/admin/AssetAttachment.svelte +8 -3
  4. package/dist/admin/AssetAttachment.svelte.d.ts +3 -0
  5. package/dist/admin/Editor.svelte +5 -9
  6. package/dist/admin/Fields.svelte +2 -1
  7. package/dist/admin/Gallery.svelte +221 -76
  8. package/dist/admin/Inbox.svelte +3 -2
  9. package/dist/admin/MediaPicker.svelte +36 -20
  10. package/dist/admin/Navigation.svelte +13 -2
  11. package/dist/admin/Pages.svelte +195 -0
  12. package/dist/admin/Pages.svelte.d.ts +7 -0
  13. package/dist/admin/Shell.svelte +27 -5
  14. package/dist/admin/SortableList.svelte +82 -61
  15. package/dist/admin/SortableList.svelte.d.ts +3 -1
  16. package/dist/admin/Users.svelte +8 -3
  17. package/dist/admin/generated/admin.css +300 -20
  18. package/dist/admin/navigation.d.ts +9 -0
  19. package/dist/admin/navigation.js +20 -1
  20. package/dist/admin/types.d.ts +1 -0
  21. package/dist/blueprints/labels.d.ts +6 -0
  22. package/dist/blueprints/labels.js +14 -0
  23. package/dist/blueprints/load.js +11 -2
  24. package/dist/blueprints/types.d.ts +2 -2
  25. package/dist/cli/admin.d.ts +39 -0
  26. package/dist/cli/admin.js +95 -0
  27. package/dist/cli/backup.js +4 -4
  28. package/dist/cli/doctor.d.ts +8 -1
  29. package/dist/cli/doctor.js +19 -9
  30. package/dist/cli/email-test.d.ts +3 -0
  31. package/dist/cli/email-test.js +20 -0
  32. package/dist/cli/files.js +2 -1
  33. package/dist/cli/index.js +373 -135
  34. package/dist/cli/rebaseline.d.ts +10 -0
  35. package/dist/cli/rebaseline.js +117 -0
  36. package/dist/cli/upgrade.js +17 -9
  37. package/dist/env.d.ts +0 -8
  38. package/dist/env.js +0 -8
  39. package/dist/notification-fields.js +2 -1
  40. package/dist/server/admin-load.d.ts +72 -0
  41. package/dist/server/admin-load.js +20 -0
  42. package/dist/server/api-keys.d.ts +96 -0
  43. package/dist/server/api-keys.js +115 -0
  44. package/dist/server/api.js +16 -61
  45. package/dist/server/cms.d.ts +0 -5
  46. package/dist/server/cms.js +4 -3
  47. package/dist/server/db/auto-migrate.d.ts +0 -4
  48. package/dist/server/db/auto-migrate.js +12 -3
  49. package/dist/server/db/legacy.d.ts +13 -0
  50. package/dist/server/db/legacy.js +60 -0
  51. package/dist/server/db/migration-data.js +2 -38
  52. package/dist/server/db/migrations/{0000_foundation.sql → 0000_baseline.sql} +120 -4
  53. package/dist/server/db/migrations/meta/0000_snapshot.json +578 -3
  54. package/dist/server/db/migrations/meta/_journal.json +2 -65
  55. package/dist/server/db/schema.js +8 -6
  56. package/dist/server/db/store.d.ts +25 -2
  57. package/dist/server/db/store.js +90 -26
  58. package/dist/server/forms.js +2 -1
  59. package/dist/server/media/runner.d.ts +1 -1
  60. package/dist/server/media/runner.js +1 -1
  61. package/dist/server/media/service.d.ts +0 -4
  62. package/dist/server/media/service.js +0 -2
  63. package/dist/server/media/verify.d.ts +28 -0
  64. package/dist/server/media/verify.js +94 -2
  65. package/dist/server/platform/snapshots.js +3 -3
  66. package/docs/acceptance.md +2 -2
  67. package/docs/api.md +15 -1
  68. package/docs/cloudflare.md +9 -41
  69. package/docs/content.md +18 -3
  70. package/docs/deployment.md +97 -34
  71. package/docs/email.md +6 -0
  72. package/docs/forms.md +1 -1
  73. package/docs/media.md +10 -1
  74. package/docs/package.md +4 -4
  75. package/docs/releases.md +21 -1
  76. package/docs/upgrades.md +41 -7
  77. package/package.json +4 -10
  78. package/templates/Dockerfile +6 -2
  79. package/templates/integration.ts +10 -5
  80. package/templates/openship.json +9 -0
  81. package/templates/sandcms/config.yaml +1 -0
  82. package/dist/server/db/migrations/0001_independent_password_resets.sql +0 -3
  83. package/dist/server/db/migrations/0002_email_failure_reason.sql +0 -1
  84. package/dist/server/db/migrations/0003_direct_r2_uploads.sql +0 -10
  85. package/dist/server/db/migrations/0004_agent_api_keys.sql +0 -38
  86. package/dist/server/db/migrations/0005_api_retention_and_pagination.sql +0 -3
  87. package/dist/server/db/migrations/0006_durable_media_deletion.sql +0 -7
  88. package/dist/server/db/migrations/0007_content_and_job_indexes.sql +0 -2
  89. package/dist/server/db/migrations/0008_search_text_cache.sql +0 -45
  90. package/dist/server/db/migrations/0009_local_media.sql +0 -9
  91. package/dist/server/db/migrations/meta/0001_snapshot.json +0 -1197
  92. package/dist/server/db/migrations/meta/0002_snapshot.json +0 -1204
  93. package/dist/server/db/migrations/meta/0003_snapshot.json +0 -1281
  94. package/dist/server/db/migrations/meta/0004_snapshot.json +0 -1546
  95. package/dist/server/db/migrations/meta/0005_snapshot.json +0 -1572
  96. package/dist/server/db/migrations/meta/0006_snapshot.json +0 -1627
  97. package/dist/server/db/migrations/meta/0007_snapshot.json +0 -1643
  98. package/dist/server/db/migrations/meta/0008_snapshot.json +0 -1711
  99. package/dist/server/db/migrations/meta/0009_snapshot.json +0 -1763
  100. package/dist/server/media/import-r2.d.ts +0 -56
  101. package/dist/server/media/import-r2.js +0 -342
  102. package/dist/worker/index.d.ts +0 -10
  103. package/dist/worker/index.js +0 -460
  104. package/dist/worker/local.d.ts +0 -5
  105. package/dist/worker/local.js +0 -57
  106. package/dist/worker/source.d.ts +0 -2
  107. package/dist/worker/source.js +0 -31
  108. package/dist/worker/svg.d.ts +0 -1
  109. package/dist/worker/svg.js +0 -2
  110. package/dist/worker/uploads.d.ts +0 -22
  111. package/dist/worker/uploads.js +0 -48
@@ -1,51 +1,19 @@
1
- # Cloudflare: legacy import and optional CDN
1
+ # Cloudflare: retired Worker and optional CDN
2
2
 
3
- From 0.7.0, SandCMS stores and processes images on the site's own volume and no longer uses a Cloudflare Worker or R2. This guide covers sites created before 0.7.0: importing their R2 media once, then removing the Worker and bucket. The last section describes optional CDN caching in front of any site.
3
+ From 0.7.0, SandCMS stores and processes images on the site's own volume and no longer uses a Cloudflare Worker or R2. 0.8.0 removes the remaining Worker support: `sandcms media import-r2`, the `sandcms/worker` and `sandcms/worker/local` exports, `createCMS({ workerUrl, workerToken })` and the `SANDCMS_WORKER_URL` / `SANDCMS_WORKER_TOKEN` variables. `media.workerUrl` in `sandcms/config.yaml` is still accepted and ignored.
4
4
 
5
- The Worker source, the `sandcms/worker` and `sandcms/worker/local` exports, `createCMS({ workerUrl, workerToken })` and the `SANDCMS_WORKER_URL` / `SANDCMS_WORKER_TOKEN` variables are deprecated and kept through 0.7.x so the old Worker stays deployable until the import is verified. `sandcms worker update` and Cloudflare setup have been removed.
5
+ ## Sites still on Cloudflare media
6
6
 
7
- ## Import R2 media
7
+ A site whose media is still in R2 imports it with the 0.7.x package before upgrading to 0.8.0. Follow the [0.7.0 upgrade checklist](upgrades.md#070-upgrade-checklist) and the import guide that ships with that package (`docs/cloudflare.md` in `sandcms@0.7.x`), run `sandcms media import-r2` until it reports no failures, then `sandcms media verify`. Only then continue with the [0.8.0 checklist](upgrades.md#080-upgrade-checklist).
8
8
 
9
- Run this once per site, in a maintenance window, while the old protocol-6 Worker (0.6.2 or later) is still deployed. Follow the [0.7.0 upgrade checklist](upgrades.md#070-upgrade-checklist) up to the deploy first: the site runs 0.7.0, migration `0009_local_media` is applied, and `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` are still set. The volume needs free space of at least three times the site's current media.
10
-
11
- Images are unavailable on the site until they are imported: a variant that is not on disk yet returns 404. Then run, in the site's container (or a one-off container with the same volume and environment):
12
-
13
- ```sh
14
- bun x --no-install sandcms media import-r2
15
- ```
16
-
17
- | Option | Default |
18
- | ---------------------- | --------------------------------------------------------------------------- |
19
- | `--worker-url URL` | `SANDCMS_WORKER_URL`, then `media.workerUrl` in `sandcms/config.yaml` |
20
- | `--worker-token-stdin` | Reads the token from standard input instead of `SANDCMS_WORKER_TOKEN` |
21
- | `--database PATH` | `SANDCMS_DATABASE`; media goes to `SANDCMS_MEDIA_DIR` or `media/` beside it |
22
-
23
- The token is never accepted as an argument. The import:
24
-
25
- - refuses to start while uploads are in progress (`upload_sessions` rows) or legacy BLOB uploads are queued (`uploads` rows). Let them finish or expire first;
26
- - checks the Worker's token and protocol, then holds the media processor lease for the whole run, so the website renders nothing meanwhile. If the website is processing, it waits up to two minutes;
27
- - downloads each raster original through the Worker's `/internal/source/{id}` route, using short-lived signed URLs minted locally from the token. The Worker checks them against its own hostname, so use its deployed URL, not a proxy or redirect;
28
- - uses the sanitized `svg-1.svg` variant as both original and variant for SVGs, which the source route does not serve;
29
- - downloads every ready variant through `/internal/media/{key}`, including older versions that are no longer active, since caches may still hold their URLs;
30
- - skips assets being deleted, and reports assets with neither an original nor ready variants in R2 (for example expired uploads) as skipped;
31
- - fills each image's width and height and each variant's ETag, and keeps asset IDs, variant keys and preset versions, so public URLs and published content are unchanged;
32
- - runs four assets at a time and retries network errors and Worker 5xx responses with backoff;
33
- - ends by verifying that every original and ready variant exists on disk with the expected size.
34
-
35
- It prints one line per asset, then a summary, and exits nonzero if any file failed. The run is resumable: files already imported are kept and not downloaded again, so fix the cause and run the same command again until it succeeds.
36
-
37
- Then check the site and run:
38
-
39
- ```sh
40
- bun x --no-install sandcms media verify
41
- ```
42
-
43
- Imported variants keep Cloudflare's encoding. New variants are encoded by sharp under the same preset version, so an image's sizes may differ slightly in quality. To re-encode everything with sharp, run `sandcms media rebuild --force` (URLs stay the same; CDN and browser caches keep old copies until they expire).
9
+ Imported variants keep Cloudflare's encoding. To re-encode everything with sharp, run `sandcms media rebuild --force` (URLs stay the same; CDN and browser caches keep old copies until they expire).
44
10
 
45
11
  ## Remove the Worker and bucket
46
12
 
47
- 1. Remove `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` from the site's environment and redeploy. `media.workerUrl` in `sandcms/config.yaml` is ignored and can be removed.
48
- 2. Delete the project-owned `sandcms/worker/` directory and the `worker:dev` script, if present. `sandcms setup` and `sandcms upgrade` leave these files alone and report them as removable.
13
+ Once the import is verified:
14
+
15
+ 1. Remove `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` from the site's environment and redeploy. Nothing reads them from 0.8.0. `media.workerUrl` in `sandcms/config.yaml` is ignored and can be removed.
16
+ 2. Delete the project-owned `sandcms/worker/` directory and the `worker:dev` script, if present. They import the removed `sandcms/worker` exports, so they no longer type-check or deploy with 0.8.0. `sandcms setup` and `sandcms upgrade` leave these files alone and report them as removable.
49
17
  3. Wait for a volume backup, restore it somewhere and confirm it contains the originals (`media/originals/`) and a database snapshot.
50
18
  4. Delete the Worker (`bun x wrangler delete --config sandcms/worker/wrangler.jsonc`, before removing that file, or from the Cloudflare dashboard), the R2 bucket, its bucket-scoped R2 API token and its CORS and lifecycle rules.
51
19
 
package/docs/content.md CHANGED
@@ -129,21 +129,25 @@ Local settings override inherited settings. Nested mappings merge by key, retain
129
129
 
130
130
  The starter and demo project blueprint use `fields/seo`. Existing inline YAML continues to work. Reusing a definition keeps the field key and stored payload shape unchanged; restart the application after YAML edits. Upgrades preserve project-owned YAML, so adopting shared definitions in an existing site is an explicit configuration edit.
131
131
 
132
+ ## Pages screen
133
+
134
+ The sidebar shows one **Pages** link instead of a link for every page. It opens `/admin/pages`, a table of every page blueprint, including pages with their own sidebar group or link. Each row shows the page's label and icon, the public path from its `preview` template, its status (Draft, Published or Changes not live) and when it was last updated. Search filters by label, ID, path or description, and the column headings sort the table. The row menu edits, previews or views the page and publishes or unpublishes it. Listing pages does not create drafts; a page's draft is created when it is first opened. While editing a page from the Pages screen, the breadcrumb leads back to it.
135
+
132
136
  ## Sidebar groups
133
137
 
134
- Pages appear under a collapsible **Pages** group by default. Other blueprint kinds stay at the top level. Set `navigation.group` on a content blueprint to choose a group:
138
+ Pages in the default **Pages** group (no `navigation`, or `navigation: { group: Pages }`) are listed on the [Pages screen](#pages-screen) instead of the sidebar. Other blueprint kinds stay at the top level. Set `navigation.group` on a content blueprint to choose a group:
135
139
 
136
140
  ```yaml
137
141
  id: about
138
142
  label: About
139
143
  kind: page
140
144
  navigation:
141
- group: Pages
145
+ group: Company
142
146
  fields:
143
147
  title: { type: text }
144
148
  ```
145
149
 
146
- Use the same group label on several blueprints to group them together, or `navigation: { group: false }` to keep an item at the top level. Labels must be nonempty strings. Groups remain within the Content (pages/collections) or Workspace (forms/site settings) section. Groups follow the existing kind and blueprint order, appearing at their first member's position. File blueprints do not participate in navigation.
150
+ Use the same group label on several blueprints to group them together, or `navigation: { group: false }` to keep an item at the top level. Labels must be nonempty strings. Groups remain within the Content (pages/collections) or Workspace (forms/site settings) section. Groups follow the existing kind and blueprint order, appearing at their first member's position. A collection placed in a group named **Pages** stays in a collapsible group; only pages move to the Pages screen. File blueprints do not participate in navigation.
147
151
 
148
152
  Groups start collapsed and automatically open when navigating to a member, including a direct link to an editor. You can toggle them with the mouse or keyboard; choices last while the admin shell remains mounted. This only changes the admin sidebar: public URLs, content relationships, blueprint IDs, and stored data stay the same. Restart the application after editing YAML.
149
153
 
@@ -153,6 +157,17 @@ Every content blueprint kind accepts an optional `icon` using a lowercase, hyphe
153
157
 
154
158
  Omitting `icon` keeps the defaults: `file-text` for pages, `folder` for collections, `inbox` for forms, and `settings` for site settings. Restart the application after changing a blueprint. Icons are resolved on the server, and only the selected icon data is included in admin pages.
155
159
 
160
+ ## Site logo
161
+
162
+ The admin sidebar shows the site's favicon next to the project `name` by default, read from the page's `<link rel="icon">`. Set `logo` in `sandcms/config.yaml` to use another image:
163
+
164
+ ```yaml
165
+ name: Sandquist Produktion
166
+ logo: /logo.svg # A file in static/, or an http(s) URL
167
+ ```
168
+
169
+ Paths must start with `/`; `logo: false` shows the first letter of `name` instead. The initial is also shown when the site has no favicon or the image fails to load. Restart the application after changing `config.yaml`.
170
+
156
171
  ## Public routes
157
172
 
158
173
  Routes and components remain developer-owned. Use the installed site's `getCMS` wrapper:
@@ -11,7 +11,7 @@ A SandCMS site is one long-lived Bun container with one persistent volume. The p
11
11
  backups/latest.sqlite backups/previous.sqlite
12
12
  ```
13
13
 
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).
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).
15
15
 
16
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.
17
17
 
@@ -21,9 +21,9 @@ The repository pins Bun 1.4.4, SvelteKit 3.2.0, Svelte 5.57.3, and official `@sv
21
21
  | ------------- | ------------------------------------------------------------------------------------------------------------------- |
22
22
  | Container | Built from the site's `Dockerfile` (or Railpack), one replica |
23
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 |
24
+ | Deploys | Overlap: start the new container, switch traffic once it is healthy, then stop the old one. See [deploys](#deploys) |
25
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` |
26
+ | Health check | Gates the traffic switch: the image's `HEALTHCHECK`, or `GET /_sandcms/health` failing on any 5xx |
27
27
  | Memory | A container memory limit that covers one image decode at `media.maxPixels` (see [memory](#memory-and-image-limits)) |
28
28
  | Backups | A scheduled copy of the whole volume to off-server storage |
29
29
 
@@ -45,25 +45,26 @@ ADDRESS_HEADER=x-real-ip
45
45
  # SANDCMS_BOOTSTRAP_EMAIL=you@example.com # first start only
46
46
  ```
47
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
-
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.
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).
67
68
 
68
69
  ### Environment validation
69
70
 
@@ -81,7 +82,7 @@ With a health check configured, a deployment with a broken environment never goe
81
82
 
82
83
  ## Server build configuration
83
84
 
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
+ 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.
85
86
 
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`.
87
88
 
@@ -104,13 +105,18 @@ ssr: {
104
105
 
105
106
  ## Health check
106
107
 
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
+ `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.
108
109
 
109
- ## Deploys and volume checks
110
+ ## Deploys
110
111
 
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.
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).
112
113
 
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.
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
114
120
 
115
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:
116
122
 
@@ -137,11 +143,11 @@ bun x --no-install sandcms user bootstrap --database /data/sandcms.sqlite --emai
137
143
 
138
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.
139
145
 
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.
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.
141
147
 
142
148
  ### Automatic migration on start
143
149
 
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.
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.
145
151
 
146
152
  ### Users
147
153
 
@@ -153,6 +159,22 @@ bun x --no-install sandcms user reset-password --email editor@example.com
153
159
  bun x --no-install sandcms user reset-2fa --email editor@example.com
154
160
  ```
155
161
 
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).
177
+
156
178
  HTTPS origins use secure cookies. CMS writes validate origin, authentication is enforced server-side, and logins have per-email and per-client limits.
157
179
 
158
180
  ## Client IP behind a reverse proxy
@@ -210,7 +232,9 @@ It uses SQLite `VACUUM INTO`, validates integrity, foreign keys and migration hi
210
232
 
211
233
  ## Rollback
212
234
 
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:
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.
236
+
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:
214
238
 
215
239
  ```sh
216
240
  bun x --no-install sandcms restore --database /data/sandcms.sqlite --from /data/sandcms.sqlite.before-migrate-<timestamp>-<id>.sqlite
@@ -222,12 +246,51 @@ Content edited after the migration is lost.
222
246
 
223
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).
224
248
 
225
- ## Recommended platforms
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.
278
+
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`.
284
+
285
+ ### Coolify
226
286
 
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.
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.
228
288
 
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.
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).
231
294
 
232
295
  ## Transactional email
233
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
@@ -13,7 +13,7 @@ The helper accepts plain JSON objects up to 64 KB, rejects cycles, non-finite nu
13
13
 
14
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
 
package/docs/media.md CHANGED
@@ -166,7 +166,7 @@ Only the JPEG, PNG, WebP, AVIF, GIF and TIFF decoders are enabled, and the decod
166
166
  bun x --no-install sandcms media rebuild
167
167
  ```
168
168
 
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.
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 the 0.7.x [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
170
 
171
171
  ### Changes from Cloudflare processing (0.7.0)
172
172
 
@@ -185,6 +185,15 @@ bun x --no-install sandcms media verify --repair
185
185
 
186
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.
187
187
 
188
+ ### Freeing unused files
189
+
190
+ ```sh
191
+ bun x --no-install sandcms media prune
192
+ bun x --no-install sandcms media prune --delete
193
+ ```
194
+
195
+ `media prune` lists originals and variant folders that no media row uses: files of assets missing from the database (for example after restoring an older database snapshot) and variant versions left behind by preset changes or rebuilds. A version is kept while it is active, targeted, or still being rendered, and anything changed in the last hour is skipped so a running upload is never touched. Without `--delete` nothing is changed. `--delete` asks for confirmation (`--yes` skips it) and checks each entry against the database again before removing it. Removal is permanent: if you later restore an older database backup that still used those files, run `media verify --repair` and re-upload images whose originals are gone. Upload staging in `tmp/` is cleaned by the running website and is not touched.
196
+
188
197
  ## Deletion
189
198
 
190
199
  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.
package/docs/package.md CHANGED
@@ -21,13 +21,13 @@ bun pm pack --dry-run
21
21
  bun pm pack --destination /tmp
22
22
  ```
23
23
 
24
- This release produces `/tmp/sandcms-0.7.0.tgz`. `bun pm pack` builds the package through `prepack`; it packages only the allowlisted distribution, templates, documentation, and package metadata. The repository's example website, tests, databases, and environment files are excluded. `release:check` checks types, runs unit tests, inspects the packed archive, and installs/builds that archive in both a fresh starter and an existing SvelteKit site.
24
+ This release produces `/tmp/sandcms-0.8.0.tgz`. `bun pm pack` builds the package through `prepack`; it packages only the allowlisted distribution, templates, documentation, and package metadata. The repository's example website, tests, databases, and environment files are excluded. `release:check` checks types, runs unit tests, inspects the packed archive, and installs/builds that archive in both a fresh starter and an existing SvelteKit site.
25
25
 
26
26
  Upload the archive you just built:
27
27
 
28
28
  ```sh
29
- bun publish /tmp/sandcms-0.7.0.tgz --access restricted --registry=https://registry.npmjs.org/
30
- bun pm view sandcms@0.7.0 version
29
+ bun publish /tmp/sandcms-0.8.0.tgz --access restricted --registry=https://registry.npmjs.org/
30
+ bun pm view sandcms@0.8.0 version
31
31
  ```
32
32
 
33
33
  Complete the 2FA prompt (`bun publish` opens the browser, or pass `--otp`). The account must have publishing permission in `sandquist-group`. The package also defaults to restricted access and the npmjs registry in `publishConfig`. Do not set `private: true` on this package: that prevents publication entirely. Generated websites do set it.
@@ -39,7 +39,7 @@ For later releases, increment `version` in `package.json`, repeat the checks and
39
39
  After publishing, add a read token for the package to `~/.npmrc` (as above), then run:
40
40
 
41
41
  ```sh
42
- bunx --bun --package sandcms@0.7.0 sandcms setup --cwd ./my-site
42
+ bunx --bun --package sandcms@0.8.0 sandcms setup --cwd ./my-site
43
43
  cd my-site
44
44
  bun run dev
45
45
  ```
package/docs/releases.md CHANGED
@@ -1,5 +1,25 @@
1
1
  # Release notes
2
2
 
3
+ ## 0.8.0
4
+
5
+ This minor release makes deploys overlap safely, adds operator commands, a Pages screen and a site logo in the admin, and removes the Cloudflare Worker support deprecated in 0.7.0. Upgrading from 0.7.x needs a one-time `sandcms rebaseline` while the site is stopped, in a maintenance window of a few minutes; older sites upgrade with 0.7.x first. See the [0.8.0 upgrade checklist](upgrades.md#080-upgrade-checklist). The only migration is the new baseline `0000_baseline`; there is no other SQL migration. Stored data, sessions, media files and project-owned YAML are preserved.
6
+
7
+ **Breaking: new migration baseline.** The 0.5.0–0.7.x migrations `0000_foundation` through `0009_local_media` are replaced by one frozen baseline, `0000_baseline`, with the same schema. Existing 0.7.x databases are converted once with the new `sandcms rebaseline`, which copies every row into a database built from the baseline, verifies each table and keeps a safety copy; older databases are first upgraded with 0.7.x. Follow the [0.8.0 upgrade checklist](upgrades.md#080-upgrade-checklist).
8
+
9
+ Deploys now overlap safely on OpenShip, Dokploy and Coolify. Every later migration must keep the previous release working, or be marked `-- sandcms:breaking` and announced; `bun scripts/migrations.ts` refuses drops, renames, rebuilds and other risky statements that carry neither marker nor a reviewed `-- sandcms:compatible` note. A package started on a database with newer compatible migrations runs normally, so a restarted or rolled-back previous release keeps working; `backup`, `restore` and snapshots accept such databases. Table rebuilds generated by drizzle-kit no longer cascade-delete dependent rows or lose triggers: the runner keeps foreign keys off for the whole migration and restores triggers. See [compatible migrations](upgrades.md#compatible-migrations).
10
+
11
+ The generated `Dockerfile` probes health every 5 seconds with a two-minute budget, sets `SHUTDOWN_TIMEOUT=8` and `SANDCMS_AUTO_MIGRATE=true`, and the integration stops background work and exits after draining on SIGTERM, inside the 10-second stop timeout hosts use by default. New sites get an `openship.json` that seeds OpenShip's volume and readiness probe. A failing start no longer writes a new `before-migrate` copy on every retry. See [deploys](deployment.md#deploys) and [platform settings](deployment.md#platform-settings).
12
+
13
+ Adds `sandcms key create`, `key list` and `key revoke`, so an operator or an agent with shell access to the site can issue an API key without a browser session. `key create` prints only the secret on stdout, refuses owners who are not admins or editors or who still have a temporary password, and audits creation as `apikey.create`. There is no schema migration. See [API keys from the CLI](api.md#from-the-cli).
14
+
15
+ Adds operator commands for the server shell: `sandcms user list`, `user set-role`, `user remove` and `user sign-out [--all]`; `key revoke --email` to revoke every key of one user; `sandcms email test` to check SMTP settings; `sandcms forms export` for submission CSVs; and `sandcms media prune [--delete]` to free originals and old variant versions that no asset uses. `sandcms doctor`, `migrate --check`, `user list`, `key list` and `media prune` accept `--json`. The CLI gains `--version` and help for each command (`sandcms <command> --help`), reports unknown options and subcommands without a stack trace or prompt, and no longer creates an empty database file when a user command points at a missing database. Destructive commands ask for confirmation and require `--yes` when no terminal is attached. No migration or configuration change is required. See [users](deployment.md#users) and [freeing unused files](media.md#freeing-unused-files).
16
+
17
+ Replaces the collapsible **Pages** sidebar group with a single **Pages** link to a new Pages screen: a searchable, sortable table of every page with its path, status and last update, and a row menu to edit, preview, publish or unpublish. Pages with a custom `navigation.group` or `navigation: { group: false }` keep their sidebar entry and are also listed in the table. No migration or YAML change is required. See [Pages screen](content.md#pages-screen).
18
+
19
+ The admin sidebar shows the site's favicon instead of the first letter of the project name. The new optional `logo` setting in `config.yaml` chooses another image, or `false` keeps the letter. No migration or configuration change is required. See [site logo](content.md#site-logo).
20
+
21
+ **Removed:** the Cloudflare Worker support deprecated in 0.7.0: `sandcms media import-r2` with its `--worker-url` and `--worker-token-stdin` options, the `sandcms/worker` and `sandcms/worker/local` exports, the `createCMS({ workerUrl, workerToken })` options and the `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` variables. Sites with media still in R2 finish the import with 0.7.x, which 0.8.0 requires before `rebaseline` anyway. `sandcms upgrade` updates the generated integration; customized integrations must stop reading the `SANDCMS_WORKER_*` variables, which are no longer declared, and leftover `sandcms/worker/` files no longer build. `media.workerUrl` in `sandcms/config.yaml` is still accepted and ignored, so existing configuration keeps loading. See [Cloudflare](cloudflare.md).
22
+
3
23
  ## 0.7.0
4
24
 
5
25
  This minor release removes Cloudflare from SandCMS. A site becomes one container with one persistent volume that holds the database, image originals, variants and hourly database snapshots, and runs on any Docker host. We recommend [Dokploy](https://dokploy.com) or [Openship](https://openship.io). Upgrading from 0.6.3 applies retained migration `0009_local_media` and needs a one-time import of R2 media in a short maintenance window; see the [0.7.0 upgrade checklist](upgrades.md#070-upgrade-checklist). Stored data, asset IDs, public image URLs and project-owned YAML are preserved.
@@ -12,7 +32,7 @@ Uploads go to the site in 8 MB chunks with a signed ticket, so reverse proxies n
12
32
 
13
33
  Adds platform features for single-container hosting: a `site-id` check against a volume shared by another project, refusal to create a production database outside a mounted volume, a `/_sandcms/health` liveness route, hourly verified snapshots in `backups/latest.sqlite`, pruning of `before-migrate` snapshots to the newest three, first-admin bootstrap from `SANDCMS_BOOTSTRAP_EMAIL`, and `SANDCMS_INDEXING=false` for preview sites. The site derives its origin from the request and redirects other hostnames to `SANDCMS_ORIGIN`, so a domain change needs a restart, not a rebuild; remove `paths.origin` from `vite.config.ts`. New sites get a `Dockerfile` with a `HEALTHCHECK`. Overlapping (zero-downtime) and stop-then-start deploys both work; background work coordinates through database leases. See [deployment](deployment.md).
14
34
 
15
- Adds `sandcms media import-r2` to copy an existing site's originals and every ready variant from R2 through the old Worker, resumably and with a final verification; `sandcms media verify [--repair]` to find and fix media rows without files, for example after a restore; and `sandcms media rebuild --force` to re-encode existing variants with sharp under the same URLs. See [import R2 media](cloudflare.md#import-r2-media).
35
+ Adds `sandcms media import-r2` to copy an existing site's originals and every ready variant from R2 through the old Worker, resumably and with a final verification; `sandcms media verify [--repair]` to find and fix media rows without files, for example after a restore; and `sandcms media rebuild --force` to re-encode existing variants with sharp under the same URLs. See [sites still on Cloudflare media](cloudflare.md#sites-still-on-cloudflare-media).
16
36
 
17
37
  **Removed:** `sandcms worker update`, the Cloudflare prompt in setup, generated `sandcms/worker/*` files for new sites, and R2 direct-upload configuration. **Deprecated, kept through 0.7.x:** `createCMS({ workerUrl, workerToken })`, `media.workerUrl` (ignored), `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` (read only by the import), and the `sandcms/worker` and `sandcms/worker/local` exports. The package adds a `sandcms/media-processor` export used by the processor child process; keep `sharp` in `ssr.external`.
18
38
 
package/docs/upgrades.md CHANGED
@@ -1,8 +1,38 @@
1
1
  # Updates and generated files
2
2
 
3
+ ## 0.8.0 upgrade checklist
4
+
5
+ Version 0.8.0 replaces the 0.5.0–0.7.x migration history (`0000_foundation` through `0009_local_media`) with a new frozen baseline, `0000_baseline`, so that every later release can deploy by overlap. The schema is the same; existing databases are converted once with `sandcms rebaseline`, which copies every row into a database built from the new baseline. Plan a maintenance window of a few minutes. Signed-in users stay signed in.
6
+
7
+ 1. Upgrade the site to 0.7.x first and finish the [0.7.0 checklist](#070-upgrade-checklist), including `sandcms media import-r2` until it reports no failures and `sandcms media verify`. `rebaseline` accepts only the complete 0.7 history and refuses older databases.
8
+ 2. Take a volume backup and a verified `sandcms backup` with the installed 0.7.x package.
9
+ 3. Install `sandcms@0.8.0`, review `sandcms upgrade --check`, then run `sandcms upgrade`. It updates the generated `Dockerfile` (new health check timings, `SHUTDOWN_TIMEOUT=8`, `SANDCMS_AUTO_MIGRATE=true`) and integration (graceful shutdown, no Worker settings), and adds `openship.json`. Customized integrations need the shutdown listener from `templates/integration.ts` and must stop passing `workerUrl` and `workerToken`: the `SANDCMS_WORKER_*` variables are no longer declared, so the build fails while they are read. Delete a leftover `sandcms/worker/` directory; it imports the removed `sandcms/worker` exports.
10
+ 4. Stop the site and disable automatic restarts. In a one-off container with the same volume and the new image, run:
11
+
12
+ ```sh
13
+ bun x --no-install sandcms rebaseline --database /data/sandcms.sqlite
14
+ ```
15
+
16
+ It takes the exclusive database lock (refused while a website process runs), checks the exact 0.7 history, integrity and references, writes a safety copy to `<database>.before-rebaseline-<timestamp>.sqlite`, builds the new database, copies every table, verifies that each table's rows match exactly, and only then replaces the database. On any failure the database is left untouched. Media files are not touched, and `SANDCMS_SECRET` must stay the same (two-factor secrets are encrypted with it).
17
+
18
+ 5. Start the site with the new image and check sign-in, content and media. Then apply the [platform settings](deployment.md#platform-settings) for overlapping deploys.
19
+
20
+ **Removed in 0.8.0:** the Cloudflare Worker support deprecated in 0.7.0 — `sandcms media import-r2`, the `sandcms/worker` and `sandcms/worker/local` exports, `createCMS({ workerUrl, workerToken })` and the `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` variables. Remove the variables from the environment. `media.workerUrl` in `sandcms/config.yaml` is still accepted and ignored. See [Cloudflare](cloudflare.md).
21
+
22
+ The 0.7.x package refuses a rebaselined database. Going back means stopping the site and restoring the `before-rebaseline` copy with the 0.7.x image (`sandcms restore` of that version accepts it). Snapshots and `before-migrate` copies taken before the conversion keep the 0.7 history; 0.8.0 refuses to restore them and names `sandcms rebaseline`.
23
+
24
+ ## Compatible migrations
25
+
26
+ From 0.8.0, deploys overlap: the new release migrates while the previous one still serves, and a rollback starts the previous release on the migrated database. Every migration therefore keeps the previous release working, unless it is marked breaking:
27
+
28
+ - **Compatible (the default):** new tables, nullable columns or columns with a default, new indexes, and reviewed data changes the previous release can read. A release whose migrations are all compatible deploys by overlap and rolls back without a restore. A package started on a database with newer compatible migrations it does not know logs them and runs normally; `sandcms backup`, `restore` and the hourly snapshot accept such databases too.
29
+ - **Breaking:** a migration whose SQL contains the line `-- sandcms:breaking`, such as one that drops or renames a column the previous release uses. Its release notes say so. Deploy it stop-first: stop the site, then deploy; the new release migrates on start. An older package refuses a database after a breaking migration and names it.
30
+
31
+ Release notes list every migration and whether it is breaking.
32
+
3
33
  ## 0.7.0 upgrade checklist
4
34
 
5
- Version 0.7.0 moves media from Cloudflare R2 to the site's volume and includes retained migration `0009_local_media`. Follow this order when upgrading from 0.6.3; upgrading from 0.6.2 or earlier still requires the earlier checklists first. Plan a short maintenance window: images are unavailable between the deploy (step 5) and the end of the import (step 6).
35
+ Version 0.7.0 moves media from Cloudflare R2 to the site's volume and includes retained migration `0009_local_media`. Run this checklist with the 0.7.x package: 0.8.0 no longer includes `sandcms media import-r2`. Follow this order when upgrading from 0.6.3; upgrading from 0.6.2 or earlier still requires the earlier checklists first. Plan a short maintenance window: images are unavailable between the deploy (step 5) and the end of the import (step 6).
6
36
 
7
37
  1. Check in the admin that no uploads are pending or processing, and take a backup with the installed package (`sandcms backup`, or a volume backup).
8
38
  2. Make sure the volume has free space of at least **three times** the site's current media in R2.
@@ -11,9 +41,9 @@ Version 0.7.0 moves media from Cloudflare R2 to the site's volume and includes r
11
41
  - `vite.config.ts`: remove `paths: { origin: … }` from `sveltekit()`, and add `sharp` to `ssr.external`: `external: ['bun:sqlite', 'sharp']`. See [server build configuration](deployment.md#server-build-configuration).
12
42
  - A customized `src/lib/server/sandcms/index.ts`: pass `server: true`, `mediaDir: env.SANDCMS_MEDIA_DIR`, `requestLimit: env.SANDCMS_REQUEST_LIMIT`, `indexing: env.SANDCMS_INDEXING`, `canonicalRedirect: env.SANDCMS_CANONICAL_REDIRECT` and `bootstrapEmail: env.SANDCMS_BOOTSTRAP_EMAIL` to `createCMS()`, and call `media.start()` before storing the instance, closing it and rethrowing on failure, as the generated integration does. `server: true` takes the data-volume lock before the database opens. `sandcmsEnvVars()` in `src/env.ts` already declares the new variables.
13
43
  - Sites with `railpack.json` keep building with Railpack: `sandcms upgrade` does not add a `Dockerfile` to them, because hosts that detect one switch builders. To switch, copy `node_modules/sandcms/templates/Dockerfile` to the project root; later upgrades then manage it.
14
- 4. On the host, set `BODY_SIZE_LIMIT=10M`. Both overlapping and stop-then-start deploys work; see [deploys and volume checks](deployment.md#deploys-and-volume-checks). Use `GET /_sandcms/health` as the health check if the host does not use the image's `HEALTHCHECK`.
44
+ 4. On the host, set `BODY_SIZE_LIMIT=10M`. Both overlapping and stop-then-start deploys work; see [deploys](deployment.md#deploys). Use `GET /_sandcms/health` as the health check if the host does not use the image's `HEALTHCHECK`.
15
45
  5. Deploy with `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` still set. Migration `0009_local_media` applies on start with `SANDCMS_AUTO_MIGRATE=true`, or run `sandcms migrate`. Existing data is preserved.
16
- 6. Run `sandcms media import-r2` in the container and check the site; see [import R2 media](cloudflare.md#import-r2-media). Rerun it until it reports no failures.
46
+ 6. Run `sandcms media import-r2` in the container and check the site; see the import guide in the 0.7.x package (`docs/cloudflare.md`). Rerun it until it reports no failures.
17
47
  7. Remove the Worker variables and redeploy. Delete the Worker and its R2 bucket only once a restore from a volume backup has been verified to contain the originals; see [remove the Worker and bucket](cloudflare.md#remove-the-worker-and-bucket).
18
48
 
19
49
  Going back to 0.6.3 after step 5 means restoring the `before-migrate` snapshot together with the old image; 0.6.3 refuses a database with migration `0009`.
@@ -29,7 +59,7 @@ Going back to 0.6.3 after step 5 means restoring the `before-migrate` snapshot t
29
59
  - **Snapshots:** the server writes `backups/latest.sqlite` next to the database every hour. Restores use it; see [backups and restore](deployment.md#backups-and-restore).
30
60
  - **New commands:** `sandcms media import-r2`, `sandcms media verify [--repair]`, `sandcms media rebuild --force`.
31
61
  - **Removed:** `sandcms worker update`, Cloudflare setup, the generated `sandcms/worker/*` files for new sites, and the `wrangler` requirement for site development. Existing `sandcms/worker/` files are left alone and reported as removable.
32
- - **Deprecated, kept through 0.7.x:** `createCMS({ workerUrl, workerToken })`, `media.workerUrl` (ignored), the `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` variables (read only by `media import-r2`), and the `sandcms/worker` and `sandcms/worker/local` exports.
62
+ - **Deprecated, kept through 0.7.x and removed in 0.8.0:** `createCMS({ workerUrl, workerToken })`, `media.workerUrl` (ignored), the `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` variables (read only by `media import-r2`), and the `sandcms/worker` and `sandcms/worker/local` exports.
33
63
 
34
64
  ## 0.6.3 upgrade checklist
35
65
 
@@ -168,6 +198,8 @@ The new processing version gives rebuilt variants new keys; existing published v
168
198
 
169
199
  ## From 0.5.0: retained migrations
170
200
 
201
+ This section describes 0.5.0–0.7.x. From 0.8.0, `0000_baseline.sql` is the frozen baseline and the same rules apply to it; see the [0.8.0 checklist](#080-upgrade-checklist).
202
+
171
203
  Release 0.5.0 freezes `0000_foundation.sql` without changing its SQL or hash. Future schema changes append numbered migrations. Fresh installations apply the full history; supported databases apply only pending migrations, preserving existing data. Repeated migration is a no-op.
172
204
 
173
205
  Each migration runs in its own transaction. If one fails, that migration's SQL and history entry roll back; earlier completed migrations remain applied. Fix the cause and rerun. Modified hashes, missing history entries, and databases newer than the installed package are rejected. Use the matching package for inspection or recovery; never reset a supported database to bypass validation.
@@ -179,10 +211,12 @@ Before updating, stop website and job processes and take a verified backup using
179
211
  1. Edit `src/lib/server/db/schema.ts` and update its callers and fixtures.
180
212
  2. Run `bun run db:generate --name descriptive_change`. Drizzle generates the next SQL migration and snapshot and appends its journal entry; the script refreshes embedded `migration-data.ts` for bundler compatibility.
181
213
  3. Review SQL for data preservation, constraints, and compatibility with the transactional SQLite runner. Include any required data transformations in the new, unreleased migration. Never rewrite released migrations or snapshots.
182
- 4. Commit the schema, new migration artifacts, embedded SQL, code, tests, and documentation together.
183
- 5. Run `bun run release:check`. Cover fresh initialization, upgrades with existing data, repeated migration, rollback on failure, and incompatible history rejection.
214
+ 4. Keep the previous release working ([compatible migrations](#compatible-migrations)). The script checks every migration after the baseline and refuses drops, renames, new `NOT NULL` columns without a default, new unique indexes on existing tables, dropped unique indexes, table rebuilds (`__new_` tables), `UPDATE`/`DELETE` statements and `PRAGMA` other than `foreign_keys`. Once you have confirmed that the previous release works with such a statement, add a line `-- sandcms:compatible <reason>` to the migration; otherwise add `-- sandcms:breaking` and announce it in the release. Then rerun `bun scripts/migrations.ts`.
215
+ 5. Table rebuilds are safe to run: for SQL with `PRAGMA foreign_keys=OFF`, the runner turns foreign keys off for the whole transaction (SQLite ignores the pragma inside one), drops and recreates the triggers around it, and refuses to commit if references are left broken. Drizzle-kit does not generate triggers; write them by hand in the migration that needs them.
216
+ 6. Commit the schema, new migration artifacts, embedded SQL, code, tests, and documentation together.
217
+ 7. Run `bun run release:check`. Cover fresh initialization, upgrades with existing data, repeated migration, rollback on failure, and incompatible history rejection.
184
218
 
185
- `bun scripts/migrations.ts` only refreshes embedded SQL. Packaging includes the complete retained history. `bun run db:baseline` is disabled at 0.5.0 and later. Never use `drizzle-kit push` against deployed databases.
219
+ `bun scripts/migrations.ts` only refreshes embedded SQL. Packaging includes the complete retained history. `bun run db:baseline` is disabled; 0.8.0's `0000_baseline.sql` was regenerated once for the rebaseline. Never use `drizzle-kit push` against deployed databases.
186
220
 
187
221
  ## Moving from pre-0.5.0
188
222