Run misomoon in your Cloudflare account

This guide deploys misomoon to your own Cloudflare account. Then it walks you through claiming your instance and tracking your first site. misomoon runs as one Worker with D1 databases and a queue. You have no server or container to manage.

There are two ways to deploy:

• With the Deploy to Cloudflare button. This takes about 5 minutes and needs only a browser.
• From the command line. Use this to change the code, to run more shards, or to deploy from your own CI.

#Before you start

You need a Cloudflare account. The Workers Free plan works for small sites. The Free plan's queue allows 10,000 operations a day, and each event uses about 3, so it handles about 3,000 events a day. For more traffic, use the Workers Paid plan. See Workers pricing, D1 pricing, and Queues pricing.

misomoon creates these resources in your account:

#Deploy with the button

1. Select the button:

   

2. Sign in to Cloudflare, and connect your GitHub or GitLab account. Cloudflare copies the deploy bundle into a new repository that you own.

3. Keep the default names for the databases and the queues, or change them. The migrations use binding names, so any names work.

4. Select Create and deploy. The build creates the databases and the queues, applies the migrations, and deploys the Worker.

5. When the deploy is done, open the Worker's URL. It looks like https://misomoon.<your-subdomain>.workers.dev.

Continue with claim your instance.

The button deploys the bundle that CI builds from main and publishes to the deploy branch. It sets SIGNUPS to invite, so only the first person can sign up.

#Deploy from the command line

You need Node.js 22.5 or later, pnpm 10, and git.

1. Clone the repository and install the dependencies:

   shCopy

   git clone https://github.com/jackzard/misomoon.git
   cd misomoon
   pnpm install

2. Sign in to Cloudflare:

   shCopy

   pnpm --filter @misomoon/api exec wrangler login

3. Close open sign-up. In apps/api/wrangler.jsonc, set SIGNUPS in vars to invite. Change the line if vars already has one, so the key appears once:

   jsoncCopy

   "SIGNUPS": "invite"

   The first account can still sign up. Everyone after that needs an invitation.

4. Deploy:

   shCopy

   pnpm --filter @misomoon/api run deploy

   The command builds the tracker and the dashboard. On the first run, it also creates the three D1 databases and the two queues, and writes the database ids into apps/api/wrangler.jsonc. Then it applies the migrations and deploys the Worker. Commit the changed wrangler.jsonc, so that the next deploy uses the same databases.

5. Open the URL that the deploy prints.

To keep the data in the EU, set D1_JURISDICTION=eu on the first deploy. D1 then runs and stores the databases only in the EU. Cloudflare sets a database's jurisdiction when it is created and never changes it, so set it before the first deploy, and on every run that adds shards. D1 data location has the details.

To start with more shards, set SHARD_COUNT, for example SHARD_COUNT=4 pnpm --filter @misomoon/api run deploy. Scale the shards explains when you need more.

#Claim your instance

1. Open your misomoon URL, and select Create an account.
2. Enter your email, name, and password. This account owns the instance.

After this, the sign-up link is gone. To add people, open Settings, and invite them to your team.

Claim the instance right after the deploy. Until the first account exists, anyone who knows the URL can sign up.

#Track your first site

1. In Settings, add your site's domain.

2. Copy the snippet, and paste it into the <head> of every page:

   htmlCopy

   <script defer src="https://misomoon.example.workers.dev/m.js?s=your-site"></script>

3. Open your site. You appear in Live within a few seconds.

The tracking guide covers custom events, revenue, and goals.

#Use your own domain

To use a domain such as analytics.example.com:

1. Add the domain to Cloudflare as a zone, if it isn't one already.
2. In the Cloudflare dashboard, open Workers & Pages, and select the misomoon Worker.
3. Open Settings > Domains & Routes, and select Add > Custom domain.
4. Enter analytics.example.com, and save.
5. Set the PUBLIC_URL variable to https://analytics.example.com. Then the links in email reports point to the right place.

Update the snippet on your sites to use the new domain.

#Turn on optional features

Each feature needs a secret or a variable. In the Cloudflare dashboard, open the Worker, then Settings > Variables and Secrets. From the command line, run wrangler secret put <NAME> in apps/api.

The configuration reference explains each one.

Without an email provider, invitations still work. The dashboard shows the invitation link, and you send it yourself.

A variable that you set in the Cloudflare dashboard is replaced by the next deploy from the repository. To keep a variable, put it in vars in wrangler.jsonc. Secrets are not affected.

#Next steps

• Connect Claude, Cursor, or another MCP client.
• Serve the tracker from your own domain so that ad blockers don't drop events.
• Upgrade to a new version.
• Fix common problems.