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