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.
| Worker | Does |
|---|---|
pageflock-ingest | Serves the tracking script, takes events at /api/e, and stores each site's analytics in its own Durable Object |
pageflock-app | The 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 SALTSPut 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.
| Name | Type | Value |
|---|---|---|
BETTER_AUTH_URL | Variable | The app's public URL, for example https://pageflock.example.com |
INGEST_URL | Variable | The ingest Worker's public URL, for example https://in.example.com |
MAIL_FROM | Variable | A sender on a domain verified in Resend: Pageflock <pageflock@example.com> |
BETTER_AUTH_SECRET | Secret | A long random string: openssl rand -base64 32 |
RESEND_API_KEY | Secret | A Resend API key with sending access |
SIGNUP_ALLOWLIST | Secret | Who may create an account: addresses and @domains, comma separated. Empty lets anyone sign up |
AUTH_GITHUB_CLIENT_ID, AUTH_GITHUB_CLIENT_SECRET | Secret | Optional GitHub sign-in |
AUTH_GOOGLE_CLIENT_ID, AUTH_GOOGLE_CLIENT_SECRET | Secret | Optional 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 devThe 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.