This page is for technical operators and developers. It covers database backups, the Cloudflare Worker, monitoring, and recovery procedures. If you're looking to manage your site's content or settings, see the site owner guides instead.

Cactus is stateful in two places: PostgreSQL and your media bucket. Back both up.

Recommended approach for PostgreSQL on Neon or Supabase:

• Enable Point-in-Time Recovery (PITR) - both providers offer it on paid plans. PITR lets you restore to any second in the past within your retention window, which is far more useful than a daily snapshot when debugging a bad migration.
• For self-hosted Postgres: use pg_dump scheduled via cron, ship the dump to an off-server location (another cloud storage bucket), and test restores occasionally.
• Manual one-off backup: admin > Settings > General has a "Download Backup" button that generates a full SQL dump (schema + data + sequence counters) on demand and downloads it straight to the browser. No object storage provider needed - it's independent of whatever media provider (B2 or otherwise) you have configured, or none at all. Good for a quick copy before a risky change; PITR/cron pg_dump is still the right answer for ongoing, unattended backups.

The download is taken from a single consistent snapshot. The whole read runs inside one repeatable-read, read-only transaction, so every table, every row and every counter in the file describes the database at the same instant. That matters because a busy site does not hold still while a backup is being written: without it, an order could be read after the counter that numbers orders had already been recorded, or a child record could be written referencing a parent whose table had already been read. Neither shows up when the file is downloaded. Both show up at restore, which is the worst possible moment to find out. The transaction is read-only, so taking a backup cannot change anything, and it is bounded to just under the request's own time limit - on a very large database the download can therefore time out rather than quietly returning a partial file.

The backup covers the database only. It does not contain your media files - those live in your bucket, and are covered separately below. Restoring a backup onto a site whose bucket has been emptied gives you all your pages and settings back, pointing at images that no longer exist.

If the download fails with "Cactus doesn't know how to back up" a particular column, that is deliberate. Rather than write a backup file that would silently fail months later when you actually needed it, Cactus refuses to write one it cannot guarantee. Report it - the fix is to teach the backup that column's type.

A .sql file from the Download Backup button can be restored in two places:

• admin > Settings > General on a running site.
• The setup wizard, on a brand-new install that hasn't been set up yet - useful for moving a site to a new host, or rebuilding after losing the database. The wizard's restore needs no sign-in, so it closes the moment an admin account exists, not only once setup is finished: restore before you create the admin, or finish setup and restore from Settings instead. Two uploads at once can't both run - restores take turns.

Restoring is destructive and complete: every existing row is wiped and replaced with the backup's contents, so the result is a faithful point-in-time copy rather than a merge. It runs in a single transaction - if anything fails partway, nothing is changed at all.

Things worth knowing:

• Modules. If the backup came from a site with a module you don't have installed here (the shop, say), that module's data is skipped and reported rather than aborting the whole restore. Install the module first if you want its data back. A module you do have gets its tables rebuilt automatically by the next deploy if they're ever missing (for example after a restore), so a module never ends up registered-but-broken.
• Media files. A backup carries the media catalogue - which files exist, their names, folders and alt text - but not the file bytes, which live in your storage bucket (see below). If the restore lands on a site that isn't connected to the storage those files use, it says so plainly on the finish screen: reconnect that bucket, or migrate your media across, and the images come straight back. Restoring onto the same bucket needs nothing - the files never moved.
• Sequence counters - such as the shop's order numbers - are restored along with the data, so the next order after a restore carries on from where the old site left off rather than re-issuing numbers that already exist.
• Version mismatches are refused, not fudged. If the backup was taken on a newer version of Cactus than the site you're restoring onto, the restore stops and tells you to update the site first. It won't quietly drop the data it has nowhere to put. Nothing is changed when it refuses.
• Some things cannot travel between sites, and are cleared rather than faked. See below.

A few things are locked to the site that made the backup. Every install has its own encryption key, generated when it is set up, and the backup file deliberately does not contain it - a backup that carried the keys to everything it protects would be a poor sort of secret. So a handful of items are unlocked by a key the new site simply doesn't have.

