Getting started

Linkbeam runs on your Cloudflare account as a Worker with D1, KV, R2, and Queues. This guide gets you from clone to a working local dev environment.

Prerequisites

1. Clone and install

git clone https://github.com/DerpcatMusic/linkbeam
cd linkbeam
bun install

2. Create Cloudflare resources

Create the bindings Linkbeam expects, then copy the IDs into wrangler.jsonc.

wrangler d1 create linkbeam
wrangler kv namespace create LINK_CACHE
wrangler r2 bucket create linkbeam-artwork
wrangler queues create linkbeam-conversions
wrangler queues create linkbeam-conversions-dlq

Replace REPLACE_WITH_D1_DATABASE_ID and REPLACE_WITH_KV_NAMESPACE_ID in wrangler.jsonc. See the configuration reference for every binding.

3. Apply database migrations

bun run db:migrate:local   # local D1 for dev
bun run db:migrate         # remote D1 for production

4. Configure secrets

RATE_LIMIT_SECRET is required for privacy-safe email-signup limits. Meta and Spotify credentials unlock full tracking and import.

wrangler secret put META_PIXEL_ID
wrangler secret put META_ACCESS_TOKEN
wrangler secret put SPOTIFY_CLIENT_ID
wrangler secret put SPOTIFY_CLIENT_SECRET
wrangler secret put RATE_LIMIT_SECRET

5. Run locally

bun run dev

Open /admin on the dev server. The onboarding wizard at /admin/onboarding checks bindings, secrets, and migrations for you.

6. Deploy

bun run build
bun run deploy

By default the worker is available on *.workers.dev. Add a custom domain route in wrangler.jsonc when you are ready, and set PUBLIC_BASE_URL to that host.

Already running an older music-shortlink deploy? Keep your existing Cloudflare resource names and domain. Point your deployment fork at this repo and sync product code — see deployment workflow.

Next steps