Paymug

Paymug is a self-hosted Lemon Squeezy / Polar alternative for selling digital products and subscriptions. Connect PayPal or Stripe, get paid directly, and manage your store from one dashboard.

Built with Next.js 16, Tailwind CSS, Cloudflare D1, and Drizzle ORM.

Links and demo access

Features

• Sell your way — storefront, hosted checkout, one-time products, and subscriptions
• Get paid directly — connect PayPal or Stripe with sandbox and live modes
• Deliver automatically — files, license keys, and private GitHub access
• Grow sales — discounts, email campaigns, and affiliates
• Run everything in one place — customers, orders, refunds, analytics, and a buyer portal
• Own your stack — self-host on Cloudflare and extend with API keys

Quick start

npm install
cp .env.example .env.local   # optional — defaults work for local dev

# Apply D1 schema to the local Miniflare SQLite file
npm run db:migrate:local

npm run dev

Open http://localhost:3000.

Database commands

Schema: src/db/schema.ts · Client: src/db/index.ts · Queries: src/lib/db.ts

Configure payments (seller)

Payment credentials are read from environment variables and are never saved to the database. The dashboard is used only to choose which provider customers see at checkout.

1. Create a PayPal app at developer.paypal.com (or a Stripe account at dashboard.stripe.com).
2. Set the provider credentials as environment variables on the deployment (see the Environment table below for the exact names; one set for sandbox and one for live).
3. In Paymug: Dashboard → Payments → choose the active provider and click Set up webhook automatically for sandbox/live (creates the PayPal webhook pointing at the app; requires a public HTTPS app URL). For Stripe, create the webhook endpoint in the Stripe dashboard and set STRIPE_*_WEBHOOK_SECRET.
4. Publish a product and open its checkout link.

Use sandbox buyer accounts or Stripe test keys to test purchases.

Seller flow

1. Sign up → store created
2. Connect PayPal
3. Create & publish products
4. Share /buy/{id} or the storefront homepage /
5. Buyer pays your PayPal → order marked paid → delivery content shown

API surface (high level)

Environment

Set the GitHub OAuth App callback URL to <NEXT_PUBLIC_APP_URL>/api/github/oauth/callback.

AUTH_SECRET, ENCRYPTION_SECRET, and NEXT_PUBLIC_APP_URL are required at runtime: the app fails closed (session signing, secret decryption, and URL construction refuse to run) instead of falling back to a default or to the request Host header.

Cloudflare Email Service

1. In Cloudflare, open Compute → Email Service → Email Sending and onboard the sending domain.
2. Use a Workers Paid plan when sending to arbitrary customer addresses.
3. Configure EMAIL_FROM with an address on the onboarded domain, plus optional EMAIL_REPLY_TO. Store addresses are used only for replies; merchant alerts go to the Paymug account email.
4. The EMAIL Worker binding is already declared in wrangler.jsonc.

Deploy (Cloudflare)

Deploy Paymug to your Cloudflare account in one click:

The Cloudflare resources are intentionally not tied to the demo account. On the first deployment, Wrangler provisions a D1 database and R2 bucket in the deploying user's Cloudflare account. Each fork therefore has its own data and product storage.

npm run deploy

The deploy command applies pending D1 migrations before building and deploying the Worker.

Private UserGitRepo setup and automatic updates

Cloudflare's Deploy to Cloudflare button clones its source into a new repository in the deploying user's GitHub account and connects that repository to Workers Builds. The button source must be public, but the newly created UserGitRepo can be private. If the deployment must start directly from the private Paymug/paymug repository, use Cloudflare's authenticated repository import instead of a public Deploy button.

The update source is hardcoded as Paymug/paymug; users do not configure the source or destination repository name. GITHUB_REPOSITORY identifies UserGitRepo automatically inside GitHub Actions.

1. Give the purchaser's GitHub account read access to the private Paymug/paymug repository.
2. In UserGitRepo, open Settings → Secrets and variables → Actions and add one secret:

3. Ensure GitHub Actions is enabled for UserGitRepo. The included workflow declares contents: write, so its repository-scoped GITHUB_TOKEN can push the merged update back to UserGitRepo without another token.

After setup:

• .github/workflows/sync-upstream.yml checks Paymug/paymug/latest every six hours and can also be run manually. It safely merges new upstream commits and pushes UserGitRepo/main.
• That push triggers the Cloudflare Workers Build already connected during the one-click deployment. The sync workflow does not deploy a second time.
• /api/deployments exposes the current official Paymug version. Settings → About → Check for update reads that endpoint, so no GitHub token is stored in the Worker runtime.
• Build metadata discovers UserGitRepo from the Git remote; no repository environment variable is required.
• A merge conflict stops the update instead of overwriting user changes. Resolve it in UserGitRepo, then rerun Sync upstream updates.
• .github/workflows/deploy.yml remains an optional manual fallback. It needs CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, but normal Workers Builds deployments do not.

Keep runtime application secrets such as AUTH_SECRET, ENCRYPTION_SECRET, and payment credentials in Cloudflare. Automated deployments preserve variables and secrets already configured on the Worker.

Documentation

See docs/README.md for developer, API, and AI-agent guides. The documentation plan and completeness tracker are in docs/DOCS.md.

Roadmap ideas

• Stripe and Paddle as additional gateways
• Custom domains