Rather than restore them and let you find out the hard way, the restore tries to read each one, clears anything it can't, and lists what it cleared on the screen when it finishes. Restoring onto the same site (rebuilding a lost database, say) keeps everything - the key hasn't changed, so nothing needs clearing.

What you'll need to set up again on the new site:

• The GitHub App connection, under admin > Settings > Integrations. Until you do, updates and the module directory won't work - they need GitHub access, and the old site's credentials are just so much noise here. If you're looking at a site restored before this behaviour existed, the Integrations tab now says so plainly and offers a Reconnect button, instead of insisting everything is fine while nothing works.
• Authenticator-app sign-in for admins, if anyone was using it. Sign in with your password and the code sent to your email, then set the authenticator up again from your account settings.
• Members' two-factor authentication. Nobody is locked out: any member whose authenticator or phone came across gets a code by email at sign-in instead, until they re-enrol from their own account settings.

Your pages, media, settings, users, orders and everything else come across exactly as they were.

Media backups:

• Backblaze B2 and Cloudflare R2 support bucket replication. Enable it for production.
• For other providers, use the provider's own snapshot or replication feature, or ship periodic exports to a secondary bucket.
• If you delete a media file via the admin, it's deleted from the provider immediately. There's no soft-delete or trash. Your bucket backup is the recovery path.

There are two ways to stand up the media Worker.

Automatic (recommended for non-technical operators). The admin Settings → General → Media panel has a Set up the Worker automatically box. The admin supplies a Cloudflare credential and Cactus deploys the Worker via the Cloudflare API - uploading the script, setting the provider secrets, enabling the *.workers.dev URL, and (when possible) attaching a media.<your-domain> Custom Domain - then writes the best public URL into CLOUDFLARE_WORKER_URL for them. No terminal required.

• Credential: either a scoped API token (recommended) with Account · Workers Scripts · Edit + Account · Account Settings · Read + Zone · Zone · Read, or the legacy Global API Key + account email. Both are obtained at https://dash.cloudflare.com/profile/api-tokens. Zone · Zone · Read is only needed for the Custom Domain step; without it the deploy still succeeds on the *.workers.dev URL.
• The credential is stored back as Vercel env vars for future re-deploys: CLOUDFLARE_API_TOKEN or CLOUDFLARE_GLOBAL_API_KEY + CLOUDFLARE_EMAIL (the two keys are stored sensitive), plus CLOUDFLARE_ACCOUNT_ID.
• The account must have a workers.dev subdomain claimed once (Cloudflare dashboard → Workers & Pages). If it doesn't, the deploy returns a clear error asking you to set one.
• Custom domain. When SITE_URL's host sits in a zone on the same Cloudflare account, the deploy attaches media.<zone-apex> to the Worker (Cloudflare provisions the DNS record and TLS certificate), stores that as CLOUDFLARE_WORKER_URL, and rebases every existing proxied Media.url onto it - via rebaseProxiedMediaUrls() in lib/media/upload.ts - so old and new images share one address. Direct-provider images (Cloudinary, ImageKit) are left on their own CDN. If no zone matches (domain managed elsewhere, or the token lacks Zone · Zone · Read), it falls back to the *.workers.dev URL and surfaces the reason. The certificate can take up to a minute to go live after the next site redeploy.
• Worker script name: cactus-media-worker. Re-running the deploy overwrites it in place.

Manual (wrangler). The Cloudflare Worker reads credentials from Worker secrets, not from Vercel environment variables. Configure these manually whenever you add or change a proxied provider.

# Set secrets for the providers you use (run from the workers/media-worker/ directory):

# Backblaze B2
wrangler secret put B2_APPLICATION_KEY_ID
wrangler secret put B2_APPLICATION_KEY
wrangler secret put B2_BUCKET_NAME
wrangler secret put B2_ENDPOINT

# Cloudflare R2
wrangler secret put R2_ACCOUNT_ID
wrangler secret put R2_ACCESS_KEY_ID
wrangler secret put R2_SECRET_ACCESS_KEY
wrangler secret put R2_BUCKET_NAME

