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.
- package/README.md +4 -4
- package/dist/admin/Admin.svelte +7 -5
- package/dist/admin/AssetAttachment.svelte +8 -3
- package/dist/admin/AssetAttachment.svelte.d.ts +3 -0
- package/dist/admin/Editor.svelte +5 -9
- package/dist/admin/Fields.svelte +2 -1
- package/dist/admin/Gallery.svelte +221 -76
- package/dist/admin/Inbox.svelte +3 -2
- package/dist/admin/MediaPicker.svelte +36 -20
- package/dist/admin/Navigation.svelte +13 -2
- package/dist/admin/Pages.svelte +195 -0
- package/dist/admin/Pages.svelte.d.ts +7 -0
- package/dist/admin/Shell.svelte +27 -5
- package/dist/admin/SortableList.svelte +82 -61
- package/dist/admin/SortableList.svelte.d.ts +3 -1
- package/dist/admin/Users.svelte +8 -3
- package/dist/admin/generated/admin.css +300 -20
- package/dist/admin/navigation.d.ts +9 -0
- package/dist/admin/navigation.js +20 -1
- package/dist/admin/types.d.ts +1 -0
- package/dist/blueprints/labels.d.ts +6 -0
- package/dist/blueprints/labels.js +14 -0
- package/dist/blueprints/load.js +11 -2
- package/dist/blueprints/types.d.ts +2 -2
- package/dist/cli/admin.d.ts +39 -0
- package/dist/cli/admin.js +95 -0
- package/dist/cli/backup.js +4 -4
- package/dist/cli/doctor.d.ts +8 -1
- package/dist/cli/doctor.js +19 -9
- package/dist/cli/email-test.d.ts +3 -0
- package/dist/cli/email-test.js +20 -0
- package/dist/cli/files.js +2 -1
- package/dist/cli/index.js +373 -135
- package/dist/cli/rebaseline.d.ts +10 -0
- package/dist/cli/rebaseline.js +117 -0
- package/dist/cli/upgrade.js +17 -9
- package/dist/env.d.ts +0 -8
- package/dist/env.js +0 -8
- package/dist/notification-fields.js +2 -1
- package/dist/server/admin-load.d.ts +72 -0
- package/dist/server/admin-load.js +20 -0
- package/dist/server/api-keys.d.ts +96 -0
- package/dist/server/api-keys.js +115 -0
- package/dist/server/api.js +16 -61
- package/dist/server/cms.d.ts +0 -5
- package/dist/server/cms.js +4 -3
- package/dist/server/db/auto-migrate.d.ts +0 -4
- package/dist/server/db/auto-migrate.js +12 -3
- package/dist/server/db/legacy.d.ts +13 -0
- package/dist/server/db/legacy.js +60 -0
- package/dist/server/db/migration-data.js +2 -38
- package/dist/server/db/migrations/{0000_foundation.sql → 0000_baseline.sql} +120 -4
- package/dist/server/db/migrations/meta/0000_snapshot.json +578 -3
- package/dist/server/db/migrations/meta/_journal.json +2 -65
- package/dist/server/db/schema.js +8 -6
- package/dist/server/db/store.d.ts +25 -2
- package/dist/server/db/store.js +90 -26
- package/dist/server/forms.js +2 -1
- package/dist/server/media/runner.d.ts +1 -1
- package/dist/server/media/runner.js +1 -1
- package/dist/server/media/service.d.ts +0 -4
- package/dist/server/media/service.js +0 -2
- package/dist/server/media/verify.d.ts +28 -0
- package/dist/server/media/verify.js +94 -2
- package/dist/server/platform/snapshots.js +3 -3
- package/docs/acceptance.md +2 -2
- package/docs/api.md +15 -1
- package/docs/cloudflare.md +9 -41
- package/docs/content.md +18 -3
- package/docs/deployment.md +97 -34
- package/docs/email.md +6 -0
- package/docs/forms.md +1 -1
- package/docs/media.md +10 -1
- package/docs/package.md +4 -4
- package/docs/releases.md +21 -1
- package/docs/upgrades.md +41 -7
- package/package.json +4 -10
- package/templates/Dockerfile +6 -2
- package/templates/integration.ts +10 -5
- package/templates/openship.json +9 -0
- package/templates/sandcms/config.yaml +1 -0
- package/dist/server/db/migrations/0001_independent_password_resets.sql +0 -3
- package/dist/server/db/migrations/0002_email_failure_reason.sql +0 -1
- package/dist/server/db/migrations/0003_direct_r2_uploads.sql +0 -10
- package/dist/server/db/migrations/0004_agent_api_keys.sql +0 -38
- package/dist/server/db/migrations/0005_api_retention_and_pagination.sql +0 -3
- package/dist/server/db/migrations/0006_durable_media_deletion.sql +0 -7
- package/dist/server/db/migrations/0007_content_and_job_indexes.sql +0 -2
- package/dist/server/db/migrations/0008_search_text_cache.sql +0 -45
- package/dist/server/db/migrations/0009_local_media.sql +0 -9
- package/dist/server/db/migrations/meta/0001_snapshot.json +0 -1197
- package/dist/server/db/migrations/meta/0002_snapshot.json +0 -1204
- package/dist/server/db/migrations/meta/0003_snapshot.json +0 -1281
- package/dist/server/db/migrations/meta/0004_snapshot.json +0 -1546
- package/dist/server/db/migrations/meta/0005_snapshot.json +0 -1572
- package/dist/server/db/migrations/meta/0006_snapshot.json +0 -1627
- package/dist/server/db/migrations/meta/0007_snapshot.json +0 -1643
- package/dist/server/db/migrations/meta/0008_snapshot.json +0 -1711
- package/dist/server/db/migrations/meta/0009_snapshot.json +0 -1763
- package/dist/server/media/import-r2.d.ts +0 -56
- package/dist/server/media/import-r2.js +0 -342
- package/dist/worker/index.d.ts +0 -10
- package/dist/worker/index.js +0 -460
- package/dist/worker/local.d.ts +0 -5
- package/dist/worker/local.js +0 -57
- package/dist/worker/source.d.ts +0 -2
- package/dist/worker/source.js +0 -31
- package/dist/worker/svg.d.ts +0 -1
- package/dist/worker/svg.js +0 -2
- package/dist/worker/uploads.d.ts +0 -22
- package/dist/worker/uploads.js +0 -48
package/docs/cloudflare.md
CHANGED
|
@@ -1,51 +1,19 @@
|
|
|
1
|
-
# Cloudflare:
|
|
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.
|
|
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
|
-
|
|
5
|
+
## Sites still on Cloudflare media
|
|
6
6
|
|
|
7
|
-
|
|
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
|
-
|
|
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
|
-
|
|
48
|
-
|
|
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
|
|
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:
|
|
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:
|
package/docs/deployment.md
CHANGED
|
@@ -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
|
|
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 |
|
|
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 |
|
|
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
|
-
|
|
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`.
|
|
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
|
|
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
|
|
110
|
+
## Deploys
|
|
110
111
|
|
|
111
|
-
|
|
112
|
+
Deploys overlap: the host starts the new container next to the old one, waits until its health check passes, switches traffic, then stops the old container. Nobody sees downtime, and a release that fails to start never goes live. Per platform, see [platform settings](#platform-settings).
|
|
112
113
|
|
|
113
|
-
|
|
114
|
+
- **Shared volume.** Both containers use the same SQLite database for a short time. SQLite handles two processes on a local volume; background work coordinates through database leases (one image is processed at a time, one server writes the hourly snapshot), and sessions, rate limits and upload progress are database rows, so visitors and editors keep working across the switch. Keep `SANDCMS_SECRET` the same across deploys. Run a single replica per site; several long-running replicas are not supported.
|
|
115
|
+
- **Migrations.** The new container migrates on its first health check while the old one still serves. Every migration must therefore keep the previous release working on the migrated database; the old release only checks the schema when it starts and keeps serving afterwards. A previous release that starts again on that database (a restart, a crash, a rollback) accepts migrations it does not know as long as none is marked breaking; see [compatible migrations](upgrades.md#compatible-migrations).
|
|
116
|
+
- **Breaking releases.** A release whose notes say it contains a breaking migration cannot overlap. Deploy it stop-first: stop the site, deploy, and let the new container migrate on start. The previous release refuses that database afterwards, so rolling back means restoring the `before-migrate` snapshot.
|
|
117
|
+
- **Shutdown.** The old container gets SIGTERM, stops accepting connections, finishes requests in progress for up to `SHUTDOWN_TIMEOUT` seconds (8 in the starter image), stops background work and exits. Hosts send SIGKILL after their stop timeout, 10 seconds unless configured, so keep `SHUTDOWN_TIMEOUT` below it. Uploads are sent in 8 MB chunks and resume, so a cut-off chunk is simply sent again; unfinished image processing is picked up by the new container once its lease expires (at most two minutes).
|
|
118
|
+
|
|
119
|
+
### Volume checks
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
-
|
|
230
|
-
-
|
|
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
|
|
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.
|
|
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.
|
|
30
|
-
bun pm view sandcms@0.
|
|
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.
|
|
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 [
|
|
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
|
|
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
|
|
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.
|
|
183
|
-
5.
|
|
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
|
|
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
|
|