Skip to Content
Pageflock

Self-hosting on Cloudflare

Run Pageflock on your own Cloudflare account, deployed from GitHub Actions.

Pageflock is open source and runs entirely on Cloudflare: two Workers, a D1 database, a KV namespace and Durable Objects. Most sites fit in the Workers free plan; see Costs.

WorkerDoes
pageflock-ingestServes the tracking script, takes events at /api/e, and stores each site's analytics in its own Durable Object
pageflock-appThe dashboard, sign-in, the REST API and the MCP server

GitHub Actions deploys both from .github/workflows/ci.yml: every push to main deploys to production once the checks pass, and every pull request gets a preview. Ingest always goes first, because it owns the Durable Object class the app reads from.

Requirements

  • A Cloudflare account
  • A fork of thebuilder/pageflock
  • A Resend account for sign-in mail, with a verified sending domain
  • Node.js 26 and pnpm 10, to run the setup commands

Create the storage

npx wrangler login
npx wrangler d1 create pageflock
npx wrangler kv namespace create SALTS

Put the D1 database ID in apps/app/wrangler.jsonc as database_id, and the KV namespace ID in apps/ingest/wrangler.jsonc as the SALTS id. Commit both files.

Create an API token

In the Cloudflare dashboard, create an API token from the Edit Cloudflare Workers template, and add D1 Edit to it.

Add it to GitHub

In your fork, under Settings, Secrets and variables, Actions, add the CLOUDFLARE_API_TOKEN secret and your CLOUDFLARE_ACCOUNT_ID (as a variable or a secret). The deploy job runs in the production environment, so you can scope them to it.

Configure the app

Add these to the production environment. Each deploy passes them to pageflock-app. A secret you leave unset keeps the value the Worker already has.

NameTypeValue
BETTER_AUTH_URLVariableThe app's public URL, for example https://pageflock.example.com
INGEST_URLVariableThe ingest Worker's public URL, for example https://in.example.com
MAIL_FROMVariableA sender on a domain verified in Resend: Pageflock <pageflock@example.com>
BETTER_AUTH_SECRETSecretA long random string: openssl rand -base64 32
RESEND_API_KEYSecretA Resend API key with sending access
SIGNUP_ALLOWLISTSecretWho may create an account: addresses and @domains, comma separated. Empty lets anyone sign up
AUTH_GITHUB_CLIENT_ID, AUTH_GITHUB_CLIENT_SECRETSecretOptional GitHub sign-in
AUTH_GOOGLE_CLIENT_ID, AUTH_GOOGLE_CLIENT_SECRETSecretOptional Google sign-in

Deploy

Push to main, or re-run the latest CI run on main. Then add custom domains to both Workers in the Cloudflare dashboard (Workers, your Worker, Settings, Domains and Routes), matching BETTER_AUTH_URL and INGEST_URL.

To deploy by hand instead: pnpm build, then npx wrangler deploy in apps/ingest, then npx wrangler d1 migrations apply DB --remote && npx wrangler deploy in apps/app.

Point your sites at it

Install the tracking as usual, with your own ingest URL:

<Analytics site="SITE_ID" endpoint="https://in.example.com/api/e" />
<script defer src="https://in.example.com/s.js" data-site="SITE_ID"></script>

The install screen in your dashboard fills these in for you, and the agent prompt carries the endpoint too.

On a public instance

Set SIGNUP_ALLOWLIST. People a workspace invites can always create an account, and people who already have one can always sign in. Sign-in requests are also limited to 10 a minute per IP by a rate-limit binding that needs no setup.

Without RESEND_API_KEY, production refuses to send mail rather than writing sign-in links to the logs.

Costs

Pageflock writes each event to the site's Durable Object and rolls it up later, which costs Durable Object rows read and written. The Workers free plan allows 5 million rows read a day for the whole account; once that is used up, tracking and dashboards stop until midnight UTC. For busy sites, use Workers Paid, where Pageflock's cost is small.

Local development

pnpm install
cp apps/app/.dev.vars.example apps/app/.dev.vars
cp apps/ingest/.dev.vars.example apps/ingest/.dev.vars
pnpm --filter @pageflock/app db:migrate
pnpm dev

The app runs on http://localhost:3000 and ingest on http://localhost:8788. Sign-in links print in the terminal. pnpm seed --email you@example.com fills a demo site with 90 days of traffic.

On this page