# AWS S3
wrangler secret put S3_ACCESS_KEY_ID
wrangler secret put S3_SECRET_ACCESS_KEY
wrangler secret put S3_BUCKET_NAME
wrangler secret put S3_REGION

# DigitalOcean Spaces
wrangler secret put SPACES_ACCESS_KEY_ID
wrangler secret put SPACES_SECRET_ACCESS_KEY
wrangler secret put SPACES_BUCKET_NAME
wrangler secret put SPACES_REGION

# Wasabi
wrangler secret put WASABI_ACCESS_KEY_ID
wrangler secret put WASABI_SECRET_ACCESS_KEY
wrangler secret put WASABI_BUCKET_NAME
wrangler secret put WASABI_REGION

# MinIO
wrangler secret put MINIO_ENDPOINT
wrangler secret put MINIO_ACCESS_KEY_ID
wrangler secret put MINIO_SECRET_ACCESS_KEY
wrangler secret put MINIO_BUCKET_NAME

# Vercel Blob (BLOB_BASE_URL is the base URL of your blob store, e.g. https://xxxx.public.blob.vercel-storage.com)
wrangler secret put BLOB_BASE_URL
wrangler secret put BLOB_READ_WRITE_TOKEN

# Supabase Storage
wrangler secret put SUPABASE_STORAGE_PROJECT_URL
wrangler secret put SUPABASE_STORAGE_SERVICE_ROLE_KEY
wrangler secret put SUPABASE_STORAGE_BUCKET_NAME

# Required for all proxied providers
wrangler secret put ALLOWED_ORIGIN   # e.g. https://example.com

# Signing keys. Only needed if you deploy the Worker by hand - the
# "Deploy Worker" button in Settings > General > Media pushes both for you.
# Each is an HMAC-SHA256 of a fixed label under your SESSION_SECRET:
#   UPLOAD_SIGNING_SECRET = HMAC(SESSION_SECRET, "cactus-media-upload-v1")
#   ASSET_SIGNING_SECRET  = HMAC(SESSION_SECRET, "cactus-media-asset-v1")
wrangler secret put UPLOAD_SIGNING_SECRET
wrangler secret put ASSET_SIGNING_SECRET

UPLOAD_SIGNING_SECRET enables direct browser-to-Worker uploads; without it uploads fall back to the slower serverless route. ASSET_SIGNING_SECRET turns on protected reads for 3D models: the Worker will then refuse a model file unless the request carries a valid, unexpired token that Cactus stamped onto the URL. Without it the Worker serves models to anyone holding the address, which is how it behaved before this existed. Images are never gated either way.

Configure only the secrets for the providers you actually have items on - unused secrets have no effect. When you switch providers and choose "Switch without migrating", keep the old provider's secrets in place until migration is complete so that existing items continue to serve correctly.

Expired tokens accumulate in the database over time. Cactus doesn't run a background job, but the cleanup is a single query that's fast to run from a cron job or Vercel scheduled function:

-- Sessions expired more than N days ago (default: 30)
DELETE FROM "Session" WHERE "expiresAt" < NOW() - INTERVAL '30 days';

-- Unused recovery requests older than N days (default: 7)
DELETE FROM "RecoveryRequest" WHERE "expiresAt" < NOW() - INTERVAL '7 days' AND used = false;

-- Expired trusted devices
DELETE FROM "TrustedDevice" WHERE "expiresAt" < NOW();

-- Expired WebAuthn challenges (should be very short-lived)
DELETE FROM "WebAuthnChallenge" WHERE "expiresAt" < NOW();

-- Stale rate-limit windows
DELETE FROM "RateLimit" WHERE "windowStart" < NOW() - INTERVAL '1 hour';

The retention periods are configurable on Settings → General → GDPR & Legal. Schedule the cleanup SQL with your Postgres provider's scheduled jobs feature, a Vercel Cron job, or an external cron.

