Deployment

CaretCMS runs anywhere Astro does. Pick a delivery mode first, then match storage to your host.

1. Static delivery — caret({ delivery: 'static' }), bake at build, deploy to a CDN (guide)
2. Server delivery — output: 'server' + adapter, per-request rewrite in production
3. Storage adapter must match the host’s filesystem semantics
4. Editor secrets as environment variables

Pre-flight checklist

Run through this before any production deploy:

Static delivery (CDN / static host)

• caret({ delivery: 'static' }) in astro.config.mjs
• CI runs astro build after publish (webhook or git pull)
• Optional: CARET_GIT_ON_PUBLISH=true to commit .caret/data/ on publish
• Build environment can read storage (.caret/data/ in repo or mounted)
• CARET_EDIT_PASSWORD / CARET_SESSION_SECRET set where authoring runs (dev/staging)

Server delivery (Node / Workers)

• output: 'server' in astro.config.mjs (+ adapter)
• CARET_EDIT_PASSWORD set in host env (or editing disabled)
• CARET_SESSION_SECRET set to a long random value, not committed to git
• HTTPS enforced on your domain
• Storage adapter matches the host (see table below)
• If you don’t want editing on this environment, set enableAdmin: false and enableInlineEditor: false

Adapter per host

Host	Adapter	Notes
Static CDN (Netlify, Vercel static, S3, Pages)	Filesystem (default)	Static delivery — bake at build; no CMS routes in prod
Node (Fly, Railway, Render, your VPS)	Filesystem (default)	Server delivery; mount a persistent volume
Cloudflare Workers	cloudflareStorage + r2Uploads	Server delivery; KV + R2 bindings required
Vercel / Netlify (serverless)	Custom (Postgres / KV)	Server delivery; no writable filesystem

Pick your host

Static CDN

The default path for marketing and brochure sites. No SSR adapter.

1. Configure static delivery

   astro.config.mjs

   import caret from '@caretcms/core';
   
   export default defineConfig({
     integrations: [
       caret({
         delivery: {
           mode: 'static',
           publish: {
             webhookUrl: process.env.CARET_REBUILD_WEBHOOK_URL,
           },
         },
       }),
     ],
   });

2. Author in dev — npm run dev, sign in at /admin, edit and publish.

3. Build and deploy

   npm run build

   Confirm [caretcms] static delivery bake complete in the logs. Deploy dist/.

4. Wire CI — on publish, trigger a build that has access to .caret/data/ (committed to git or fetched from staging).

See Static delivery for the full flow.

Node / VPS

The simplest path. Filesystem storage works as long as you have one process and a persistent disk.

1. Install the Node adapter

   npm install @astrojs/node

2. Configure Astro

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import node from '@astrojs/node';
   import caret from '@caretcms/core';
   
   export default defineConfig({
     output: 'server',
     adapter: node({ mode: 'standalone' }),
     integrations: [caret()],
   });

3. Mount a persistent volume

   CMS edits land in .caret/data/. If your host wipes the filesystem on each deploy, mount a volume there.

   Fly.io

   fly.toml

   [mounts]
     source = "cms_data"
     destination = "/app/.caret/data"

   Railway / Render

   Attach a Volume to the service, mount at /app/.caret/data.

   Docker / docker-compose

   Declare a volume on /app/.caret/data in your compose file or service config.

   Without a persistent volume

   Every deploy resets edits to the values in your repo. Some teams prefer this (content stays git-tracked), but you’ll lose anything edited between deploys.

4. Set environment variables

   CARET_EDIT_PASSWORD=...
   CARET_SESSION_SECRET=...
   CARET_TRUST_PROXY=true   # if you terminate TLS at a proxy/load balancer

   Set these in your host’s dashboard or CLI. Never commit them. Behind Nginx, a load balancer, or Cloudflare’s proxy, set CARET_TRUST_PROXY=true so the Secure cookie flag is derived from X-Forwarded-Proto rather than the (plain HTTP) connection to the origin.

Single instance only

The default filesystem adapter serializes revision writes within a single Node process. Don’t run multiple instances against the same volume — concurrent processes can race the revision counter. If you need horizontal scale, use a custom DB-backed adapter.

Cloudflare Workers

Use @caretcms/cloudflare for KV storage and R2 uploads. Edge-distributed, no servers to manage.

Dev runs on workerd too (Astro 6)

Astro 6’s dev server runs the same workerd runtime as production, so a Workers-targeted project has no filesystem in astro dev either. Use cloudflareStorage from day one — the default filesystem adapter now throws a clear error on workerd rather than silently failing on reads and crashing on writes.

Quick decision: Targeting Workers? Cloudflare adapter in dev and prod. Targeting Node? Filesystem is fine in both.

1. Install

   npm install @astrojs/cloudflare @caretcms/cloudflare

2. Configure Astro

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import cloudflare from '@astrojs/cloudflare';
   import caret from '@caretcms/core';
   import { cloudflareStorage, r2Uploads } from '@caretcms/cloudflare';
   
   export default defineConfig({
     output: 'server',
     adapter: cloudflare(),
     integrations: [
       caret({
         storage: cloudflareStorage({ binding: 'CMS_KV' }),
         uploads: r2Uploads({ binding: 'CMS_R2' }),
       }),
     ],
   });

