sandcms 0.6.2 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -10
- package/dist/admin/Account.svelte +286 -83
- package/dist/admin/Admin.svelte +14 -1
- package/dist/admin/ApiKeys.svelte +146 -79
- package/dist/admin/AssetAttachment.svelte +10 -12
- package/dist/admin/AssetAttachment.svelte.d.ts +0 -1
- package/dist/admin/BlueprintFields.svelte +20 -5
- package/dist/admin/BlueprintFields.svelte.d.ts +2 -1
- package/dist/admin/Collection.svelte +111 -54
- package/dist/admin/Dashboard.svelte +3 -37
- package/dist/admin/DateField.svelte +75 -0
- package/dist/admin/DateField.svelte.d.ts +11 -0
- package/dist/admin/Editor.svelte +70 -65
- package/dist/admin/Fields.svelte +24 -23
- package/dist/admin/Fields.svelte.d.ts +0 -1
- package/dist/admin/FocusPicker.svelte +1 -2
- package/dist/admin/Gallery.svelte +2 -7
- package/dist/admin/Gallery.svelte.d.ts +0 -1
- package/dist/admin/GlobalSearch.svelte +54 -26
- package/dist/admin/HoverHint.svelte +37 -0
- package/dist/admin/HoverHint.svelte.d.ts +8 -0
- package/dist/admin/Inbox.svelte +6 -11
- package/dist/admin/LinkField.svelte +128 -66
- package/dist/admin/LinkField.svelte.d.ts +0 -1
- package/dist/admin/Login.svelte +0 -1
- package/dist/admin/MediaLibrary.svelte +70 -56
- package/dist/admin/MediaPicker.svelte +62 -55
- package/dist/admin/MediaPicker.svelte.d.ts +0 -1
- package/dist/admin/NotificationSettings.svelte +35 -27
- package/dist/admin/RichText.svelte +2 -2
- package/dist/admin/RowMenu.svelte +28 -0
- package/dist/admin/RowMenu.svelte.d.ts +10 -0
- package/dist/admin/SearchList.svelte +51 -14
- package/dist/admin/Shell.svelte +64 -29
- package/dist/admin/ThemePicker.svelte +72 -0
- package/dist/admin/ThemePicker.svelte.d.ts +18 -0
- package/dist/admin/UploadButton.svelte +2 -1
- package/dist/admin/UploadProgress.svelte +24 -0
- package/dist/admin/UploadProgress.svelte.d.ts +7 -0
- package/dist/admin/Users.svelte +106 -50
- package/dist/admin/client.d.ts +5 -670
- package/dist/admin/client.js +20 -1
- package/dist/admin/components/ui/alert/alert.svelte.d.ts +3 -13
- package/dist/admin/components/ui/attachment/attachment-media.svelte.d.ts +3 -13
- package/dist/admin/components/ui/attachment/attachment.svelte.d.ts +6 -26
- package/dist/admin/components/ui/badge/badge.svelte.d.ts +7 -25
- package/dist/admin/components/ui/button/button.svelte.d.ts +15 -53
- package/dist/admin/components/ui/calendar/calendar-caption.svelte +76 -0
- package/dist/admin/components/ui/calendar/calendar-caption.svelte.d.ts +19 -0
- package/dist/admin/components/ui/calendar/calendar-cell.svelte +19 -0
- package/dist/admin/components/ui/calendar/calendar-cell.svelte.d.ts +4 -0
- package/dist/admin/components/ui/calendar/calendar-day.svelte +33 -0
- package/dist/admin/components/ui/calendar/calendar-day.svelte.d.ts +4 -0
- package/dist/admin/components/ui/calendar/calendar-grid-body.svelte +12 -0
- package/dist/admin/components/ui/calendar/calendar-grid-body.svelte.d.ts +4 -0
- package/dist/admin/components/ui/calendar/calendar-grid-head.svelte +12 -0
- package/dist/admin/components/ui/calendar/calendar-grid-head.svelte.d.ts +4 -0
- package/dist/admin/components/ui/calendar/calendar-grid-row.svelte +12 -0
- package/dist/admin/components/ui/calendar/calendar-grid-row.svelte.d.ts +4 -0
- package/dist/admin/components/ui/calendar/calendar-grid.svelte +16 -0
- package/dist/admin/components/ui/calendar/calendar-grid.svelte.d.ts +4 -0
- package/dist/admin/components/ui/calendar/calendar-head-cell.svelte +19 -0
- package/dist/admin/components/ui/calendar/calendar-head-cell.svelte.d.ts +4 -0
- package/dist/admin/components/ui/calendar/calendar-header.svelte +19 -0
- package/dist/admin/components/ui/calendar/calendar-header.svelte.d.ts +4 -0
- package/dist/admin/components/ui/calendar/calendar-heading.svelte +16 -0
- package/dist/admin/components/ui/calendar/calendar-heading.svelte.d.ts +4 -0
- package/dist/admin/components/ui/calendar/calendar-month-select.svelte +48 -0
- package/dist/admin/components/ui/calendar/calendar-month-select.svelte.d.ts +4 -0
- package/dist/admin/components/ui/calendar/calendar-month.svelte +15 -0
- package/dist/admin/components/ui/calendar/calendar-month.svelte.d.ts +5 -0
- package/dist/admin/components/ui/calendar/calendar-months.svelte +19 -0
- package/dist/admin/components/ui/calendar/calendar-months.svelte.d.ts +5 -0
- package/dist/admin/components/ui/calendar/calendar-nav.svelte +19 -0
- package/dist/admin/components/ui/calendar/calendar-nav.svelte.d.ts +5 -0
- package/dist/admin/components/ui/calendar/calendar-next-button.svelte +37 -0
- package/dist/admin/components/ui/calendar/calendar-next-button.svelte.d.ts +8 -0
- package/dist/admin/components/ui/calendar/calendar-prev-button.svelte +37 -0
- package/dist/admin/components/ui/calendar/calendar-prev-button.svelte.d.ts +8 -0
- package/dist/admin/components/ui/calendar/calendar-year-select.svelte +47 -0
- package/dist/admin/components/ui/calendar/calendar-year-select.svelte.d.ts +4 -0
- package/dist/admin/components/ui/calendar/calendar.svelte +115 -0
- package/dist/admin/components/ui/calendar/calendar.svelte.d.ts +21 -0
- package/dist/admin/components/ui/calendar/index.d.ts +19 -0
- package/dist/admin/components/ui/calendar/index.js +21 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-checkbox-group.svelte +16 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-checkbox-group.svelte.d.ts +4 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-checkbox-item.svelte +46 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-checkbox-item.svelte.d.ts +9 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-content.svelte +31 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-content.svelte.d.ts +10 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-group-heading.svelte +22 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-group-heading.svelte.d.ts +8 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-group.svelte +7 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-group.svelte.d.ts +4 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-item.svelte +27 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-item.svelte.d.ts +8 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-label.svelte +24 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-label.svelte.d.ts +8 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-portal.svelte +7 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-portal.svelte.d.ts +3 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-radio-group.svelte +16 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-radio-group.svelte.d.ts +4 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-radio-item.svelte +36 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-radio-item.svelte.d.ts +4 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-separator.svelte +17 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-separator.svelte.d.ts +4 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-shortcut.svelte +23 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-shortcut.svelte.d.ts +5 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub-content.svelte +31 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub-content.svelte.d.ts +10 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub-trigger.svelte +29 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub-trigger.svelte.d.ts +7 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub.svelte +7 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-sub.svelte.d.ts +3 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-trigger.svelte +7 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu-trigger.svelte.d.ts +4 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu.svelte +7 -0
- package/dist/admin/components/ui/dropdown-menu/dropdown-menu.svelte.d.ts +3 -0
- package/dist/admin/components/ui/dropdown-menu/index.d.ts +18 -0
- package/dist/admin/components/ui/dropdown-menu/index.js +18 -0
- package/dist/admin/components/ui/input-otp/index.d.ts +5 -0
- package/dist/admin/components/ui/input-otp/index.js +5 -0
- package/dist/admin/components/ui/input-otp/input-otp-group.svelte +23 -0
- package/dist/admin/components/ui/input-otp/input-otp-group.svelte.d.ts +5 -0
- package/dist/admin/components/ui/input-otp/input-otp-separator.svelte +27 -0
- package/dist/admin/components/ui/input-otp/input-otp-separator.svelte.d.ts +5 -0
- package/dist/admin/components/ui/input-otp/input-otp-slot.svelte +29 -0
- package/dist/admin/components/ui/input-otp/input-otp-slot.svelte.d.ts +4 -0
- package/dist/admin/components/ui/input-otp/input-otp.svelte +24 -0
- package/dist/admin/components/ui/input-otp/input-otp.svelte.d.ts +4 -0
- package/dist/admin/components/ui/popover/index.d.ts +9 -0
- package/dist/admin/components/ui/popover/index.js +11 -0
- package/dist/admin/components/ui/popover/popover-close.svelte +7 -0
- package/dist/admin/components/ui/popover/popover-close.svelte.d.ts +4 -0
- package/dist/admin/components/ui/popover/popover-content.svelte +31 -0
- package/dist/admin/components/ui/popover/popover-content.svelte.d.ts +10 -0
- package/dist/admin/components/ui/popover/popover-description.svelte +20 -0
- package/dist/admin/components/ui/popover/popover-description.svelte.d.ts +5 -0
- package/dist/admin/components/ui/popover/popover-header.svelte +20 -0
- package/dist/admin/components/ui/popover/popover-header.svelte.d.ts +5 -0
- package/dist/admin/components/ui/popover/popover-portal.svelte +7 -0
- package/dist/admin/components/ui/popover/popover-portal.svelte.d.ts +3 -0
- package/dist/admin/components/ui/popover/popover-title.svelte +20 -0
- package/dist/admin/components/ui/popover/popover-title.svelte.d.ts +5 -0
- package/dist/admin/components/ui/popover/popover-trigger.svelte +17 -0
- package/dist/admin/components/ui/popover/popover-trigger.svelte.d.ts +4 -0
- package/dist/admin/components/ui/popover/popover.svelte +7 -0
- package/dist/admin/components/ui/popover/popover.svelte.d.ts +3 -0
- package/dist/admin/components/ui/switch/switch.svelte +2 -2
- package/dist/admin/components/ui/toggle/toggle.svelte.d.ts +6 -26
- package/dist/admin/components/ui/tooltip/index.d.ts +6 -0
- package/dist/admin/components/ui/tooltip/index.js +8 -0
- package/dist/admin/components/ui/tooltip/tooltip-content.svelte +48 -0
- package/dist/admin/components/ui/tooltip/tooltip-content.svelte.d.ts +11 -0
- package/dist/admin/components/ui/tooltip/tooltip-portal.svelte +7 -0
- package/dist/admin/components/ui/tooltip/tooltip-portal.svelte.d.ts +4 -0
- package/dist/admin/components/ui/tooltip/tooltip-provider.svelte +7 -0
- package/dist/admin/components/ui/tooltip/tooltip-provider.svelte.d.ts +4 -0
- package/dist/admin/components/ui/tooltip/tooltip-trigger.svelte +7 -0
- package/dist/admin/components/ui/tooltip/tooltip-trigger.svelte.d.ts +25 -0
- package/dist/admin/components/ui/tooltip/tooltip.svelte +7 -0
- package/dist/admin/components/ui/tooltip/tooltip.svelte.d.ts +25 -0
- package/dist/admin/generated/admin.css +1298 -234
- package/dist/admin/slug.d.ts +1 -0
- package/dist/admin/slug.js +6 -0
- package/dist/admin/theme-context.d.ts +7 -0
- package/dist/admin/theme-context.js +3 -0
- package/dist/admin/theme.d.ts +7 -0
- package/dist/admin/theme.js +14 -0
- package/dist/admin/types.d.ts +2 -1
- package/dist/admin/uploads.d.ts +8 -1
- package/dist/admin/uploads.js +94 -16
- package/dist/blueprints/files.js +1 -0
- package/dist/blueprints/load.js +7 -2
- package/dist/blueprints/types.d.ts +4 -1
- package/dist/cli/doctor.d.ts +3 -1
- package/dist/cli/doctor.js +85 -30
- package/dist/cli/files.d.ts +2 -6
- package/dist/cli/files.js +11 -2
- package/dist/cli/index.js +99 -31
- package/dist/cli/scaffold.js +8 -8
- package/dist/cli/setup.js +16 -26
- package/dist/cli/upgrade.js +21 -2
- package/dist/env.d.ts +32 -0
- package/dist/env.js +53 -3
- package/dist/server/admin-load.d.ts +13 -5
- package/dist/server/admin-load.js +8 -3
- package/dist/server/api-access.d.ts +4 -0
- package/dist/server/api-access.js +15 -2
- package/dist/server/api-pagination.d.ts +3 -0
- package/dist/server/api.js +11 -3
- package/dist/server/auth.d.ts +11 -9
- package/dist/server/auth.js +23 -0
- package/dist/server/cms.d.ts +65 -18
- package/dist/server/cms.js +62 -6
- package/dist/server/db/migration-data.js +4 -0
- package/dist/server/db/migrations/0009_local_media.sql +9 -0
- package/dist/server/db/migrations/meta/0009_snapshot.json +1763 -0
- package/dist/server/db/migrations/meta/_journal.json +7 -0
- package/dist/server/db/schema.d.ts +119 -2
- package/dist/server/db/schema.js +15 -3
- package/dist/server/hooks.js +155 -81
- package/dist/server/media/contracts.d.ts +115 -0
- package/dist/server/media/contracts.js +12 -0
- package/dist/server/media/deletions.d.ts +2 -1
- package/dist/server/media/deletions.js +3 -3
- package/dist/server/media/delivery.js +7 -11
- package/dist/server/media/import-r2.d.ts +56 -0
- package/dist/server/media/import-r2.js +342 -0
- package/dist/server/media/processor-child.d.ts +2 -0
- package/dist/server/media/processor-child.js +236 -0
- package/dist/server/media/processor.d.ts +51 -0
- package/dist/server/media/processor.js +135 -0
- package/dist/server/media/render-math.d.ts +24 -0
- package/dist/server/media/render-math.js +50 -0
- package/dist/server/media/runner.d.ts +30 -1
- package/dist/server/media/runner.js +418 -165
- package/dist/server/media/service.d.ts +56 -10
- package/dist/server/media/service.js +309 -98
- package/dist/server/media/storage.d.ts +5 -0
- package/dist/server/media/storage.js +279 -0
- package/dist/server/media/svg.d.ts +5 -0
- package/dist/server/media/svg.js +142 -0
- package/dist/server/media/upload-ticket.d.ts +12 -0
- package/dist/server/media/upload-ticket.js +35 -0
- package/dist/server/media/verify.d.ts +36 -0
- package/dist/server/media/verify.js +109 -0
- package/dist/server/platform/http.d.ts +27 -0
- package/dist/server/platform/http.js +77 -0
- package/dist/server/platform/index.d.ts +52 -0
- package/dist/server/platform/index.js +98 -0
- package/dist/server/platform/snapshots.d.ts +18 -0
- package/dist/server/platform/snapshots.js +110 -0
- package/dist/server/platform/volume.d.ts +20 -0
- package/dist/server/platform/volume.js +60 -0
- package/dist/worker/svg.d.ts +1 -5
- package/dist/worker/svg.js +2 -142
- package/docs/acceptance.md +6 -4
- package/docs/api.md +42 -4
- package/docs/cloudflare.md +48 -142
- package/docs/content.md +2 -2
- package/docs/deployment.md +159 -57
- package/docs/forms.md +1 -1
- package/docs/media.md +85 -21
- package/docs/package.md +21 -18
- package/docs/plans/0.7-self-hosted.md +264 -0
- package/docs/releases.md +27 -1
- package/docs/upgrades.md +44 -6
- package/package.json +38 -37
- package/templates/Dockerfile +28 -0
- package/templates/integration.ts +18 -2
- package/templates/railpack.json +1 -1
- package/templates/sandcms/blueprints/files/image.yaml +1 -1
- package/templates/sandcms/config.yaml +0 -1
- package/dist/cli/cloudflare.d.ts +0 -8
- package/dist/cli/cloudflare.js +0 -135
- package/templates/sandcms/worker/index.ts +0 -1
- package/templates/sandcms/worker/local.ts +0 -1
- package/templates/sandcms/worker/wrangler.jsonc +0 -6
package/docs/package.md
CHANGED
|
@@ -4,46 +4,49 @@
|
|
|
4
4
|
|
|
5
5
|
## Publish from macOS
|
|
6
6
|
|
|
7
|
-
Use Bun **1.4.
|
|
7
|
+
Use Bun **1.4.4**; Node and npm are not needed. Bun reads npm credentials from `~/.npmrc` or `NPM_CONFIG_TOKEN`. Create a granular access token at npmjs.com with publish rights for `sandquist-group` and keep it out of the repository:
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
echo '//registry.npmjs.org/:_authToken=${NPM_TOKEN}' >> ~/.npmrc
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Run these commands from the repository root after pulling the changes:
|
|
8
14
|
|
|
9
15
|
```sh
|
|
10
16
|
bun --version
|
|
11
|
-
|
|
12
|
-
npm login --registry=https://registry.npmjs.org/
|
|
13
|
-
npm whoami --registry=https://registry.npmjs.org/
|
|
17
|
+
bun pm whoami
|
|
14
18
|
bun install --frozen-lockfile
|
|
15
19
|
bun run release:check
|
|
16
|
-
|
|
17
|
-
|
|
20
|
+
bun pm pack --dry-run
|
|
21
|
+
bun pm pack --destination /tmp
|
|
18
22
|
```
|
|
19
23
|
|
|
20
|
-
This release produces `/tmp/sandcms-0.
|
|
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.
|
|
21
25
|
|
|
22
26
|
Upload the archive you just built:
|
|
23
27
|
|
|
24
28
|
```sh
|
|
25
|
-
|
|
26
|
-
|
|
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
|
|
27
31
|
```
|
|
28
32
|
|
|
29
|
-
Complete
|
|
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.
|
|
30
34
|
|
|
31
|
-
For later releases, increment `version` in `package.json
|
|
35
|
+
For later releases, increment `version` in `package.json`, repeat the checks and packing, and publish the resulting archive filename. npm versions cannot be overwritten. The CLI reads its package version when creating starter dependencies and integration manifests.
|
|
32
36
|
|
|
33
37
|
## Create a starter from npm
|
|
34
38
|
|
|
35
|
-
After publishing,
|
|
39
|
+
After publishing, add a read token for the package to `~/.npmrc` (as above), then run:
|
|
36
40
|
|
|
37
41
|
```sh
|
|
38
|
-
|
|
39
|
-
bunx --bun --package sandcms@0.6.2 sandcms setup --cwd ./my-site
|
|
42
|
+
bunx --bun --package sandcms@0.7.0 sandcms setup --cwd ./my-site
|
|
40
43
|
cd my-site
|
|
41
44
|
bun run dev
|
|
42
45
|
```
|
|
43
46
|
|
|
44
|
-
Setup asks for the project name and initial local admin email. The generated site includes a minimal public home page, `/admin/[...path]`, `/api/cms/[...path]`, the server hook/integration, YAML blueprints, and a local database.
|
|
47
|
+
Setup asks for the project name and initial local admin email. The generated site includes a minimal public home page, `/admin/[...path]`, `/api/cms/[...path]`, the server hook/integration, YAML blueprints, a `Dockerfile`, and a local database. Uploads and image processing work locally with no extra service; media is stored next to the database. This is a Bun application; Node alone cannot run the CMS.
|
|
45
48
|
|
|
46
|
-
Setup also adds commented `SANDCMS_TRUSTED_PROXY_HEADER
|
|
49
|
+
Setup also adds commented `SANDCMS_TRUSTED_PROXY_HEADER` and `ADDRESS_HEADER` examples to `.env.local`. They stay disabled for local development. In production, set both to the client IP header your reverse proxy sets; follow the [client IP setup and check](deployment.md#client-ip-behind-a-reverse-proxy). Rerunning setup adds missing examples without duplicating existing ones or overwriting configured proxy settings.
|
|
47
50
|
|
|
48
51
|
For an existing SvelteKit project, run the same setup command with `--cwd` pointing to that project and review `sandcms/setup-report.md`. Inside an installed project, use the local CLI:
|
|
49
52
|
|
|
@@ -67,11 +70,11 @@ cd /tmp/my-sandcms-site
|
|
|
67
70
|
bun run dev
|
|
68
71
|
```
|
|
69
72
|
|
|
70
|
-
`setup --dry-run --name "Example"` only prints the integration plan. `--yes` skips optional prompts
|
|
73
|
+
`setup --dry-run --name "Example"` only prints the integration plan. `--yes` skips optional prompts; `--skip-install` is useful in fixture tests. `--email` optionally supplies a local bootstrap email. Never pass passwords as command arguments.
|
|
71
74
|
|
|
72
75
|
A fresh site receives SvelteKit, TypeScript, the pinned Bun adapter, a public starter page, CMS route glue, starter YAML, environment values, and a local database. An existing site must already be a SvelteKit project. Setup checks reserved routes and leaves custom hooks, adapters, config, and public routes intact. Read `sandcms/setup-report.md` and apply the hook composition patch if needed. Existing JavaScript hooks are recognized; setup does not shadow them with a TypeScript file. Tailwind, ESLint, Prettier, Vitest, and Playwright are individually optional website add-ons.
|
|
73
76
|
|
|
74
|
-
The built package contains Svelte admin components, compiled CSS/fonts, server code, CLI, reviewed migrations, Worker source, and templates. `bun run test:package` installs and builds it in a clean fixture without Tailwind and verifies a customized existing site.
|
|
77
|
+
The built package contains Svelte admin components, compiled CSS/fonts, server code, the media processor entry (`sandcms/media-processor`), CLI, reviewed migrations, the deprecated Worker source, and templates. `sharp` is a dependency; its prebuilt binary is installed for the build platform, so install dependencies inside the image (as the starter `Dockerfile` does), not on a different OS. `bun run test:package` installs and builds it in a clean fixture without Tailwind and verifies a customized existing site.
|
|
75
78
|
|
|
76
79
|
## Private registry use
|
|
77
80
|
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
# SandCMS 0.7.0 plan: self-contained media on any Docker host
|
|
2
|
+
|
|
3
|
+
Status: **proposed** (2026-11-17).
|
|
4
|
+
|
|
5
|
+
0.7.0 removes the Cloudflare Worker and R2 from SandCMS. A site becomes one container with one persistent volume, and runs on any Docker host. We recommend [Dokploy](https://dokploy.com) or [Openship](https://openship.io) as the host platform; nothing in the package depends on either.
|
|
6
|
+
|
|
7
|
+
## 1. Goals
|
|
8
|
+
|
|
9
|
+
- **One container, one volume.** SQLite, image originals, variants and database snapshots live under `/data`. No external service is needed to run a site.
|
|
10
|
+
- **Full-resolution originals.** Editors upload camera originals of 70 MB and more, including TIFF, without compressing first. The site serves optimized variants.
|
|
11
|
+
- **Runs behind any reverse proxy with default settings.** No raised timeouts or body limits on the proxy.
|
|
12
|
+
- **Preview first, launch later.** A site can start on a temporary hostname. Changing its domain is an environment change and a restart, with no rebuild.
|
|
13
|
+
- **Safe with plain volume backups.** A file-level copy of the volume, taken while the site runs, is always restorable.
|
|
14
|
+
|
|
15
|
+
Non-goals for 0.7.0: an S3 media backend (the storage interface leaves room for one), multiple instances per site, video, HEIC input, platform-specific automation.
|
|
16
|
+
|
|
17
|
+
## 2. Decisions
|
|
18
|
+
|
|
19
|
+
| # | Decision | Why |
|
|
20
|
+
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
21
|
+
| D1 | Media is stored on the site volume (`/data/media`), behind a storage interface. | One volume to back up. An S3 backend can be added later without touching callers. |
|
|
22
|
+
| D2 | Images are processed with sharp (libvips) in a child process, one image at a time. | Removes Cloudflare's 100 MP, 100 MB and TIFF limits. A huge decode can't take down the web server. |
|
|
23
|
+
| D3 | Uploads go to the site itself in **8 MB chunks**, resumable, authorized by a signed ticket. A session or an API key may upload. | No request is long or large enough to hit a proxy's default limits. Survives restarts and bad connections, and keeps the API-key flow in `docs/api.md`. |
|
|
24
|
+
| D4 | `BODY_SIZE_LIMIT=10M`; `cmsHandle` enforces 1 MB on every route except the chunk route. | The Bun adapter's limit applies to all routes at once (`adapter-bun/src/index.js:51`). |
|
|
25
|
+
| D5 | **Overlapping deploys are allowed.** Old and new containers may share the volume briefly; background work coordinates through database leases (processor, snapshot). One long-running replica per site. | Openship deploys run-new-then-swap on Docker servers. SQLite handles two processes on a local volume, and migrations are additive. (An earlier draft refused a second server with an instance lock; that broke every overlapping deploy.) |
|
|
26
|
+
| D6 | The app writes a verified database snapshot **every hour** to `/data/backups/latest.sqlite`. | A file copy of a live SQLite database can be torn. With the snapshot inside the volume, any volume backup contains a consistent database. |
|
|
27
|
+
| D7 | Variants live on the same volume as originals. | Restores need no re-encoding. |
|
|
28
|
+
| D8 | The starter ships a `Dockerfile` with a `HEALTHCHECK`. | Works on any Docker host. `railpack.json` stays for existing sites. |
|
|
29
|
+
| D9 | The site derives its public origin from the request, and redirects other hostnames to `SANDCMS_ORIGIN`. | A domain change needs no rebuild; preview and extra domains redirect without proxy rules. |
|
|
30
|
+
| D10 | Existing R2 media is imported once with `sandcms media import-r2`, keeping asset IDs, variant keys and the preset version. Images are unavailable during the import. | Public URLs and published content are unchanged. A short maintenance window is simpler than a fallback path. |
|
|
31
|
+
| D11 | The Worker options, env variables and package exports stay, deprecated, through 0.7.x. | Existing integrations pass them, and the old Worker must stay deployable until the import is verified. |
|
|
32
|
+
|
|
33
|
+
## 3. Architecture
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
Visitor ──HTTPS──▶ reverse proxy (TLS, default settings)
|
|
37
|
+
│
|
|
38
|
+
▼
|
|
39
|
+
SandCMS container (Bun, single instance, health-checked)
|
|
40
|
+
├─ public site + /admin + /api/cms
|
|
41
|
+
├─ cmsHandle: canonical host · body guard · media delivery · chunk upload
|
|
42
|
+
├─ job runner ──spawn──▶ media processor child (sharp)
|
|
43
|
+
└─ snapshot scheduler (hourly)
|
|
44
|
+
│
|
|
45
|
+
▼
|
|
46
|
+
/data (one persistent volume per site)
|
|
47
|
+
sandcms.sqlite (+wal/shm, guard) site-id instance.lock
|
|
48
|
+
media/originals/{id}
|
|
49
|
+
media/variants/{id}/{version}/{preset}-{size}.{fmt}
|
|
50
|
+
media/tmp/{id}/{attempt}/
|
|
51
|
+
backups/latest.sqlite · previous.sqlite
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## 4. Media
|
|
55
|
+
|
|
56
|
+
The Worker is reached through one closure, `worker()` in `src/lib/server/media/service.ts:61-74`, with 8 call sites. It is replaced by two modules. The job, lease, version and publication model stays.
|
|
57
|
+
|
|
58
|
+
### 4.1 Storage (`src/lib/server/media/storage.ts`)
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
interface MediaStorage {
|
|
62
|
+
writeChunk(id, attempt, index, body: ReadableStream, bytes): Promise<void>;
|
|
63
|
+
assemble(id, attempt, totalBytes): Promise<string>; // path of the staged file
|
|
64
|
+
promoteOriginal(id, stagedPath): Promise<void>; // fails if an original exists
|
|
65
|
+
original(id): BunFile | null;
|
|
66
|
+
writeVariant(key, tmpPath): Promise<{ etag: string }>;
|
|
67
|
+
variant(key): BunFile | null;
|
|
68
|
+
removeAsset(id): Promise<void>;
|
|
69
|
+
sweepTmp(olderThan: Date): Promise<number>;
|
|
70
|
+
usage(): Promise<{ bytes: number; free: number }>;
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- 0.7.0 ships the local-disk implementation only. The root is `SANDCMS_MEDIA_DIR`, defaulting to `<dirname(SANDCMS_DATABASE)>/media`.
|
|
75
|
+
- **Durability.** Files are written to a temporary path, `fsync`ed, renamed, and the directory `fsync`ed, before the database says they exist.
|
|
76
|
+
- **No overwrite.** `promoteOriginal` uses `link()` + `unlink()`, which fails if the original exists, matching the Worker's conditional put (`worker/index.ts:338, 362`).
|
|
77
|
+
- **Metadata in SQLite.** Original `width`, `height` and `uploadAttempt` become nullable `media` columns in retained migration `0009_local_media` (`bun run db:generate --name local_media`). Each variant's `etag` (short sha256) goes into the existing `variants` and `jobs.result` JSON.
|
|
78
|
+
- **Deletion.** After every promote or variant write, the parent process re-checks the media row and removes the file if the row is `deleting` or missing. `media_deletions` rows cascade away with the media row (`schema.ts:333`), so a missing row counts as deleted.
|
|
79
|
+
- **Disk guard.** In-flight upload bytes are reserved in `upload_sessions`. An upload is refused unless free space ≥ `3 × bytes` + reserved bytes + 5 GB, and within the optional `media.maxStorage` quota. Usage and free space appear in the admin and in `doctor`.
|
|
80
|
+
- `sweepTmp` runs at start and hourly.
|
|
81
|
+
|
|
82
|
+
### 4.2 Upload
|
|
83
|
+
|
|
84
|
+
1. `POST /api/cms/media/upload` keeps its validation (blueprint `accept`, `uploadLimit`, MIME) and returns an absolute URL:
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"id": "…",
|
|
88
|
+
"url": "https://site/api/cms/media/upload/{id}",
|
|
89
|
+
"chunkSize": 8388608,
|
|
90
|
+
"headers": { "x-sandcms-upload": "<ticket>" }
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
The ticket is an HMAC (key derived from `SANDCMS_SECRET`) over `id`, `attempt`, `mime`, `bytes`, the user or API-key ID, and an expiry. It travels in a header, so it stays out of access logs.
|
|
94
|
+
2. `PUT {url}?index=N` stores one chunk. `cmsHandle` handles it before SvelteKit reads the body.
|
|
95
|
+
- Authorized by the ticket plus an admin/editor session (with the origin check) or an API key with `cms:write`. `hooks.ts:30-49` and `api-access.ts` gain this route.
|
|
96
|
+
- Bytes are counted while streaming, so a missing `Content-Length` (HTTP/2, HTTP/3) is fine. A chunk over `chunkSize` is rejected.
|
|
97
|
+
- Each chunk is a file `tmp/{id}/{attempt}/{index}`; re-sending replaces it.
|
|
98
|
+
- The first chunk moves the session from `uploading` to `receiving` and takes its lease; later chunks extend it. The expiry branch (`runner.ts:28-63`) and the deletion runner (`deletions.ts:43`) respect that lease.
|
|
99
|
+
- `GET {url}` lists stored chunk indexes, for resume.
|
|
100
|
+
3. `POST /api/cms/media/upload/complete` assembles the chunks, verifies the total length, and sets the session to `pending`. The existing runner branch (`runner.ts:79-128`) validates and promotes asynchronously: SVGs through the sanitizer (moved from `src/lib/worker/svg.ts` to `src/lib/server/media/svg.ts`), raster files through the processor.
|
|
101
|
+
4. `cms.media.upload(file)` (`service.ts:209-219`) writes through the storage module directly.
|
|
102
|
+
5. **Body guard.** Any other request over `SANDCMS_REQUEST_LIMIT` (default 1 MB) gets 413 before its body is read; bodies without a length are counted and cut off. `cmsHandle` must run first in `sequence()`.
|
|
103
|
+
6. The admin client (`src/lib/admin/uploads.ts`) sends chunks sequentially with per-chunk retry and a progress bar.
|
|
104
|
+
|
|
105
|
+
Accepted input: JPEG, PNG, WebP, AVIF, GIF, **TIFF**, SVG. Output stays WebP, AVIF and JPEG. Defaults: `uploadLimit` 100 MB (up to 500 MB), `media.maxPixels` 100 MP.
|
|
106
|
+
|
|
107
|
+
### 4.3 Processing (`src/lib/server/media/processor.ts` + child entry)
|
|
108
|
+
|
|
109
|
+
- The runner keeps `jobs`, leases, retries and batching (`runner.ts:182-293`). The Worker batch call becomes `processor.render(id, version, specs)`.
|
|
110
|
+
- **One processor per site.** Render work is claimed only when the child is idle. A database lease stops the server and a CLI command (`media rebuild`, `import-r2`) from processing at once.
|
|
111
|
+
- **Child process.** Spawned per batch over Bun's `ipc` channel, with `sharp.cache(false)` and `oom_score_adj` 1000, so a memory limit kills the child and not the web server. On exit the parent fails the batch at once. Two kills in a row mark the asset failed with a clear message.
|
|
112
|
+
- **Loader allowlist.** Block all libvips loaders, then unblock JPEG, PNG, WebP, AVIF, GIF and TIFF. `metadata().format` must match the declared MIME, with `failOn: 'error'`. Otherwise an SVG claiming to be a PNG would be rasterized.
|
|
113
|
+
- **Decode once.** Each batch decodes the original into a master image at the largest requested size (EXIF-rotated, sRGB, temporary lossless file), derives each spec from it sequentially, and reports each variant as it finishes. The parent `fsync`s, renames and commits it, and extends the lease. A retry skips finished variants. (Measured: sharp's `clone()` re-decodes per pipeline, and `sharp.concurrency(1)` does not serialize pipelines.)
|
|
114
|
+
- `inspect` ports `dimensions()` (`worker/index.ts:103-128`): orientation-corrected size and the max-pixels rejection. Stored dimensions come from sharp's output.
|
|
115
|
+
- `render` reuses the size math from `renderVariant` (`worker/index.ts:191-251`) as a shared function. Never upscale. Focal-point crops are a resize followed by `extract`.
|
|
116
|
+
- **Behaviour changes from Cloudflare**, for the release notes: animated GIF and WebP inputs are flattened to their first frame; metadata is stripped except copyright and artist EXIF.
|
|
117
|
+
- Originals are never modified, and TIFF originals are never served.
|
|
118
|
+
- sharp becomes a direct dependency. The child entry must survive the consumer's Vite SSR bundle.
|
|
119
|
+
|
|
120
|
+
### 4.4 Delivery
|
|
121
|
+
|
|
122
|
+
`deliver()` (`service.ts:410-440`):
|
|
123
|
+
|
|
124
|
+
- keeps the variant-membership and `isPublic()` checks;
|
|
125
|
+
- returns the `Bun.file` response with `Content-Length`, and maps a missing file to 404;
|
|
126
|
+
- answers `If-None-Match` from the stored `etag`, porting `worker/index.ts:395-404`;
|
|
127
|
+
- sets the headers the Worker used to set (`worker/index.ts:386-392`): `Content-Type`, `Content-Security-Policy: default-src 'none'; style-src 'none'; sandbox`, `Cross-Origin-Resource-Policy`, `X-Content-Type-Options: nosniff`.
|
|
128
|
+
|
|
129
|
+
`delivery.ts` stops deleting `Content-Length` and re-wrapping the body (`delivery.ts:23-25`). Cache headers and URLs (`/_sandcms/media/{id}/{version}/{preset}-{size}.{fmt}`) are unchanged.
|
|
130
|
+
|
|
131
|
+
### 4.5 Configuration and compatibility
|
|
132
|
+
|
|
133
|
+
- New config: `media.maxPixels`, `media.maxStorage`, a higher allowed `media.uploadLimit`. `media.workerUrl` becomes optional and ignored (`load.ts:222`).
|
|
134
|
+
- New env: `SANDCMS_MEDIA_DIR`, `SANDCMS_REQUEST_LIMIT`, `SANDCMS_INDEXING`, `SANDCMS_BOOTSTRAP_EMAIL`.
|
|
135
|
+
- **Deprecated, kept through 0.7.x (D11):** `createCMS({ workerToken, workerUrl })`, the `SANDCMS_WORKER_*` declarations, and the `./worker` and `./worker/local` exports.
|
|
136
|
+
- **Removed:** `src/lib/cli/cloudflare.ts`, `sandcms worker update`, the Cloudflare prompt in setup, `templates/sandcms/worker/*` for new sites, the `wrangler` dev dependency, the dead `workerUrl` prop in the admin (`client.ts:44-46`).
|
|
137
|
+
- Setup and upgrade leave project-owned `sandcms/worker/*` files alone and report them as removable.
|
|
138
|
+
- New background work starts from `media.start()`, which existing integrations already call, and never from CLI commands.
|
|
139
|
+
|
|
140
|
+
### 4.6 Import from R2 (`sandcms media import-r2`)
|
|
141
|
+
|
|
142
|
+
Run once per existing site, in a maintenance window, while the old Worker is still deployed.
|
|
143
|
+
|
|
144
|
+
- Refuses to start while `upload_sessions` or legacy `uploads` rows are pending.
|
|
145
|
+
- Holds the processor lease, so nothing renders during the import.
|
|
146
|
+
- Raster originals come through the Worker's `/internal/source/{id}`, with URLs minted locally from `SANDCMS_WORKER_TOKEN` (`src/lib/worker/source.ts`).
|
|
147
|
+
- SVG originals are not served by that route (`worker/index.ts:278`); the already sanitized `svg-1.svg` variant becomes both original and variant.
|
|
148
|
+
- Variants come through `/internal/media/{key}` for every ready `jobs.result`. Assets in `deleting` are skipped.
|
|
149
|
+
- Fills `width`, `height` and `etag`; keeps `activeVersion` and the `'remote-transform-v2:'` salt (`presets.ts:6`).
|
|
150
|
+
- Resumable and idempotent; ends by verifying every original and variant (existence and size).
|
|
151
|
+
|
|
152
|
+
`sandcms media rebuild --force` re-encodes everything with sharp on request.
|
|
153
|
+
|
|
154
|
+
## 5. Platform features
|
|
155
|
+
|
|
156
|
+
- **Overlapping deploys (D5).** No instance lock: a second server on the same volume serves normally. The processor and the hourly snapshot each take a database lease, so only one server does that work at a time.
|
|
157
|
+
- **Site identity.** On first start the app writes `/data/site-id` (a random ID plus the project name) and later refuses to run if the project name differs. In production it refuses to create a new database when the data directory is not a mount. Both catch a shared or missing volume before content is written.
|
|
158
|
+
- **Request origin (D9).** The starter stops baking `paths.origin` into the build (`cli/scaffold.ts:55`). The Bun adapter then derives the origin from the `Host` header (`adapter-bun/src/handler.js:44-52`). `sandcms upgrade` reports the change for existing `vite.config.ts` files.
|
|
159
|
+
- **Canonical host.** A request whose `Host` (lowercased, default port stripped) isn't `SANDCMS_ORIGIN`'s host gets a 308 to the same URL on the origin, with `Cache-Control: no-store`. Exceptions: the health route, and development. Prerendered pages and `static/` files bypass hooks; `doctor` warns when a site has them.
|
|
160
|
+
- **Indexing.** `SANDCMS_INDEXING=false` sends `X-Robots-Tag: noindex` and a disallow-all `robots.txt`. Unset means indexed.
|
|
161
|
+
- **Health.** `GET /_sandcms/health` returns 200 when the process serves and the database opens. Liveness only: disk and media problems show in the admin and `doctor`, so a full disk doesn't restart the site in a loop.
|
|
162
|
+
- **Snapshots (D6).** Hourly: rotate `latest.sqlite` to `previous.sqlite`, then write a verified snapshot with `backup()` (`src/lib/cli/backup.ts:27-44`). Catches up at start. `before-migrate` snapshots are pruned to the newest 3.
|
|
163
|
+
- **Bootstrap.** With `SANDCMS_BOOTSTRAP_EMAIL` set and no users, the first start creates the admin and logs a one-time password. No shell access is needed for a new site.
|
|
164
|
+
- **Dockerfile (D8).** The starter gets a multi-stage `Dockerfile` on the pinned Bun image: install with the frozen lockfile, build, run `bun build/index.js`, `HEALTHCHECK` on `/_sandcms/health`, no `VOLUME` instruction.
|
|
165
|
+
- **Doctor.** Drops the Worker and Railpack-only checks. Adds: media directory, disk usage and quota, snapshot age, `BODY_SIZE_LIMIT` ≥ chunk size, trusted-header configuration, site-id.
|
|
166
|
+
|
|
167
|
+
## 6. Hosting
|
|
168
|
+
|
|
169
|
+
### 6.1 What the host must provide
|
|
170
|
+
|
|
171
|
+
| Requirement | Detail |
|
|
172
|
+
| ------------- | -------------------------------------------------------------------------------------------------- |
|
|
173
|
+
| Container | Built from the site's `Dockerfile` (or Railpack), one replica |
|
|
174
|
+
| Volume | One persistent volume mounted at `/data`, on a local filesystem, **used by this site only** |
|
|
175
|
+
| Deploys | Replace the container: stop the old one, then start the new one. Stop timeout ≥ 30 s |
|
|
176
|
+
| Reverse proxy | TLS, routes the site's hostnames, passes `Host` unchanged, overwrites the client-IP header it sets |
|
|
177
|
+
| Health check | The image's `HEALTHCHECK`, or `GET /_sandcms/health` |
|
|
178
|
+
| Memory | A container memory limit that covers one decode at `media.maxPixels` (measured in §8) |
|
|
179
|
+
| Backups | A scheduled copy of the whole volume to off-server storage |
|
|
180
|
+
|
|
181
|
+
Environment:
|
|
182
|
+
|
|
183
|
+
```dotenv
|
|
184
|
+
SANDCMS_ORIGIN=https://www.example.com
|
|
185
|
+
SANDCMS_SECRET=<32+ random characters>
|
|
186
|
+
SANDCMS_DATABASE=/data/sandcms.sqlite
|
|
187
|
+
SANDCMS_AUTO_MIGRATE=true
|
|
188
|
+
BODY_SIZE_LIMIT=10M
|
|
189
|
+
SANDCMS_TRUSTED_PROXY_HEADER=x-real-ip # the header your proxy sets
|
|
190
|
+
ADDRESS_HEADER=x-real-ip
|
|
191
|
+
# SANDCMS_INDEXING=false # preview sites only
|
|
192
|
+
# SANDCMS_BOOTSTRAP_EMAIL=you@example.com # first start only
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### 6.2 Recommended platforms
|
|
196
|
+
|
|
197
|
+
Dokploy and Openship both provide everything in §6.1: Git deploys, a reverse proxy with Let's Encrypt, named volumes, scheduled volume backups to S3-compatible storage, and rollback. Platform notes:
|
|
198
|
+
|
|
199
|
+
- **Dokploy.** Volume names are global on a server, so give each site its own (`sandcms-<slug>-data`). The default update order starts the new container first; set it to stop-first. Rollback needs a registry configured. Volume backups are full archives.
|
|
200
|
+
- **Openship.** Supports incremental volume backups and validates a restore before replacing data. Not yet tested by us with SandCMS.
|
|
201
|
+
|
|
202
|
+
### 6.3 Site lifecycle
|
|
203
|
+
|
|
204
|
+
1. **Create** the app with its own volume and the environment above, on a preview hostname, with `SANDCMS_INDEXING=false` and `SANDCMS_BOOTSTRAP_EMAIL`. First start migrates the database and creates the admin.
|
|
205
|
+
2. **Launch:** point the domain's DNS at the host, add the hostnames on the platform, set `SANDCMS_ORIGIN`, remove `SANDCMS_INDEXING` and `SANDCMS_BOOTSTRAP_EMAIL`, restart. Other hostnames now redirect to the origin.
|
|
206
|
+
3. **Roll back** a bad deploy with the platform's rollback. If that deploy applied a migration, the old code refuses the newer database (`store.ts:91-92`); also restore the `before-migrate` snapshot with `sandcms restore`.
|
|
207
|
+
|
|
208
|
+
### 6.4 Backup and restore
|
|
209
|
+
|
|
210
|
+
- Back up the whole volume on a schedule. The site may keep running.
|
|
211
|
+
- **Restore:** stop the site, restore the volume, run `sandcms restore --from /data/backups/latest.sqlite`, start the site. Always restore the database from the snapshot: the copy of the live database inside a volume backup can be torn.
|
|
212
|
+
- Up to one hour of content edits can be lost relative to the media files in the same backup. `sandcms media verify` reports media rows without files after a restore.
|
|
213
|
+
|
|
214
|
+
## 7. Upgrading a site from 0.6
|
|
215
|
+
|
|
216
|
+
1. Check that no uploads are pending, and take a backup.
|
|
217
|
+
2. Make sure the volume has free space of at least 3 × the site's current media.
|
|
218
|
+
3. Install `sandcms@0.7.0`, run `sandcms upgrade --check`, then `sandcms upgrade`. Confirm `cmsHandle` runs first in `sequence()`, and remove `paths.origin` from `vite.config.ts`.
|
|
219
|
+
4. Set `BODY_SIZE_LIMIT=10M` and switch the host to stop-then-start deploys.
|
|
220
|
+
5. Deploy with `SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` still set. Migration `0009_local_media` applies; existing data is preserved.
|
|
221
|
+
6. Run `sandcms media import-r2` and check the site.
|
|
222
|
+
7. Remove the Worker env and redeploy. Delete the Worker and its R2 bucket once a restore from backup has been verified to contain originals.
|
|
223
|
+
|
|
224
|
+
Going back to 0.6 after step 5 means restoring the `before-migrate` snapshot along with the old image. `docs/upgrades.md`, `docs/deployment.md`, `docs/media.md` and the README are rewritten for this release; `docs/cloudflare.md` is reduced to the legacy import.
|
|
225
|
+
|
|
226
|
+
## 8. Testing
|
|
227
|
+
|
|
228
|
+
- **Unit:**
|
|
229
|
+
- storage: durable writes, no-overwrite promote, sweep, usage, reservations and quota, deletion with a missing row;
|
|
230
|
+
- upload: ticket signature, expiry and user binding; session and API-key authorization; chunk retry, resume, oversize chunk, missing `Content-Length`; session expiry and deletion during an upload;
|
|
231
|
+
- processor fixtures: JPEG with EXIF orientation, 16-bit TIFF, CMYK JPEG, PNG with alpha, animated GIF, an SVG declared as PNG, rejection above `maxPixels`, corrupt file;
|
|
232
|
+
- processor lifecycle: child crash mid-batch, kill by signal, retry skipping finished variants, the processor lease against a CLI command;
|
|
233
|
+
- render dimensions matching current Worker results;
|
|
234
|
+
- body guard on non-upload routes;
|
|
235
|
+
- delivery: ETag/304, security headers, `Content-Length`, missing file, publication revoked;
|
|
236
|
+
- import against a fake Worker: SVG, originals without stored dimensions, non-active ready versions, errors with resume;
|
|
237
|
+
- instance lock (second process refused, released on crash), site-id mismatch, snapshots (rotation, catch-up, not started by CLI), canonical host, indexing unset vs `false`.
|
|
238
|
+
- **Migrations, per AGENTS.md:** fresh initialization, upgrade from 0.6.3 with data, repeated migration, rollback after a failed migration, rejection of incompatible databases, and a 0.6.3 build rejecting a 0.7 database.
|
|
239
|
+
- **e2e:** remove wrangler from `scripts/e2e-server.ts`. Cover a 70 MB chunked upload with progress, an interrupted upload that resumes, TIFF → variants, an API-key upload, and that a draft image isn't public.
|
|
240
|
+
- **Package and container:** `scripts/test-package.ts` builds a consumer site and processes an image through the bundled child. `scripts/test-container.ts` builds the starter `Dockerfile`, processes a large image under a memory limit, and checks the web process survives a child out-of-memory kill.
|
|
241
|
+
- **Load:** process real 70 MB originals on a production-sized server; record peak memory and time to set the documented memory limit and the `maxPixels` default.
|
|
242
|
+
- **Release gate:** `bun run release:check`, then `bun run build` and `bun run test:e2e`.
|
|
243
|
+
|
|
244
|
+
## 9. Work order
|
|
245
|
+
|
|
246
|
+
| Step | Scope |
|
|
247
|
+
| ---- | ----------------------------------------------------------------------- |
|
|
248
|
+
| 1 | Storage module, migration `0009`, delivery from disk |
|
|
249
|
+
| 2 | Processor child, runner integration, deletion and lease changes |
|
|
250
|
+
| 3 | Chunked upload: server routes, body guard, admin client, API-key access |
|
|
251
|
+
| 4 | Platform features (§5), starter `Dockerfile`, doctor |
|
|
252
|
+
| 5 | `media import-r2`, `media verify`, `media rebuild --force` |
|
|
253
|
+
| 6 | Remove Cloudflare setup; deprecations; setup/upgrade templates |
|
|
254
|
+
| 7 | Tests (§8), docs, release notes, load test |
|
|
255
|
+
|
|
256
|
+
## 10. Accepted risks and open items
|
|
257
|
+
|
|
258
|
+
- **Single volume, single server per site.** Recovery depends on the host's volume backups.
|
|
259
|
+
- **No CDN or request filtering** in front of sites unless the operator adds one.
|
|
260
|
+
- **Images are unavailable during the one-time R2 import** (D10).
|
|
261
|
+
- **Mixed encoders after import.** Imported variants were rendered by Cloudflare and later ones by sharp, under the same version, until a forced rebuild.
|
|
262
|
+
- **HEIC is not supported**: sharp's prebuilt binaries can't decode HEVC.
|
|
263
|
+
- **Open:** the memory limit and `maxPixels` default, set by the load test.
|
|
264
|
+
- **Later:** S3 media backend; removal of the deprecated Worker surface; optional host automation.
|
package/docs/releases.md
CHANGED
|
@@ -1,5 +1,31 @@
|
|
|
1
1
|
# Release notes
|
|
2
2
|
|
|
3
|
+
## 0.7.0
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
Stores media on the site volume. Originals and variants are files under `SANDCMS_MEDIA_DIR` (default `media/` next to the database), written durably before the database records them. Width, height and variant ETags are stored in SQLite. Uploads are refused when free disk space or the new optional `media.maxStorage` quota would run out; usage appears in the admin and in `sandcms doctor`. See [media storage](media.md#storage).
|
|
8
|
+
|
|
9
|
+
Processes images with sharp in a child process, one image at a time, so a large decode cannot take down the web server. Each original is decoded once per batch. TIFF input is now accepted, `media.uploadLimit` may be raised to 500 MB, and the new `media.maxPixels` (default 100 MP) limits decoded size. Variant URLs, presets and the preset version are unchanged. **Behaviour changes:** animated GIF and WebP inputs are flattened to their first frame; metadata is stripped from variants except EXIF copyright and artist; HEIC remains unsupported. See [changes from Cloudflare processing](media.md#changes-from-cloudflare-processing-070).
|
|
10
|
+
|
|
11
|
+
Uploads go to the site in 8 MB chunks with a signed ticket, so reverse proxies need no raised limits. Uploads show progress, retry failed chunks and resume after interruptions or restarts. API clients use the same flow with a write key; the earlier single presigned PUT is gone. See [media uploads](api.md#media-uploads). Requests other than upload chunks are limited to 1 MB (`SANDCMS_REQUEST_LIMIT`); set `BODY_SIZE_LIMIT=10M`.
|
|
12
|
+
|
|
13
|
+
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
|
+
|
|
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).
|
|
16
|
+
|
|
17
|
+
**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
|
+
|
|
19
|
+
## 0.6.3
|
|
20
|
+
|
|
21
|
+
This patch release polishes the admin interface and adds user removal. There is no SQL migration, Worker protocol change or configuration change; upgrading from 0.6.2 only requires installing the package and rebuilding; see the [0.6.3 upgrade checklist](upgrades.md#063-upgrade-checklist). Stored data and project-owned YAML are preserved.
|
|
22
|
+
|
|
23
|
+
Polishes the admin. Pages drop decorative eyebrows, taglines and redundant helper text, and sections, tables and rows share aligned borders, padding and fixed row heights. The sidebar gains an account menu with settings and sign out, the top bar has a wider search trigger and a breadcrumb without the redundant Overview, and link fields are edited in a dialog behind a one-line summary. Date fields use a calendar picker. The editor labels its primary action **Publish** and moves unpublish, duplicate and delete into a menu. The title-to-slug auto-fill now works across editor tabs.
|
|
24
|
+
|
|
25
|
+
Reworks two-factor setup on **Account & security** as a step-by-step dialog: confirm the password, scan a QR code or copy the setup key, enter the six-digit code (submitted automatically), then copy or download the recovery codes. Disabling two-factor asks for the password in a dialog. Copy buttons for setup keys and API key secrets now also work outside a secure context such as plain HTTP.
|
|
26
|
+
|
|
27
|
+
Adds user removal. Administrators can remove another user from the row menu on the Users page after confirming. The `users/delete` endpoint is admin-only, refuses to remove the signed-in account or the last administrator, and audits the removal. The user's sessions, credentials, two-factor secrets and API keys are deleted with the account. No schema migration is required.
|
|
28
|
+
|
|
3
29
|
## 0.6.2
|
|
4
30
|
|
|
5
31
|
This patch release speeds up media processing and the admin, and validates the website environment on start. Before upgrading from 0.6.1, check every environment's SandCMS variables, deploy the protocol-6 Worker with `sandcms worker update`, then apply retained migrations `0007` and `0008` before restarting the website; see the [0.6.2 upgrade checklist](upgrades.md#062-upgrade-checklist). Stored data and project-owned YAML are preserved.
|
|
@@ -51,7 +77,7 @@ Upgrades the application and generated starters to SvelteKit 3.0.0, `@sveltejs/p
|
|
|
51
77
|
|
|
52
78
|
Admin uploads now use metadata initialization, a 15-minute presigned PUT directly from the browser to private R2 staging, and idempotent completion. The website no longer buffers file bodies or stores new originals in SQLite. Durable finalization validates a private snapshot, preserves retry/restart recovery, and prevents a reused upload URL from replacing an accepted original.
|
|
53
79
|
|
|
54
|
-
Run the retained `0003_direct_r2_uploads.sql` migration; it preserves existing media and pending legacy BLOB transfers. Deploy the protocol-4 Worker first (it also accepts protocol 3), configure bucket-scoped R2 signing credentials, PUT CORS for the admin origin, and a one-day `incoming/` lifecycle rule before deploying the website. The local Worker now uses `sandcms/worker/local.ts`. See
|
|
80
|
+
Run the retained `0003_direct_r2_uploads.sql` migration; it preserves existing media and pending legacy BLOB transfers. Deploy the protocol-4 Worker first (it also accepts protocol 3), configure bucket-scoped R2 signing credentials, PUT CORS for the admin origin, and a one-day `incoming/` lifecycle rule before deploying the website. The local Worker now uses `sandcms/worker/local.ts`. See the 0.6 version of `docs/cloudflare.md`.
|
|
55
81
|
|
|
56
82
|
Fixes large raster uploads failing with “file too large” during dimension inspection. Upload validation and legacy-original rebuilds now use remote JSON metadata transforms instead of `IMAGES.info()`. New originals retain their dimensions in R2 metadata for variant generation. The 100 MB / 100 MP limits and private originals remain unchanged. Deploy with `sandcms worker update`; the `IMAGES` binding is no longer required.
|
|
57
83
|
|
package/docs/upgrades.md
CHANGED
|
@@ -1,5 +1,45 @@
|
|
|
1
1
|
# Updates and generated files
|
|
2
2
|
|
|
3
|
+
## 0.7.0 upgrade checklist
|
|
4
|
+
|
|
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).
|
|
6
|
+
|
|
7
|
+
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
|
+
2. Make sure the volume has free space of at least **three times** the site's current media in R2.
|
|
9
|
+
3. Install `sandcms@0.7.0`, review `sandcms upgrade --check`, then run `sandcms upgrade`. Merge into customized files:
|
|
10
|
+
- `src/hooks.server.ts`: `cmsHandle` must be the **first** handle in `sequence()`. It enforces request size limits and serves health checks, host redirects, upload chunks and media before other hooks.
|
|
11
|
+
- `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
|
+
- 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
|
+
- 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`.
|
|
15
|
+
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.
|
|
17
|
+
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
|
+
|
|
19
|
+
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`.
|
|
20
|
+
|
|
21
|
+
### Local media
|
|
22
|
+
|
|
23
|
+
`0009_local_media.sql` adds nullable `width`, `height` and `uploadAttempt` columns to `media` and a `leases` table for the single media processor. Existing media rows, jobs and variant sets are unchanged; the import fills `width`, `height` and variant ETags. Asset IDs, variant keys and preset versions stay the same, so published content and public image URLs keep working.
|
|
24
|
+
|
|
25
|
+
- **Uploads** are chunked through the site; the R2 signing secrets, bucket CORS and lifecycle rules are no longer used. Custom API clients must switch to the [chunked upload flow](api.md#media-uploads).
|
|
26
|
+
- **Processing** uses sharp in a child process. TIFF is accepted by blueprints that allow it: file blueprints without an `accept` list accept it automatically, while project-owned blueprints with an explicit `accept` list (such as the starter's `sandcms/blueprints/files/image.yaml`) need `image/tiff` added; `uploadLimit` may now be up to 500 MB, and new `media.maxPixels` (default 100 MP) and `media.maxStorage` settings limit decoded size and total storage. See [the behaviour changes](media.md#changes-from-cloudflare-processing-070).
|
|
27
|
+
- **New environment variables:** `SANDCMS_MEDIA_DIR`, `SANDCMS_REQUEST_LIMIT`, `SANDCMS_INDEXING`, `SANDCMS_BOOTSTRAP_EMAIL`, `SANDCMS_CANONICAL_REDIRECT`, `SANDCMS_SITE_RENAME`, `SANDCMS_ALLOW_UNMOUNTED_DATA`; see [environment](deployment.md#environment).
|
|
28
|
+
- **Domains:** the site now redirects hostnames other than `SANDCMS_ORIGIN`'s with a 308. Add every hostname to the proxy, then set `SANDCMS_ORIGIN` to the canonical one. If your proxy rewrites `Host`, set `HOST_HEADER` first; see [first start](deployment.md#first-start).
|
|
29
|
+
- **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
|
+
- **New commands:** `sandcms media import-r2`, `sandcms media verify [--repair]`, `sandcms media rebuild --force`.
|
|
31
|
+
- **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.
|
|
33
|
+
|
|
34
|
+
## 0.6.3 upgrade checklist
|
|
35
|
+
|
|
36
|
+
Version 0.6.3 adds no SQL migration and no Worker protocol change. Follow this order when upgrading from 0.6.2:
|
|
37
|
+
|
|
38
|
+
1. Install `sandcms@0.6.3`, review `sandcms upgrade --check`, then apply integration updates with `sandcms upgrade`.
|
|
39
|
+
2. Rebuild and restart the website. Verify sign-in, two-factor setup and the editor on staging.
|
|
40
|
+
|
|
41
|
+
Upgrading from 0.6.1 still requires the [0.6.2 upgrade checklist](#062-upgrade-checklist) first.
|
|
42
|
+
|
|
3
43
|
## 0.6.2 upgrade checklist
|
|
4
44
|
|
|
5
45
|
Version 0.6.2 includes retained database migrations `0007` and `0008`. Follow this order when upgrading from 0.6.1:
|
|
@@ -51,7 +91,7 @@ Version 0.6.0 requires SvelteKit 3 and includes retained database migrations `00
|
|
|
51
91
|
|
|
52
92
|
1. Stop website and job processes and take a verified backup with the installed package.
|
|
53
93
|
2. Install `sandcms@0.6.0` and migrate developer-owned configuration using the [SvelteKit 3 instructions](#sveltekit-3). Review `sandcms upgrade --check` and merge integration changes into customized files.
|
|
54
|
-
3. Deploy the protocol-5 Worker with `sandcms worker update`. Configure R2 signing credentials, bucket PUT CORS, and the one-day `incoming/` lifecycle rule for
|
|
94
|
+
3. Deploy the protocol-5 Worker with `sandcms worker update`. Configure R2 signing credentials, bucket PUT CORS, and the one-day `incoming/` lifecycle rule for direct uploads (see the 0.6 version of `docs/cloudflare.md`). Preserve the private `deleted/` prefix indefinitely for [durable deletion](#durable-media-deletion).
|
|
55
95
|
4. Review `sandcms migrate --check`, apply integration updates with `sandcms upgrade`, then run `sandcms migrate`. Only pending migrations are applied; supported existing data is preserved.
|
|
56
96
|
5. Rebuild and restart the website. Verify sign-in, editing, uploads, deletion, and form submissions on staging. Update custom API clients for paginated `{items, nextCursor}` list responses and the required document `version` on unpublish.
|
|
57
97
|
|
|
@@ -160,7 +200,7 @@ rm -f ./data/sandcms.sqlite ./data/sandcms.sqlite-wal ./data/sandcms.sqlite-shm
|
|
|
160
200
|
bun run dev:init
|
|
161
201
|
```
|
|
162
202
|
|
|
163
|
-
For installed sites, initialize the fresh database with `sandcms migrate --database PATH` and then `sandcms user bootstrap --database PATH`. Update the application's database setting if you chose a new path. Recreate content and re-upload media as needed. Resetting SQLite does not delete
|
|
203
|
+
For installed sites, initialize the fresh database with `sandcms migrate --database PATH` and then `sandcms user bootstrap --database PATH`. Update the application's database setting if you chose a new path. Recreate content and re-upload media as needed. Resetting SQLite does not delete files in the media directory; old uploads are not imported into the fresh database.
|
|
164
204
|
|
|
165
205
|
## Generated application files and configuration
|
|
166
206
|
|
|
@@ -171,14 +211,12 @@ bun x --no-install sandcms upgrade --check
|
|
|
171
211
|
bun x --no-install sandcms upgrade
|
|
172
212
|
bun x --no-install sandcms migrate --check
|
|
173
213
|
bun x --no-install sandcms migrate
|
|
174
|
-
# Separately, when the release requires Worker changes:
|
|
175
|
-
bun x --no-install sandcms worker update
|
|
176
214
|
```
|
|
177
215
|
|
|
178
216
|
These commands assume a compatible or fresh database. `upgrade --check` validates blueprints, checks recorded ownership and database compatibility, and prints a no-write report. `upgrade` compares generated files with hashes in `sandcms/install.json`. Unmodified generated files receive new templates. Edited files are preserved by default, with a unified diff and an explicit overwrite choice in an interactive terminal. Cancelling a prompt still produces the report without applying file changes. These ownership protections remain in place for upgrades.
|
|
179
217
|
|
|
180
|
-
|
|
218
|
+
A media preset change requires `media rebuild`; old active variant sets remain live until each new set completes. See [media](media.md).
|
|
181
219
|
|
|
182
220
|
## Direct R2 upload upgrade
|
|
183
221
|
|
|
184
|
-
Back up with the installed package before updating. Deploy the new Worker first; protocol 4 retains compatibility with protocol 3 website processes. Configure its R2 signing secrets, bucket PUT CORS for the admin origin and a one-day `incoming/` lifecycle rule as described in
|
|
222
|
+
Back up with the installed package before updating. Deploy the new Worker first; protocol 4 retains compatibility with protocol 3 website processes. Configure its R2 signing secrets, bucket PUT CORS for the admin origin and a one-day `incoming/` lifecycle rule as described in the 0.6 version of `docs/cloudflare.md`. Run `sandcms migrate` to append `0003_direct_r2_uploads.sql`, then rebuild and restart the website. The migration adds metadata-only sessions and preserves all media, jobs and pending legacy BLOB uploads. There is no reset or automatic replacement of developer-owned configuration. New browser uploads send bytes directly to R2; the website needs only its normal JSON body limit. Existing host limits can remain in place.
|