The Admin - Modules page checks each installed module for available updates once per page visit, throttled per module via a sessionStorage timestamp (cactus-module-update-check-{id}, 10s window) so a reload or quick navigate-away-and-back doesn't refire the check. For every installed module not already throttled, it fires a background GET /api/admin/modules/{id} call; if a newer GitHub release exists on that module's configured channel, the "Update" button appears without any manual action required. A per-module refresh icon (↻) forces an immediate re-check, bypassing the throttle. The check is a no-op when GitHub is not configured.

Each module has its own update channel (Module.updateChannel, 'public' or 'beta'), set independently via the Public/Beta buttons on its row - there is no longer a site-wide module update channel.

Enabling or disabling a module refreshes the admin sidebar immediately - nav links for the toggled module appear or disappear without a full page reload.

• Database connection pool saturation - watch pg_stat_activity or your provider's pool metrics. If you're near the limit, check DATABASE_URL is a pooled connection string.
• Vercel function errors - set SENTRY_DSN for structured error tracking. Without it, errors go to Vercel's function logs only.
• Failed modules/themes - the Modules/Themes admin page shows any item stuck in failed status with the error message.
• Deploy lock stuck - if a deploy fails uncleanly, DeployLock may remain set, and installs/updates answer "Another install or update is in progress". It clears itself: the row carries an expiresAt stamped by whoever took it (90 seconds for the normal in-request holders), and the next attempt after that sweeps it. The message tells you how long that is. Only a row written by an older build - no expiresAt - waits out the 15-minute fallback. Clearing it by hand is a last resort, not the first move:

  DELETE FROM "DeployLock" WHERE id = 'singleton';

  If the same lock keeps reappearing, the update is dying rather than running: check GitHub's status page, since a degraded GitHub is the usual cause of an update slow enough to be killed.
• A failed deploy still showing in the notification bell - a build that errors leaves the deploy panel on screen reading "Redeploy failed" until you press Dismiss. That is deliberate: dismissing is what reconciles the modules the build was carrying, rolling their pinned versions back to what the site is actually running. Nothing is in flight while it sits there, so installs, updates and redeploys stay available - press Dismiss when convenient and update again. (Before v0.5.1427 those buttons stayed greyed out until the panel was dismissed, which could leave a site unable to apply the very update that fixed its build.)
• The same build failure repeating on every update - a module left in deploying by a failed build keeps its pendingVersion, and every modules.json write pins pendingVersion ?? version. Before v0.5.1428 that meant an update launched straight after a failure re-pinned the exact tag that broke the last build, indefinitely. Installs, module updates and core updates now settle the previous deployment first: a build that already errored rolls its modules back to their confirmed versions before any pin is written. On an older core, loading the Modules page does the same reconcile - it checks every deploying row against its real deployment - so open that page once before updating again.

1. Go to /<adminPath>/login and click Lost access?.
2. Enter your email address and click Send recovery link.
3. Check your inbox, click the link (expires in 30 minutes).
4. Complete recovery - you are signed in and can register a new passkey from Account settings.

Changed: deleting the Passkey row no longer lets you register a replacement from the sign-in page. That shortcut trusted nothing but the email address you typed, so anyone who knew an admin's address could attach their own authenticator to that account and sign in as them. Enrolling a passkey now always requires an authenticated session first.

If the account has an authenticator app (TOTP):

1. Go to /<adminPath>/login and choose Use authenticator app instead.
2. Enter your email address and the 6-digit code. TOTP sign-in does not send email, so it works on a site with no email configured.
3. Once in, add a new passkey from Account settings → Security, and remove the old one.

If it does not, you need a second factor to exist before you can prove the account is yours - which means configuring email:

1. Add email credentials to your environment variables and redeploy.
2. Go to /<adminPath>/login, click Lost access?, and request a recovery link (expires in 30 minutes, single use).
3. Complete recovery - you are signed in and can register a new passkey from Account settings → Security.

1. Connect to your PostgreSQL database.
2. Generate a new bcrypt hash for a temporary password:

   node -e "const b = require('bcryptjs'); b.hash('TempPass123!', 12).then(console.log)"

