sandcms 0.6.3 → 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 +2 -0
- package/dist/admin/Admin.svelte +14 -1
- package/dist/admin/AssetAttachment.svelte +1 -3
- package/dist/admin/AssetAttachment.svelte.d.ts +0 -1
- package/dist/admin/BlueprintFields.svelte +0 -3
- package/dist/admin/BlueprintFields.svelte.d.ts +0 -1
- package/dist/admin/Editor.svelte +0 -1
- package/dist/admin/Fields.svelte +0 -7
- package/dist/admin/Fields.svelte.d.ts +0 -1
- package/dist/admin/Gallery.svelte +2 -6
- package/dist/admin/Gallery.svelte.d.ts +0 -1
- 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 +7 -15
- package/dist/admin/MediaPicker.svelte.d.ts +0 -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/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 +529 -101
- 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 +6 -1
- 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 +5 -2
- package/dist/server/auth.d.ts +10 -9
- 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 +41 -3
- 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 +17 -1
- package/docs/upgrades.md +35 -6
- package/package.json +36 -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/deployment.md
CHANGED
|
@@ -1,34 +1,69 @@
|
|
|
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; we recommend [Dokploy](https://dokploy.com) or [Openship](https://openship.io).
|
|
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
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
18
|
+
## What the host must provide
|
|
19
|
+
|
|
20
|
+
| Requirement | Detail |
|
|
21
|
+
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
22
|
+
| Container | Built from the site's `Dockerfile` (or Railpack), one replica |
|
|
23
|
+
| Volume | One persistent volume mounted at `/data`, on a local filesystem, **used by this site only** |
|
|
24
|
+
| Deploys | Either overlap (start the new container, then stop the old) or stop-then-start. Stop timeout of at least 30 s |
|
|
25
|
+
| Reverse proxy | TLS, routes the site's hostnames, passes `Host` unchanged, overwrites the client-IP header it sets |
|
|
26
|
+
| Health check | The image's `HEALTHCHECK`, or `GET /_sandcms/health` |
|
|
27
|
+
| Memory | A container memory limit that covers one image decode at `media.maxPixels` (see [memory](#memory-and-image-limits)) |
|
|
28
|
+
| Backups | A scheduled copy of the whole volume to off-server storage |
|
|
17
29
|
|
|
18
|
-
|
|
30
|
+
The proxy needs no raised timeouts or body limits: uploads arrive in 8 MB chunks, and every other request is under 1 MB.
|
|
19
31
|
|
|
20
|
-
|
|
32
|
+
Do not put the volume on an object-store mount or an unproven network filesystem; SQLite needs local file locking.
|
|
21
33
|
|
|
22
|
-
##
|
|
34
|
+
## Environment
|
|
35
|
+
|
|
36
|
+
```dotenv
|
|
37
|
+
SANDCMS_ORIGIN=https://www.example.com
|
|
38
|
+
SANDCMS_SECRET=<32+ random characters>
|
|
39
|
+
SANDCMS_DATABASE=/data/sandcms.sqlite
|
|
40
|
+
SANDCMS_AUTO_MIGRATE=true
|
|
41
|
+
BODY_SIZE_LIMIT=10M
|
|
42
|
+
SANDCMS_TRUSTED_PROXY_HEADER=x-real-ip # the header your proxy sets
|
|
43
|
+
ADDRESS_HEADER=x-real-ip
|
|
44
|
+
# SANDCMS_INDEXING=false # preview sites only
|
|
45
|
+
# SANDCMS_BOOTSTRAP_EMAIL=you@example.com # first start only
|
|
46
|
+
```
|
|
23
47
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
48
|
+
| Variable | Purpose |
|
|
49
|
+
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
50
|
+
| `SANDCMS_ORIGIN` | Canonical public origin. Requests for other hostnames redirect here. Changing it needs a restart, not a rebuild. |
|
|
51
|
+
| `SANDCMS_SECRET` | Stable random secret, at least 32 characters. Signs sessions and upload tickets. |
|
|
52
|
+
| `SANDCMS_DATABASE` | SQLite path on the volume. Its directory is the data directory. |
|
|
53
|
+
| `SANDCMS_MEDIA_DIR` | Optional. Defaults to `<database directory>/media`. Keep it on the same volume. |
|
|
54
|
+
| `SANDCMS_AUTO_MIGRATE` | `true` applies pending migrations on start, after a verified snapshot. See [automatic migration](#automatic-migration-on-start). |
|
|
55
|
+
| `BODY_SIZE_LIMIT` | The Bun adapter's limit for all routes. Must be at least the 8 MB chunk size; `10M` is recommended and set by the starter image. |
|
|
56
|
+
| `SANDCMS_REQUEST_LIMIT` | Optional. Largest body in bytes for every route except upload chunks (default 1 MB). Larger bodies get 413 before being read. |
|
|
57
|
+
| `SANDCMS_TRUSTED_PROXY_HEADER` | Client-IP header used for CMS rate limits. See [client IP](#client-ip-behind-a-reverse-proxy). |
|
|
58
|
+
| `ADDRESS_HEADER` | The Bun adapter's client-IP header for `event.getClientAddress()`. Set it to the same header. |
|
|
59
|
+
| `SANDCMS_INDEXING` | `false` sends `X-Robots-Tag: noindex` and a disallow-all `robots.txt`. Unset means indexed. |
|
|
60
|
+
| `SANDCMS_BOOTSTRAP_EMAIL` | On a start with no users, creates this administrator and logs a one-time password. Remove it after first sign-in. |
|
|
61
|
+
| `SANDCMS_CANONICAL_REDIRECT` | `false` turns off the redirect of other hostnames to `SANDCMS_ORIGIN`. Unset means on. See [first start](#first-start). |
|
|
62
|
+
| `SANDCMS_SITE_RENAME` | `true` for one start after renaming the project in `config.yaml`, so the volume's `site-id` follows. Remove it afterwards. |
|
|
63
|
+
| `SANDCMS_ALLOW_UNMOUNTED_DATA` | `true` allows a new production database outside a mounted volume. Only for hosts without container volumes. |
|
|
64
|
+
| `PORT` | The port the server listens on (3000 in the starter image). |
|
|
65
|
+
|
|
66
|
+
`SANDCMS_WORKER_URL` and `SANDCMS_WORKER_TOKEN` are deprecated. They are read only by `sandcms media import-r2`; remove them once the [R2 import](cloudflare.md) is done.
|
|
32
67
|
|
|
33
68
|
### Environment validation
|
|
34
69
|
|
|
@@ -42,13 +77,57 @@ SANDCMS_SECRET
|
|
|
42
77
|
- Must be at least 32 characters
|
|
43
78
|
```
|
|
44
79
|
|
|
45
|
-
|
|
80
|
+
With a health check configured, a deployment with a broken environment never goes live. Builds skip the required checks, so secrets need not be present in the build environment. Values are all runtime (`static: false`); none are inlined into the bundle. Declare your own variables in the same `defineEnvVars` call; see [SvelteKit environment variables](https://svelte.dev/docs/kit/environment-variables).
|
|
81
|
+
|
|
82
|
+
## Server build configuration
|
|
83
|
+
|
|
84
|
+
New sites get a multi-stage `Dockerfile` on the pinned Bun image: it installs with the frozen lockfile, builds, and runs `bun build/index.js` on port 3000 with `BODY_SIZE_LIMIT=10M` and `SANDCMS_DATABASE=/data/sandcms.sqlite`. It has a `HEALTHCHECK` on `/_sandcms/health` and no `VOLUME` instruction; the host mounts the volume. `.dockerignore` excludes local credentials, databases, media and build/test artifacts. Do not create accounts during image builds.
|
|
85
|
+
|
|
86
|
+
Existing sites can keep building with Railpack and `railpack.json`, or copy the starter `Dockerfile` from the package (`node_modules/sandcms/templates/Dockerfile`). Either way, start the server with `bun build/index.js`.
|
|
87
|
+
|
|
88
|
+
The starter's `vite.config.ts` contains this server configuration. Merge it into existing sites, preserving other plugins and SSR options:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
sveltekit({ adapter: adapter(), preprocess: vitePreprocess() }),
|
|
92
|
+
// …
|
|
93
|
+
ssr: {
|
|
94
|
+
external: ['bun:sqlite', 'sharp'],
|
|
95
|
+
noExternal: ['@better-auth/core']
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
- Do not set `paths.origin`. The site derives its origin from each request's `Host` header, so a domain change needs no rebuild.
|
|
100
|
+
- `sharp` stays external so its native binary loads at runtime. The image processor runs as a child process from the package's `sandcms/media-processor` entry.
|
|
101
|
+
- Vite bundles `@better-auth/core` using its server export conditions to retain native async request storage. Keep it out of `ssr.external`, which takes precedence over `noExternal`. See [Vite SSR options](https://vite.dev/config/ssr-options) and the [Bun adapter](https://svelte.dev/docs/kit/adapter-bun).
|
|
102
|
+
|
|
103
|
+
`cmsHandle` must run first in `sequence()` in `src/hooks.server.ts`: it serves health checks, redirects other hostnames, enforces the request body limit and receives upload chunks before anything else reads the request.
|
|
104
|
+
|
|
105
|
+
## Health check
|
|
106
|
+
|
|
107
|
+
`GET /_sandcms/health` returns 200 when the process serves requests and the database opens. It is a liveness check only: a full disk or a media problem shows in the admin and in `sandcms doctor`, and does not restart the site in a loop. The health route is exempt from the hostname redirect, so the host can call it on any address.
|
|
108
|
+
|
|
109
|
+
## Deploys and volume checks
|
|
110
|
+
|
|
111
|
+
Both deploy styles work. Hosts that overlap (start the new container, wait until it is ready, switch traffic, then stop the old one, as Openship does on a Docker server) give zero-downtime deploys; hosts that stop the old container first have a few seconds of downtime. During an overlap both containers use the same SQLite database, which SQLite handles on a local volume. Background work coordinates through database leases: one image is processed at a time and one server writes the hourly snapshot. Use a stop timeout of at least 30 seconds so uploads in progress finish.
|
|
46
112
|
|
|
47
|
-
|
|
113
|
+
With auto-migrate, the new container applies pending migrations while the old one is still serving. SandCMS migrations are additive, so the old code keeps working for the short overlap. Run a single replica per site; scaling out to several long-running replicas is not supported.
|
|
48
114
|
|
|
49
|
-
|
|
115
|
+
The generated integration passes `server: true` to `createCMS()`; customized integrations need it too. Two checks then catch a wrong volume before content is written:
|
|
50
116
|
|
|
51
|
-
|
|
117
|
+
- On first start the server writes `/data/site-id` (a random ID and the project `name` from `config.yaml`). It refuses to start on a volume whose `site-id` names another project, so two sites cannot share a volume by mistake. After renaming the project, start once with `SANDCMS_SITE_RENAME=true`: the server rewrites `site-id` with the new name, keeps its ID and logs the change. Then remove the variable.
|
|
118
|
+
- In production, the server refuses to create a new database outside a mounted volume, where content would be lost when the container is replaced. The data directory may be the mount (`/data`) or inside one (`/data/db`). Set `SANDCMS_ALLOW_UNMOUNTED_DATA=true` only on hosts without container volumes where the directory does persist.
|
|
119
|
+
|
|
120
|
+
## First start
|
|
121
|
+
|
|
122
|
+
1. Create the app on the host with its own volume and the environment above. Use a temporary hostname, `SANDCMS_INDEXING=false` and `SANDCMS_BOOTSTRAP_EMAIL`.
|
|
123
|
+
2. Deploy. With `SANDCMS_AUTO_MIGRATE=true` the first start creates the database; with `SANDCMS_BOOTSTRAP_EMAIL` and no users, it creates that administrator and logs a one-time password. Sign in and change it.
|
|
124
|
+
3. **Launch:** point the domain's DNS at the host, add the hostnames on the platform, set `SANDCMS_ORIGIN` to the final origin, remove `SANDCMS_INDEXING` and `SANDCMS_BOOTSTRAP_EMAIL`, and restart. Other hostnames, including the temporary one, now get a 308 redirect to the origin.
|
|
125
|
+
|
|
126
|
+
The redirect compares the hostname of the request as the Bun adapter sees it: the `Host` header, or the header named by `HOST_HEADER`. A proxy that passes `Host` unchanged needs nothing else. A proxy that rewrites `Host` to an internal name (nginx does by default with `proxy_pass`) must forward the public name, for example in `X-Forwarded-Host` with `HOST_HEADER=x-forwarded-host`; otherwise every request would be redirected. `SANDCMS_CANONICAL_REDIRECT=false` turns the redirect off. The redirect is also off when `NODE_ENV` is not `production` (the starter image sets it).
|
|
127
|
+
|
|
128
|
+
Prerendered pages and files in `static/` are served without hooks, so they skip the redirect and the indexing header. `sandcms doctor` warns when a site has them.
|
|
129
|
+
|
|
130
|
+
Without shell access to bootstrap, the operator commands below are an alternative. Run them through the host's command facility or a one-off container with the **same** volume:
|
|
52
131
|
|
|
53
132
|
```sh
|
|
54
133
|
bun x --no-install sandcms migrate --check --database /data/sandcms.sqlite
|
|
@@ -56,15 +135,17 @@ bun x --no-install sandcms migrate --database /data/sandcms.sqlite
|
|
|
56
135
|
bun x --no-install sandcms user bootstrap --database /data/sandcms.sqlite --email admin@example.com
|
|
57
136
|
```
|
|
58
137
|
|
|
59
|
-
In this source repository's demo image, use `bun dist/cli/index.js` in place of `bun x --no-install sandcms`.
|
|
138
|
+
In this source repository's demo image, use `bun dist/cli/index.js` in place of `bun x --no-install sandcms`. Bootstrap only works when the selected database has no users, generates a password, and prints it once. A local account does not create a production account.
|
|
139
|
+
|
|
140
|
+
From 0.5.0, retained incremental migrations upgrade supported databases. Changed pre-0.5.0 baselines still require a fresh database; see the [upgrade workflow](upgrades.md). The app refuses to start with pending or incompatible migrations. Each numbered migration runs transactionally.
|
|
60
141
|
|
|
61
142
|
### Automatic migration on start
|
|
62
143
|
|
|
63
|
-
Set `SANDCMS_AUTO_MIGRATE=true` to apply pending migrations when the website starts instead of running `sandcms migrate` separately. The generated integration passes it to `createCMS({ autoMigrate })`; customized integrations must add `autoMigrate: env.SANDCMS_AUTO_MIGRATE` themselves when reading `$app/env/private` (the value is already a boolean), or `autoMigrate: process.env.SANDCMS_AUTO_MIGRATE === 'true'` when still reading `process.env`. Before migrating an existing database, the website writes a verified snapshot to `<database>.before-migrate-<timestamp>-<id>.sqlite` beside it and logs its path;
|
|
144
|
+
Set `SANDCMS_AUTO_MIGRATE=true` to apply pending migrations when the website starts instead of running `sandcms migrate` separately. The generated integration passes it to `createCMS({ autoMigrate })`; customized integrations must add `autoMigrate: env.SANDCMS_AUTO_MIGRATE` themselves when reading `$app/env/private` (the value is already a boolean), or `autoMigrate: process.env.SANDCMS_AUTO_MIGRATE === 'true'` when still reading `process.env`. Before migrating an existing database, the website writes a verified snapshot to `<database>.before-migrate-<timestamp>-<id>.sqlite` beside it and logs its path; the newest three are kept. Empty databases are initialized without a snapshot, and a non-empty database with no migration history is refused. Incompatible or modified histories are still rejected without changes, and a failed migration rolls back and stops startup. Leave the variable unset to keep the explicit operator workflow.
|
|
64
145
|
|
|
65
|
-
|
|
146
|
+
### Users
|
|
66
147
|
|
|
67
|
-
A new user added later must have an operator
|
|
148
|
+
A new user added later must have an operator- or admin-supplied password. The CLI prompts without echo; automation may use `--password-stdin`. Both paths require a change at first login. Password and 2FA recovery invalidate sessions and write audit metadata:
|
|
68
149
|
|
|
69
150
|
```sh
|
|
70
151
|
bun x --no-install sandcms user add --email editor@example.com --role editor
|
|
@@ -72,60 +153,81 @@ bun x --no-install sandcms user reset-password --email editor@example.com
|
|
|
72
153
|
bun x --no-install sandcms user reset-2fa --email editor@example.com
|
|
73
154
|
```
|
|
74
155
|
|
|
75
|
-
HTTPS origins use secure cookies. CMS writes validate origin, authentication is enforced server-side, and logins have per-email and per-client limits.
|
|
156
|
+
HTTPS origins use secure cookies. CMS writes validate origin, authentication is enforced server-side, and logins have per-email and per-client limits.
|
|
76
157
|
|
|
77
|
-
## Client IP behind
|
|
158
|
+
## Client IP behind a reverse proxy
|
|
78
159
|
|
|
79
|
-
|
|
160
|
+
By default the application reads no proxy IP headers, and every visitor appears to come from the proxy. To rate-limit per visitor:
|
|
80
161
|
|
|
81
|
-
1.
|
|
82
|
-
2.
|
|
83
|
-
3. Set both
|
|
162
|
+
1. Find the header your proxy sets to the client address: Traefik (Dokploy) and nginx commonly use `X-Real-IP`; Cloudflare in front of the proxy sets `CF-Connecting-IP`.
|
|
163
|
+
2. Make sure the proxy **overwrites** that header on every request, and that the container port is not reachable around the proxy. Otherwise a visitor can supply any address.
|
|
164
|
+
3. Set both variables to that header and restart:
|
|
84
165
|
|
|
85
166
|
```dotenv
|
|
86
|
-
SANDCMS_TRUSTED_PROXY_HEADER=
|
|
87
|
-
ADDRESS_HEADER=
|
|
167
|
+
SANDCMS_TRUSTED_PROXY_HEADER=x-real-ip
|
|
168
|
+
ADDRESS_HEADER=x-real-ip
|
|
88
169
|
```
|
|
89
170
|
|
|
90
|
-
`SANDCMS_TRUSTED_PROXY_HEADER` controls CMS login and access-link rate limits. The [Bun adapter's `ADDRESS_HEADER`](https://svelte.dev/docs/kit/adapter-bun) controls `event.getClientAddress()`, including website form actions.
|
|
171
|
+
`SANDCMS_TRUSTED_PROXY_HEADER` controls CMS login and access-link rate limits. The [Bun adapter's `ADDRESS_HEADER`](https://svelte.dev/docs/kit/adapter-bun) controls `event.getClientAddress()`, including website form actions. Use a single-address header; with `X-Forwarded-For`, the adapter also needs `XFF_DEPTH`. The CMS falls back to `event.getClientAddress()` if its header is absent or empty; the Bun adapter throws if its `ADDRESS_HEADER` is absent. A wrongly trusted header defeats client rate limiting.
|
|
91
172
|
|
|
92
|
-
|
|
173
|
+
With Cloudflare proxying in front of the host, use `cf-connecting-ip` instead, restrict the host's ingress to [Cloudflare traffic](https://developers.cloudflare.com/fundamentals/security/protect-your-origin-server/), and replace untrusted copies on any other ingress.
|
|
93
174
|
|
|
94
|
-
|
|
175
|
+
`sandcms doctor` warns when `SANDCMS_ORIGIN` uses HTTPS and no CMS proxy header is set; it does not verify the proxy. To check, temporarily log `event.getClientAddress()` in a form action on staging, submit from two networks, and confirm each shows its own public IP and that a supplied spoofed header has no effect. Remove the logging afterwards.
|
|
95
176
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
177
|
+
## Backups and restore
|
|
178
|
+
|
|
179
|
+
Back up the **whole volume** on a schedule, to storage off the server. The site may keep running while the copy is taken.
|
|
180
|
+
|
|
181
|
+
A file copy of a live SQLite database can be torn, so the site also writes a verified snapshot of its database every hour to `/data/backups/latest.sqlite`, keeping the one before as `previous.sqlite`. It catches up shortly after start when the last snapshot is older than an hour. Snapshots run in a separate process, so they do not hold up requests. Any volume backup therefore contains a consistent database. `sandcms doctor` reports the snapshot age.
|
|
182
|
+
|
|
183
|
+
**Restore:**
|
|
184
|
+
|
|
185
|
+
1. Stop the site and disable automatic restarts.
|
|
186
|
+
2. Restore the volume from the backup.
|
|
187
|
+
3. Restore the database from the snapshot inside it, using a one-off container with the same volume:
|
|
99
188
|
|
|
100
|
-
|
|
189
|
+
```sh
|
|
190
|
+
bun x --no-install sandcms restore --database /data/sandcms.sqlite --from /data/backups/latest.sqlite
|
|
191
|
+
```
|
|
101
192
|
|
|
102
|
-
|
|
193
|
+
4. Start the site, and check for media rows without files:
|
|
194
|
+
|
|
195
|
+
```sh
|
|
196
|
+
bun x --no-install sandcms media verify
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
Always restore the database from the snapshot; the copy of the live database in the volume backup may be torn. The snapshot can be up to an hour older than the media files in the same backup, so recent edits can be lost and recent uploads can exist as files without rows (they are harmless). `media verify --repair` re-renders missing variants and marks images whose original is missing as failed; see [media](media.md#checking-and-repairing-files).
|
|
200
|
+
|
|
201
|
+
The restore command verifies the backup and schema, obtains an exclusive lock on `sandcms.sqlite.guard.sqlite`, creates a verified `before-restore` safety snapshot, checkpoints WAL, and replaces the target. Every CMS database connection holds a shared guard lock for its lifetime, so an in-use restore is refused. Keep the guard file with the database; do not delete it to bypass the check. `--yes` is an explicit noninteractive confirmation; it does not bypass locking.
|
|
202
|
+
|
|
203
|
+
For an extra copy outside the volume, `sandcms backup` writes a verified snapshot to any path:
|
|
103
204
|
|
|
104
205
|
```sh
|
|
105
|
-
bun x --no-install sandcms backup --database /data/sandcms.sqlite --output /backups/
|
|
206
|
+
bun x --no-install sandcms backup --database /data/sandcms.sqlite --output /data/backups/manual-2026-11-17.sqlite
|
|
106
207
|
```
|
|
107
208
|
|
|
108
|
-
|
|
209
|
+
It uses SQLite `VACUUM INTO`, validates integrity, foreign keys and migration history, and writes the file with restrictive permissions. Never copy a live WAL-mode `.sqlite` file by itself.
|
|
109
210
|
|
|
110
|
-
##
|
|
211
|
+
## Rollback
|
|
111
212
|
|
|
112
|
-
|
|
113
|
-
2. Run a one-off command/container mounting the same volume and backup.
|
|
114
|
-
3. Restore, explicitly confirming the displayed target:
|
|
213
|
+
Use the platform's rollback to return to the previous image. If the bad deploy applied a migration, the old code refuses the newer database; also stop the site and restore the `before-migrate` snapshot that the migration logged:
|
|
115
214
|
|
|
116
215
|
```sh
|
|
117
|
-
bun x --no-install sandcms restore --database /data/sandcms.sqlite --from /
|
|
216
|
+
bun x --no-install sandcms restore --database /data/sandcms.sqlite --from /data/sandcms.sqlite.before-migrate-<timestamp>-<id>.sqlite
|
|
118
217
|
```
|
|
119
218
|
|
|
120
|
-
|
|
219
|
+
Content edited after the migration is lost.
|
|
220
|
+
|
|
221
|
+
## Memory and image limits
|
|
121
222
|
|
|
122
|
-
|
|
223
|
+
Images are decoded in a child process, one at a time, so a decode that exceeds the container's memory limit kills the child, not the web server; the image is retried and then marked failed. Give the container enough memory for one decode at `media.maxPixels` (100 megapixels by default) on top of the web server. Lower `media.maxPixels` on small servers. See [media limits](media.md#limits).
|
|
123
224
|
|
|
124
|
-
##
|
|
225
|
+
## Recommended platforms
|
|
125
226
|
|
|
126
|
-
|
|
227
|
+
Dokploy and Openship both provide everything in [the requirements](#what-the-host-must-provide): Git deploys, a reverse proxy with Let's Encrypt, named volumes, scheduled volume backups to S3-compatible storage, and rollback.
|
|
127
228
|
|
|
128
|
-
|
|
229
|
+
- **Dokploy.** Volume names are global on a server, so give each site its own, such as `sandcms-<slug>-data`. Either update order works. Rollback needs a registry configured. Volume backups are full archives. Traefik sets `X-Real-IP`.
|
|
230
|
+
- **Openship.** On a Docker server it deploys by overlap, with no downtime. Supports incremental volume backups and validates a restore before replacing data. Not yet tested by us with SandCMS.
|
|
129
231
|
|
|
130
232
|
## Transactional email
|
|
131
233
|
|
package/docs/forms.md
CHANGED
|
@@ -11,7 +11,7 @@ const result = await cms.forms.submit('registration', validatedData, {
|
|
|
11
11
|
|
|
12
12
|
The helper accepts plain JSON objects up to 64 KB, rejects cycles, non-finite numbers, reserved keys, and excessive nesting, silently ignores filled honeypots, and applies a durable per-form/per-client limit of five accepted attempts per minute. Supply a server-derived client identity. Never pass a browser-provided identity or trust proxy headers without configuring your host's trusted proxy chain.
|
|
13
13
|
|
|
14
|
-
Behind
|
|
14
|
+
Behind a reverse proxy, configure both `ADDRESS_HEADER` and `SANDCMS_TRUSTED_PROXY_HEADER` as described in the [client IP recipe](deployment.md#client-ip-behind-a-reverse-proxy). The CMS setting alone does not change `event.getClientAddress()` in website form actions; without adapter configuration, visitors can share the proxy's five-attempt bucket.
|
|
15
15
|
|
|
16
16
|
Form YAML supplies stable IDs, labels, optional nested field groups, list `columns`, and `export` ordering. Each accepted submission stores its own blueprint snapshot so prior labels and export columns remain readable after changes. Both CMS roles can read, mark read/unread, export CSV, and delete. Export preserves historical field labels and guards formula-like spreadsheet cells.
|
|
17
17
|
|
package/docs/media.md
CHANGED
|
@@ -1,16 +1,46 @@
|
|
|
1
1
|
# Media
|
|
2
2
|
|
|
3
|
-
The website's Bun process owns SQLite
|
|
3
|
+
Images are stored and processed by the site itself. The website's Bun process owns SQLite, the durable media job runner and the files under the media directory; a child process decodes and encodes images with [sharp](https://sharp.pixelplumbing.com) (libvips). Public images use the website's media route, which supports browser and CDN caching. No external service is involved.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Storage
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Media lives in `SANDCMS_MEDIA_DIR`, by default `media/` next to the database (`/data/media` in the starter image), on the same volume:
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
media/originals/{id} uploaded files, never modified or served
|
|
11
|
+
media/variants/{id}/{version}/{preset}-{size}.{format} encoded variants, served at /_sandcms/media/{key}
|
|
12
|
+
media/tmp/{id}/… upload chunks and processing scratch files
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Every file is written to a temporary path, flushed to disk and renamed before the database records it, so a crash never leaves a half-written original or variant behind a database row. An existing original is never replaced. Width, height and each variant's ETag are stored in SQLite. Temporary files older than a day are removed at start and hourly.
|
|
16
|
+
|
|
17
|
+
Back up the media directory with the rest of the volume; see [backups](deployment.md#backups-and-restore). Media usage and free disk space are shown in the admin and by `sandcms doctor`.
|
|
18
|
+
|
|
19
|
+
## Formats and limits
|
|
20
|
+
|
|
21
|
+
Accepted input: JPEG, PNG, WebP, AVIF, GIF, TIFF and SVG. Output is WebP, AVIF and JPEG; SVG is served as a sanitized SVG. TIFF originals are never served directly, only their variants. HEIC is not supported.
|
|
22
|
+
|
|
23
|
+
### Limits
|
|
24
|
+
|
|
25
|
+
| Setting | Default | Range | Applies to |
|
|
26
|
+
| ------------------- | ----------- | ------------------------- | --------------------------------------------------------- |
|
|
27
|
+
| `media.uploadLimit` | 100,000,000 | 1 – 500,000,000 bytes | Each uploaded file |
|
|
28
|
+
| `media.maxPixels` | 100,000,000 | 1,000,000 – 1,000,000,000 | Decoded raster area (width × height, after EXIF) |
|
|
29
|
+
| `media.maxStorage` | none | bytes | Originals plus variants; uploads are refused when reached |
|
|
30
|
+
|
|
31
|
+
SVG is limited to 1 MB. An upload is also refused (507) unless the disk has free space of at least three times its size, plus the size of other uploads in progress, plus 5 GB. Memory use grows with `maxPixels`: the container needs room for one decode at that size, see [memory](deployment.md#memory-and-image-limits).
|
|
32
|
+
|
|
33
|
+
```yaml
|
|
34
|
+
media:
|
|
35
|
+
uploadLimit: 200000000 # 200 MB
|
|
36
|
+
maxPixels: 150000000 # 150 MP
|
|
37
|
+
maxStorage: 50000000000 # 50 GB
|
|
38
|
+
```
|
|
8
39
|
|
|
9
40
|
## Presets
|
|
10
41
|
|
|
11
42
|
```yaml
|
|
12
43
|
media:
|
|
13
|
-
workerUrl: https://your-project-media.example.workers.dev
|
|
14
44
|
defaultFileBlueprint: image
|
|
15
45
|
uploadLimit: 100000000
|
|
16
46
|
presets:
|
|
@@ -22,7 +52,7 @@ media:
|
|
|
22
52
|
formats: { webp: 85 }
|
|
23
53
|
```
|
|
24
54
|
|
|
25
|
-
Sizes are longest-side pixels. Outputs preserve aspect ratio and do not upscale unless an optional `aspectRatio` (width divided by height, 0.01–100) requests a crop. Cropped outputs also never upscale; small originals produce smaller variants with the requested ratio, subject to pixel rounding. Formats are WebP, AVIF, and JPEG, each with quality 1–100.
|
|
55
|
+
Sizes are longest-side pixels. Outputs preserve aspect ratio and do not upscale unless an optional `aspectRatio` (width divided by height, 0.01–100) requests a crop. Cropped outputs also never upscale; small originals produce smaller variants with the requested ratio, subject to pixel rounding. Formats are WebP, AVIF, and JPEG, each with quality 1–100. SVG is sanitized using a strict XML parser and allowlists; scripts, foreign content, external references, event handlers, and styles are removed. Document types/entities are rejected. The sanitized derivative receives restrictive CSP and nosniff headers, and is not resized or encoded as WebP.
|
|
26
56
|
|
|
27
57
|
## Focal points
|
|
28
58
|
|
|
@@ -45,21 +75,23 @@ card:
|
|
|
45
75
|
formats: { webp: 80, avif: 65 }
|
|
46
76
|
```
|
|
47
77
|
|
|
48
|
-
Crops
|
|
78
|
+
Crops resize the image to cover the requested ratio, then cut out the region centred as close to the focal point as the edges allow. Presets without `aspectRatio` preserve the full image. Focus changes automatically queue new immutable variant keys when cropping is configured; current variants stay available until the complete new set is ready. Unrelated metadata edits do not rebuild images. The reserved `sandcms-preview` preset supplies an uncropped WebP for the picker on raster files with a focus field.
|
|
49
79
|
|
|
50
|
-
Existing project-owned blueprints/configuration are preserved during upgrades: add the field and ratio explicitly,
|
|
80
|
+
Existing project-owned blueprints/configuration are preserved during upgrades: add the field and ratio explicitly, then run `sandcms media rebuild` to prepare existing files and previews. No database migration is required.
|
|
51
81
|
|
|
52
82
|
## Privacy and publication
|
|
53
83
|
|
|
54
|
-
Originals
|
|
84
|
+
Originals stay private on the volume; no route serves them. A media asset becomes publicly accessible only when at least one **published snapshot** references it through a media field, media list, or gallery (including nested fields). Uploading to the library, saving a draft, and preparing variants grant no public access. Sharing an asset with published content makes its active variants public even if it is also used in drafts.
|
|
85
|
+
|
|
86
|
+
`cmsHandle` serves public variants at `/_sandcms/media/{key}`. It checks the current published references and the active variant set, then streams the file from disk. Removing the last published reference—by unpublishing, deleting content, or publishing a replacement—revokes access at the origin. Cached copies can remain available. Draft edits leave the existing published snapshot and its images live. Requests reaching the origin cannot access historical variant sets after replacement; previously cached versions can remain available.
|
|
55
87
|
|
|
56
|
-
|
|
88
|
+
Editor previews use `/api/cms/media/{key}` and require an active admin/editor session with no pending password change. Query-based transformations are rejected; only named variants exist.
|
|
57
89
|
|
|
58
|
-
|
|
90
|
+
Variant responses carry `Content-Type`, `Content-Length`, a strong `ETag`, `Content-Security-Policy: default-src 'none'; style-src 'none'; sandbox`, `Cross-Origin-Resource-Policy: cross-origin` and `X-Content-Type-Options: nosniff`. A file missing on disk returns 404.
|
|
59
91
|
|
|
60
|
-
Successful public responses use `Cache-Control: public, max-age=86400, s-maxage=2592000`: one day of browser freshness and 30 days in shared caches. Public responses preserve ETags and support `If-None-Match` revalidation for GET and HEAD, including weak validators, lists, and `*`. The CMS checks current access before
|
|
92
|
+
Successful public responses use `Cache-Control: public, max-age=86400, s-maxage=2592000`: one day of browser freshness and 30 days in shared caches. Public responses preserve ETags and support `If-None-Match` revalidation for GET and HEAD, including weak validators, lists, and `*`. The CMS checks current access before returning a body or a cacheable `304`. Cache hits bypass these checks. Cached availability after unpublishing, deletion, or variant replacement is intentional; immediate revocation is not promised. Cache retention is not guaranteed, so a cold location can return 404 while a warm cache still serves the image.
|
|
61
93
|
|
|
62
|
-
Editor previews and all delivery errors use `Cache-Control: private, no-store` and omit ETags. Preview responses vary by cookie; public responses are independent of sessions. Never cache private previews. Already downloaded images cannot be recalled.
|
|
94
|
+
Editor previews and all delivery errors use `Cache-Control: private, no-store` and omit ETags. Preview responses vary by cookie; public responses are independent of sessions. Never cache private previews. Already downloaded images cannot be recalled. For CDN cache rules in front of the site, see [optional CDN caching](cloudflare.md#optional-cdn-caching).
|
|
63
95
|
|
|
64
96
|
Publication does not move files or require cache registration. Uploads get distinct asset IDs and preset changes produce distinct variant URLs. Rebuilds reuse existing completed variants rather than overwriting them. Do not replace bytes under an existing URL: processing changes that alter output must introduce a new variant version. The public policy deliberately does not advertise `immutable`.
|
|
65
97
|
|
|
@@ -71,8 +103,7 @@ Import the Svelte component from the package root and pass the asset returned by
|
|
|
71
103
|
`cms.media.publicAsset(id)`:
|
|
72
104
|
|
|
73
105
|
Each variant includes a `url` using the CMS public or authenticated preview route.
|
|
74
|
-
The component needs no URL configuration.
|
|
75
|
-
`media.workerUrl` in YAML) configures only the server's private Worker connection.
|
|
106
|
+
The component needs no URL configuration.
|
|
76
107
|
|
|
77
108
|
```svelte
|
|
78
109
|
<script lang="ts">
|
|
@@ -111,24 +142,57 @@ The component emits a `<picture>` with AVIF, WebP, then JPEG sources when availa
|
|
|
111
142
|
and adds no styling or admin dependencies. Consumers control layout with their own CSS.
|
|
112
143
|
`imageSources(asset, preset)` remains available for custom markup.
|
|
113
144
|
|
|
114
|
-
##
|
|
145
|
+
## Uploads
|
|
115
146
|
|
|
116
|
-
|
|
147
|
+
Files upload to the site itself in 8 MB chunks, so no request is large or long enough to hit a reverse proxy's default limits:
|
|
148
|
+
|
|
149
|
+
1. The admin (or an [API client](api.md#media-uploads)) asks to start an upload with the file's name, type and size. The CMS checks the blueprint's accepted types, `uploadLimit`, disk space and quota, and returns a chunk URL with a signed upload ticket.
|
|
150
|
+
2. Chunks are sent one at a time with `PUT {url}?index=N`. Each chunk is stored on disk as it streams in; re-sending a chunk replaces it. A `GET {url}` lists the chunks already stored, so an interrupted upload resumes where it stopped, also after a site restart.
|
|
151
|
+
3. Completion assembles the chunks and checks the total size. A background job then validates the file and stores the original: SVGs go through the sanitizer; raster files must decode as the declared type within `maxPixels`. Variant jobs are queued after that.
|
|
152
|
+
|
|
153
|
+
The ticket is bound to the asset, the upload attempt, the declared type and size, and the user who started it (their session or any of their API keys may send chunks). An upload with no chunk for 15 minutes expires; the asset is marked failed and its chunks are removed. Upload bytes never enter SQLite. Existing BLOB uploads from earlier releases still finish through the legacy runner.
|
|
154
|
+
|
|
155
|
+
`cms.media.upload(file)` stores a file from server code through the same validation, without HTTP.
|
|
156
|
+
|
|
157
|
+
## Processing
|
|
158
|
+
|
|
159
|
+
Images are processed one at a time per site by a child process running sharp, so a huge decode cannot take down the web server. Each batch decodes the original once, auto-rotates it from EXIF orientation, converts it to sRGB, and encodes every requested variant from that master. Variants never upscale. Each finished variant is written and recorded before the next starts, so a retry skips finished variants. Jobs have durable attempts, leases, retry delays and failure state; restarting the website resumes them. If the child exits, for example when the container's memory limit is reached, the batch fails at once and each unfinished variant counts as a failed attempt; a variant that fails four times marks the asset failed. The media library shows processing/ready/failed and permits retries. An asset's old active set stays available throughout a rebuild.
|
|
160
|
+
|
|
161
|
+
The child runs at low CPU priority (`nice 10`), so page requests always win over background processing within a site. It uses one libvips thread by default. Set `SANDCMS_MEDIA_THREADS` (for example `2`–`4`) to let a site finish large batches sooner when the server is idle; Docker's default CPU weights still split CPU evenly between busy containers, so leave the host's CPU limit unset or generous rather than low. Processing stays one image at a time, so memory use does not grow with the thread count beyond libvips' per-thread buffers.
|
|
162
|
+
|
|
163
|
+
Only the JPEG, PNG, WebP, AVIF, GIF and TIFF decoders are enabled, and the decoded format must match the declared type, so an SVG named `.png` is rejected rather than rasterized.
|
|
117
164
|
|
|
118
165
|
```sh
|
|
119
166
|
bun x --no-install sandcms media rebuild
|
|
120
167
|
```
|
|
121
168
|
|
|
122
|
-
Rebuild compares the current preset hash, schedules missing sets, shows progress, and exits nonzero for failures. It does not delete old variants.
|
|
169
|
+
Rebuild compares the current preset hash, schedules missing sets, shows progress, and exits nonzero for failures. It does not delete old variants. `media rebuild --force` also re-encodes the active variants of every ready raster image under the same version and URLs; use it after an [R2 import](cloudflare.md) to replace variants encoded by Cloudflare. Rebuilds wait while the website's processor is busy, and never start the website's background tasks. Configure a later reviewed cleanup operation if you need to remove unreferenced historical variant keys.
|
|
170
|
+
|
|
171
|
+
### Changes from Cloudflare processing (0.7.0)
|
|
172
|
+
|
|
173
|
+
- Animated GIF and WebP inputs are flattened to their first frame.
|
|
174
|
+
- Metadata is stripped from variants except the EXIF copyright and artist fields.
|
|
175
|
+
- HEIC input is not supported.
|
|
176
|
+
- Inputs are no longer capped at 100 MB / 100 MP or a 20 MB output; `uploadLimit` and `maxPixels` set the limits.
|
|
177
|
+
- Imported variants keep their Cloudflare encoding until `media rebuild --force`; new variants are encoded by sharp under the same preset version.
|
|
178
|
+
|
|
179
|
+
### Checking and repairing files
|
|
180
|
+
|
|
181
|
+
```sh
|
|
182
|
+
bun x --no-install sandcms media verify
|
|
183
|
+
bun x --no-install sandcms media verify --repair
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`media verify` lists media rows whose original or active variants are missing on disk, for example after restoring a database snapshot that is newer than the media in a backup, and exits nonzero when any are missing. `--repair` queues missing variants to be rendered again when the original exists, and marks an image failed with "Original file is missing. Upload this image again." when it does not. Uploads in progress are not checked.
|
|
123
187
|
|
|
124
|
-
|
|
188
|
+
## Deletion
|
|
125
189
|
|
|
126
|
-
|
|
190
|
+
Editable asset fields come from file blueprints. If a blueprint declares a photographer relation, it references that field's configured collection. Publish a photographer's rename to update public credits; deletion clears the credit. Deletion displays known draft/published usages and allows confirmation without additional permission escalation.
|
|
127
191
|
|
|
128
|
-
|
|
192
|
+
Deletion clears draft/published references and revokes active variants immediately, then records cleanup in the durable `media_deletions` queue. Assets remain `deleting` until their files are removed. Cleanup waits for active uploads and processing to finish or their leases to expire; processing cannot restore the asset or schedule more work, and a file written after the deletion is removed again. Failures retry automatically, including after a website restart. The library polls pending deletions and excludes them from image pickers.
|
|
129
193
|
|
|
130
194
|
## Bulk uploads and galleries
|
|
131
195
|
|
|
132
|
-
The library and multi-image pickers accept multiple files in one selection. Files upload sequentially
|
|
196
|
+
The library and multi-image pickers accept multiple files in one selection. Files upload sequentially in selection order, each in chunks with a progress bar; a failed chunk is retried before the file is reported as failed. Errors name each failed file, and later files still upload. Successful uploads remain available when another file fails. Use the library's processing retry for files already accepted by the server.
|
|
133
197
|
|
|
134
198
|
Use a `gallery` field for ordered images. Its file blueprint defines available metadata; `overrides` explicitly enables per-placement editing of selected fields. A gallery without overrides displays images and ordering controls only. See [gallery configuration](content.md#galleries-and-project-specific-metadata). Both galleries and `media-list` fields support drag handles and arrow controls for ordering.
|