Skip to content

Configuration and environment

Almost everything about a DragonslairCMS site is configured in its admin and stored in the database, so you rarely need to edit anything else. This page covers what’s left: wrangler.jsonc, secrets and credentials.

Key Value Notes
name dragonslaircms The Worker’s name, and part of its *.workers.dev address.
main src/index.js The Worker entry point.
compatibility_date 2025-06-01
compatibility_flags nodejs_compat
assets directory: ./public, binding: ASSETS Static CSS, JavaScript and icons.
d1_databases binding: DB, database_name: dragonslaircms No database_id is committed. See below.
r2_buckets binding: MEDIA, bucket_name: dragonslaircms Uploaded media, fonts and emoticons.
send_email name: EMAIL Optional. See Email.
triggers.crons */15 * * * * Scheduled publishing. See below.

The committed file deliberately has no database_id. The Deploy to Cloudflare button and wrangler deploy (Wrangler 4.45 or later) create any D1 database or R2 bucket in the file that doesn’t exist yet, and write the new ID back into wrangler.jsonc. npm run setup creates the database itself and writes the ID in.

To create the resources yourself instead:

Terminal window
npx wrangler d1 create <database-name>
npx wrangler r2 bucket create <bucket-name>

and paste the ID that d1 create prints into d1_databases[0].database_id:

"d1_databases": [
{
"binding": "DB",
"database_name": "<database-name>",
"database_id": "<database-id>"
}
]

npm run setup does this for you. By hand, the Worker, the database and the bucket can each be renamed independently:

  • Worker name: the top-level name.
  • D1 database name: d1_databases[0].database_name. That’s the only place; the db:schema* scripts use the binding, not the name.
  • R2 bucket name: r2_buckets[0].bucket_name.

Don’t rename the bindings (DB, MEDIA, EMAIL, ASSETS). The code refers to those.

No vars block is needed. If you add one, these are used as fallbacks until the matching setting is saved in the admin’s Settings:

Var Fallback for
SITE_TITLE Organisation name
SITE_URL Site URL (canonical)
SITE_EMAIL_FROM Email “From” address

The setting in the admin always wins. There’s no SITE_TAGLINE: the tagline is only ever the Tagline setting.

siteUrlError in src/site-url.js is the one check on the site URL, whether it comes from Settings or SITE_URL. It must be just a scheme and a host, with an optional port: no path, query or trailing slash (a trailing slash typed in Settings is removed before the check). It must be https://, except for a loopback host (localhost, a *.localhost name, 127.0.0.1 or [::1]), which may be http:// so that mail works under wrangler dev.

A value that fails the check counts as unset. With no site URL, email stays off, because every link in an email is built from it and never from the host a request arrived on. The setting can only be changed by an admin, since it decides where password-reset links point.

When anybody sets a new password, the Worker asks Have I Been Pwned’s range API (api.pwnedpasswords.com) whether it has appeared in a breach. Only the first five hex characters of the password’s SHA-1 are sent. If the API is slow (over two seconds) or down, the password is accepted, so no configuration is needed and an outage never blocks anyone.

Admin and reader session cookies are signed with two secrets, ADMIN_SESSION_SECRET and READER_SESSION_SECRET. You don’t have to set either: on first use, the Worker generates a random 32-byte value for each and stores it in the site_config table (keys admin_session_secret and reader_session_secret).

To manage them yourself, set them as Worker secrets:

Terminal window
npx wrangler secret put ADMIN_SESSION_SECRET
npx wrangler secret put READER_SESSION_SECRET

Use 32 or more random characters, for example from openssl rand -hex 32. A secret you set always wins over a generated one. Setting or changing one logs out everybody in that realm: all CMS users for the admin secret, all readers for the reader secret. The reader secret also signs the anti-spam token on public forms, so an anonymous comment or correction sent from a page that was loaded before the change is silently dropped.

Generated secrets live in the database, so a fresh database gets fresh secrets.

For local development, .dev.vars does the same job; see Local development.

npx wrangler login is the easiest way to authorise your own machine. For CI, or a machine where you can’t log in with a browser, copy .env.example to .env, uncomment the two lines and fill them in:

Terminal window
CLOUDFLARE_API_TOKEN=<api-token>
CLOUDFLARE_ACCOUNT_ID=<account-id>
  • Create the token in the Cloudflare dashboard under My Profile → API Tokens, from the Edit Cloudflare Workers template, and add a D1 → Edit permission. The template already covers Workers and R2, but not D1, which the deploy script writes to.
  • Your account ID is in the dashboard under Workers & Pages in the right-hand sidebar, or from npx wrangler whoami.

.env is gitignored; never commit it. In a hosted CI system, set the two values as the system’s secret environment variables instead of a file.

The Cron Trigger in wrangler.jsonc runs the Worker’s scheduled handler every 15 minutes, which publishes any draft article whose scheduled time has passed. Cron Triggers are available on the Workers Free plan.

You can change the schedule in triggers.crons. The admin’s article editor says scheduled articles are “checked every 15 min”, so a different interval makes that hint wrong. Removing the trigger turns scheduled publishing off: articles can still be scheduled, but nothing publishes them.