3. Update the admin user's passwordHash:

   UPDATE "User" SET "passwordHash" = '<hash>' WHERE email = '[email protected]';

4. Add email credentials to your environment variables (if not already set). This is required, not optional: the password fallback issues a one-time code by email or SMS, so it cannot complete on a site with no email configured.
5. Sign in via the password fallback and register a new passkey from Account settings → Security.
6. Once your passkey is registered, change the temporary password to a strong one from Account settings → Password (passkeys remain your primary sign-in).

A signed-in admin can add or change their password from Account settings → Password (/<adminPath>/account), without touching the database.

• The section only appears when email is configured (Brevo or SMTP). The password sign-in relies on email to send a one-time code, so a password set without email would be useless. If email is not configured, the section shows a warning with a link to Settings instead of the form.
• If you have no password yet, the form takes a new password. If you already have one, it also asks for your current password before changing it.
• Passwords must be at least 12 characters and are checked against the Pwned Passwords breach list; breached passwords are rejected.
• A notification email is sent to your address whenever the password is added or changed.
• Removing a password is not yet supported from the UI; set a strong one and rely on passkeys for day-to-day sign-in.

1. Connect to PostgreSQL.
2. Find the Admin role:

   SELECT id FROM "Role" WHERE "isProtected" = true;

3. Assign it to an existing user:

   UPDATE "User" SET "roleId" = '<admin-role-id>' WHERE email = '[email protected]';

If a module migration fails during a build, the build will fail and Vercel will not deploy. The previous deployment stays live. To diagnose:

1. Check Vercel's build logs for the [module-migrations] lines.
2. Fix the SQL in your module's migrations folder.
3. If the broken migration was partially applied, you may need to roll it back manually in the database before retrying.
4. Commit the fix and push - this triggers a new build.

Most of a deploy is the compile, and the compile is cached: Cactus keeps the bundler's work in .next/cache, which Vercel restores from your previous deployment, so a small change recompiles only what actually changed. What is not cached is the part that talks to your database before the compile starts - migrations, the module ledger, manifest syncing - and that runs in full on every single deploy. Those steps each print their own duration in the build log (the [prebuild] lines), so you can see where the time is going rather than guess.

One lever is worth knowing about if your site has a lot of pages:

Set it in Vercel's project settings and redeploy. Leave it unset and every published page is pre-built exactly as before.

If deploys are slow for a reason you cannot see here, the build log tells the story from the top: dependency install, then the [prebuild] steps with their timings, then the compile.

A build that fails tells you why. A build that hangs tells you nothing: the log stops after Creating an optimized production build ..., Vercel kills the deployment at its 45-minute limit, and the site quietly stays on the previous version. This has one common cause and one automatic defence.

The cause is usually memory, not speed. The bundler holds the whole of your site's code in memory while it compiles. On a small build machine that can exceed the available RAM, at which point the machine starts swapping and the build makes no progress at all rather than failing outright. This is why a build that took under two minutes on Vercel's larger builder can fail to finish in forty-five on a smaller one: halving the processors would only have doubled the time, but halving the memory can stop it dead. Cactus pins Next.js at ^16.3.4 for exactly this reason - that release cut the bundler's memory use dramatically - so do not pin it lower.

The defence is built in. npm run build runs the compile under a watchdog. A build that has printed nothing for ten minutes, or has been running for twenty-five, is treated as stuck: it is killed, the bundler's cache is thrown away, and it is tried once more from cold. A build killed by the machine running out of memory gets the same second chance. A build that fails on its own merits - a genuine code error - is not retried, because that would only produce the same error twice. Everything the watchdog does is printed in the build log, prefixed [next-build].

If it still hangs, these environment variables are your levers. Set them in Vercel's project settings and redeploy:

If a cold retry with the cache off still cannot finish, the build genuinely does not fit on that machine: raise the build machine size in your Vercel project settings. The build log's [prebuild] lines each carry their own duration, so you can also see at a glance whether the time is going on the database and module steps or on the compile itself.

