Skip to content

Installation

Installing DragonslairCMS gives you your own Worker, D1 database and R2 bucket on your own Cloudflare account. There are two easy ways to do it. Neither asks you to generate secrets or paste resource IDs, and the site’s name, address and email sender are set in the admin afterwards, not in config files.

  • A Cloudflare account. The Workers Free plan runs the whole CMS: Workers, D1, R2 and the Cron Trigger for scheduled publishing all work on it. If you’ve never used R2 on the account, enable it in the Cloudflare dashboard first.
  • Only if you want the site to send email: the Workers Paid plan, a domain on Cloudflare with Email Routing set up, and a verified sending address. Email is optional; without it the CMS runs in no-email mode. See Email.
  • For the command-line route: Node.js 20 or later (22 is recommended; it’s the version in .nvmrc) and Git.

The Deploy to Cloudflare button at the top of the project’s README does everything in the browser:

  1. It copies the repository into your own GitHub or GitLab account.
  2. It creates the D1 database and R2 bucket.
  3. It builds and deploys the Worker, applying schema.sql to the new database as part of the deploy.
  4. It connects your copy of the repository to the Worker, so every push to its main branch deploys.

There’s nothing to fill in. When it finishes, open your Worker’s address and carry on at First run.

Terminal window
git clone https://github.com/kihitara/dragonslaircms.git
cd dragonslaircms
npm install
npx wrangler login # authorise this machine with your Cloudflare account
npm run setup

npm run setup runs scripts/setup.js, which:

  1. Checks Wrangler is installed and you’re logged in, and offers to run wrangler login if you aren’t.
  2. Asks for a Worker name, a D1 database name and an R2 bucket name. Press Enter to accept the defaults: dragonslaircms for the Worker, and the Worker’s name for the other two. Names are lowercase letters, numbers and hyphens. The Worker name becomes part of your *.workers.dev address.
  3. Creates the database and bucket (carrying on if they already exist).
  4. Writes the names and the new database_id into wrangler.jsonc.
  5. Applies schema.sql to the remote database.
  6. Asks whether to deploy, and runs wrangler deploy.

It never asks for secrets. Two flags are useful:

Terminal window
npm run setup -- --dry-run # print every step without changing anything
npm run setup -- --no-deploy # do everything except the deploy

When it’s done, the script prints the next steps, which are the ones below.

To set things up entirely by hand instead, see Configuration and environment.

Open your Worker’s address (https://<worker-name>.<your-subdomain>.workers.dev) and go to /admin. With an empty database you’re sent to /admin/setup, a one-time screen where you create the first admin account (the password needs 12 or more characters and mustn’t be in a known breach). Do this straight away: until an account exists, anyone who finds the address can claim the site.

Then, in the admin’s Settings:

  • Set Organisation name and Tagline.
  • Set Site URL (canonical) to your public address, starting https://, with nothing after the domain. The RSS feed, the sitemap and links in emails use it, and email stays off until it’s set.
  • On the Free plan, or without an email domain, turn Send outgoing email off. Otherwise set the Email “From” address to your verified sender.
  • Choose the Home page: a static home page, or a feed of your latest articles.

Everything else (logo, colours, fonts, navigation, pages, articles and email wording) is edited in the admin too. The user guide covers it.

As an alternative to /admin/setup, scripts/seed-admin.js prints the SQL for an admin account, with the password hashed the same way the Worker hashes it:

Terminal window
node scripts/seed-admin.js <email> "<name>" <password> > /tmp/seed.sql
npm run db:schema:remote # if the schema isn't applied yet
npx wrangler d1 execute DB --file=/tmp/seed.sql --remote

Use --local instead of --remote for your local database.

If an account with that email already exists, the script’s SQL sets its password and reactivates it instead (its role stays the same). That makes it a way back in if you’ve locked yourself out.

The SQL file contains the password hash, so delete it afterwards. The password itself will be in your shell history; change it from the admin once you’re in.