3. Configure wrangler.toml

   wrangler.toml

   name = "my-site"
   compatibility_date = "2025-01-01"
   compatibility_flags = ["nodejs_compat"]
   
   # No `main` / `[assets]` — @astrojs/cloudflare v13+ generates the worker
   # entry and asset config at build time (dist/server/wrangler.json) and
   # merges these bindings into it.
   
   [[kv_namespaces]]
   binding = "CMS_KV"
   id = "<your-kv-namespace-id>"
   
   [[r2_buckets]]
   binding = "CMS_R2"
   bucket_name = "my-site-uploads"

   See the Cloudflare Astro framework guide for the authoritative, up-to-date Workers config.

4. Set secrets (not in wrangler.toml)

   wrangler secret put CARET_EDIT_PASSWORD
   wrangler secret put CARET_SESSION_SECRET

5. Deploy

   npm run build
   wrangler deploy

Quirks

• Eventual consistency — KV is eventually consistent (~60s). After a save, an immediate read might return the old value from another POP. Studio handles this by reading from the same edge that wrote.
• R2 public URLs need a custom domain or r2.dev enabled — check the bucket settings. Set R2_PUBLIC_DOMAIN (or pass publicBaseUrl to r2Uploads()) so uploaded files resolve to the right public base URL; otherwise upload URLs may point at an unreachable host.
• CPU limits — Workers have a 30s CPU limit per request. The CMS routes are well under this; if you build heavy custom adapters, keep them async-light.

Vercel / Netlify

Vercel and Netlify don’t give you a writable filesystem. Filesystem adapter is out. You need a database-backed custom adapter.

1. Implement a custom adapter

   src/cms/postgres-storage.ts

   import type { StorageAdapter } from '@caretcms/core';
   
   class PostgresStorageAdapter implements StorageAdapter {
     // ...all required methods
   }
   
   export default function postgresStorage() {
     return new PostgresStorageAdapter(/* config from env */);
   }

2. Wire it up

   astro.config.mjs

   caret({
     storage: defineStorageProvider({
       entrypoint: './src/cms/postgres-storage.ts',
       exportName: 'default',
     }),
   })

3. Push uploads to blob storage — S3, R2, or your provider’s blob storage. Implement UploadHandler similarly.

See Storage Adapters → Custom adapter for the full interface.

Split static + CMS

You can run static delivery for the public site and keep a separate server environment for authoring only (staging). Editors publish on staging; CI rebuilds and deploys static dist/ to production. No split-origin CORS workarounds needed.

Alternatively, use server delivery on one host if you want production inline editing.

Hardening checklist

Once deployed:

• Visit https://your-site/admin over HTTPS — confirm cookie has Secure flag (devtools → Application)
• Try logging in with the wrong password — should reject
• Try POST /api/cms/mutate without the CSRF header — should return 403
• Try POST /api/cms/mutate without a session cookie — should return 401
• Confirm /admin is gated (no editor JS on public pages without the cookie)
• If Cloudflare: check wrangler tail for errors after a save
• If Node: check the host’s logs for [caretcms] messages on boot

Content Security Policy

The inline editor runs cleanly under Astro’s strict CSP with no extra configuration:

astro.config.mjs

export default defineConfig({
  output: 'server',
  security: { csp: true },
  integrations: [caret()],
});

Astro auto-hashes the editor’s injected bootstrap, and every other editor asset — editor.js, its module imports, and editor.css — is served same-origin from /__caret/, so the default script-src 'self' and style-src 'self' cover them. The editor’s API calls hit same-origin /api/cms/*, which Astro’s CSP doesn’t restrict. This path is covered by an end-to-end test that asserts zero CSP violations through a full edit-and-save.

Don't enable strict-dynamic

Do not set scriptDirective.strictDynamic: true. strict-dynamic disables host-based allowlisting ('self'), which blocks Astro’s own bundled page scripts — and the editor relies on 'self' because all its assets are same-origin. Plain csp: true is the correct setting.

Two Astro CSP limitations to know:

• Production only — Astro emits the policy for astro build (+ preview/deploy), not astro dev. Test CSP against a preview build, not the dev server.
• No <ClientRouter /> — Astro’s view transitions are not supported with CSP.

If you set CSP yourself via response headers (e.g. at the Cloudflare edge) instead of Astro’s API, allow same-origin sources: script-src 'self', style-src 'self', and connect-src 'self' for the editor’s API calls.

Disabling editing in prod

If your prod environment shouldn’t be editable (you only edit on staging, then promote):

caret({
  enableAdmin: import.meta.env.MODE === 'staging',
  enableInlineEditor: import.meta.env.MODE === 'staging',
})

In prod with server delivery, no admin routes are mounted when disabled; the rewrite middleware still runs. With static delivery, production is plain static HTML — disable authoring on any server-side preview by setting the toggles from import.meta.env.

Performance

The only CaretCMS code on the hot path of every HTML response is the rewrite engine — the order: 'pre' middleware runs it over the rendered body to inject stored overrides. It’s string-based (no DOM parser) and fast: on commodity hardware it adds single-digit microseconds to a page with no editable content, well under 0.1 ms to a typical page (a dozen editable fields), and ~1 ms to a large page with 150 bindings.

Measure it on your own hardware with npm run bench. A regression tripwire in the unit suite fails the build if a large-page rewrite ever blows past a generous ceiling, so a super-linear regression can’t slip in unnoticed.

Next steps

Static delivery CDN deploy with build-time bake.

Authentication & Security Production hardening.

Storage Adapters Pick the right one for your host.

Troubleshooting Common deploy failures.