The Settings → General tab shows an Updates panel that checks the upstream Cactus Foundation repo for newer releases. It auto-checks once per visit (throttled client-side via sessionStorage for 10 seconds, so a reload doesn't refire it) and shows "Checking for updates..." while a check is in flight; a Refresh button forces an immediate re-check, bypassing both that 10-second window and the server's 10-minute cache. Two buttons at the top of the panel let you choose the update channel: Public (stable releases only, the default) or Beta (pre-releases included). The preference is stored in the database and takes effect immediately. If an update is available on the active channel, an Update now button appears. Clicking it:

1. Uses the GitHub API to diff between your installed version tag and the latest release tag on usersaynoso/cactus-foundation.
2. Copies changed core files into your GitHub repo (your GITHUB_REPO env var), skipping modules/, .gitmodules, and all database content.
3. Commits the changes and triggers a Vercel redeploy automatically.

Module code is pinned to the version recorded in your site's module registry - a build never fetches newer module code than that on its own. If any installed module has an update available, the confirmation dialog shows an "Also update" checkbox (ticked by default) listing the affected modules and their target versions: ticked, those modules are updated in the same deploy as core; unticked, core updates alone and your modules stay exactly as they are, with their "update available" flag left for you to apply later from the Modules page.

Checking for updates reads the public upstream releases directly and does not require your GitHub App installation to include the upstream repo. The check tries your authenticated GitHub connection first (so a private upstream fork the installation can reach still works) and falls back to an unauthenticated read of the public usersaynoso/cactus-foundation repo. As a result, the panel correctly shows the update card (or "Up to date") even when your App is only installed on your own deployment repo. If the check itself fails for some other reason, the panel says "Couldn't check for updates right now" rather than falsely reporting that GitHub is not configured.

Applying an update still requires GitHub to be configured (a GitHub App or GITHUB_API_TOKEN) with write access to your GITHUB_REPO. The upstream repo must publish GitHub Releases whose tags correspond to package.json versions (e.g. v0.5.97).

When an update fails because GitHub is having a bad day. Every update is a write to your GitHub repo, so a GitHub incident shows up here as an error that reads like your site's fault when it isn't. If the failure carries one of the tell-tale GitHub signatures - Resource not accessible by integration, a 5xx, a rate limit, a dropped connection - the update dialog (and the Modules page) now adds a line saying the problem is probably GitHub's end, with a link to githubstatus.com. Nothing is half-applied when a push fails: the whole update is one commit, so it either lands or it doesn't, and trying again once GitHub settles is safe. Resource not accessible by integration can also mean the GitHub App genuinely lacks write access to your repo, so if the status page is all green, check the App's permissions under admin > Settings > Integrations.

Requirements:

• GITHUB_REPO is set to your repo (e.g. myorg/my-cactus-site).
• GitHub App or GITHUB_API_TOKEN has write access to GITHUB_REPO.
• The upstream repo (usersaynoso/cactus-foundation or your CACTUS_CORE_REPO override) publishes tagged GitHub Releases.

What is preserved: Anything in modules/, .gitmodules, and all database rows (users, pages, layouts, media, settings). Only core files tracked in the upstream diff are overwritten.

Override the upstream repo: If you fork Cactus Foundation, set CACTUS_CORE_REPO=yourorg/your-fork so the Updates panel checks your fork instead.

Cactus core upgrades can also be done manually: npm update next @prisma/client prisma (and other dependencies), followed by a new prisma migrate dev if the schema changed, then push. The module migration runner runs before next build and is unaffected by core upgrades.

Adding or changing an environment variable requires either:

• A new Vercel deployment (for most variables), or
• Just saving in Vercel's project settings (for variables that aren't compiled into the build, like DATABASE_URL)

After changing SITE_URL, you must also re-register all passkeys - credentials are bound to the relying party ID (the domain). There is no automated migration for this.

Wiki: Home · Getting started · Running locally · Architecture overview · Authoring a module · Authoring a theme · Self-hosting and operations