Skip to content

Self-hosting

Customer.lite is open source, and you can run it on your own Cloudflare account: the same open-source code the managed service is built on, with your own email provider account. A self-hosted installation has no plan limits and no billing.

One Worker serves everything on one origin, your <app-origin> (for example https://app.example.com):

Path What
/api/* The REST API, and sign-in under /api/auth/*
/mcp MCP for AI assistants
/u/* One-click unsubscribe links
/approvals/* Send approval pages
/provider-events/ses Delivery events from Amazon SES
/operator/* Operator endpoints, only when OPERATOR_TOKEN is set
everything else The dashboard

The Worker uses a D1 database for accounts and settings (CONTROL_DB), one Durable Object per project for that project’s data (PROJECTS), a Queue for deliveries, and a daily cron that deletes expired sign-in records. The development configuration, apps/workers/wrangler.jsonc, declares them all.

CONTRIBUTING.md runs the whole app on your machine with wrangler dev and a fake email provider that sends nothing. It is the quickest way to see the dashboard, the API, MCP, and the approval flow before you deploy.

You need Node 24 or later, pnpm, and a Cloudflare account on which you can create Workers with Durable Objects, D1, and Queues.

  1. Install and build. In a checkout of the repository: pnpm install, then pnpm --filter @customer-lite/app-dashboard build. The Worker serves the dashboard’s build, and wrangler refuses to deploy without it.
  2. Create the resources. From apps/workers: npx wrangler d1 create <database-name> and npx wrangler queues create deliveries.
  3. Write your deployment configuration. Copy apps/workers/wrangler.jsonc to a new file in apps/workers/ (its paths are relative to that folder), keep that file out of your commits (for example by listing it in .git/info/exclude), and in it set:
    • your Worker’s name, and the route or custom domain of <app-origin>;
    • the D1 database_name and database_id from step 2;
    • APP_ORIGIN to <app-origin> (it must be https: for real mail);
    • the SYSTEM_MAIL binding and SYSTEM_MAIL_FROM, which sign-in codes and approval links are mailed from (ADR 0029);
    • SEND_APPROVAL_DELIVERY to email, so approval links are mailed to approvers;
    • ADMIN_EMAILS: the addresses of the people who run the installation and approve sends;
    • and remove FAKE_EMAIL_DUPLICATE_WEBHOOKS, which is for development only.
  4. Set the secrets with npx wrangler secret put <NAME> --config <your-config>: at least BETTER_AUTH_SECRET, and FAKE_EMAIL_WEBHOOK_SECRET while you use the fake provider. Setting up sign-in lists every sign-in setting.
  5. Apply the database migrations: npx wrangler d1 migrations apply CONTROL_DB --remote --config <your-config>.
  6. Deploy: npx wrangler deploy --config <your-config>.
  7. Sign in. Open <app-origin> and sign in with an address from ADMIN_EMAILS. Setting up sign-in covers the first user, Google sign-in, and who else may sign in.

Then follow the Quickstart from step 1, with your <app-origin>.

The Worker starts with EMAIL_PROVIDER=fake, which sends nothing. To send through your own Amazon SES account:

  1. Setting up Amazon SES: credentials, configuration sets, delivery events back to the Worker, and your sending domains.
  2. Turning on real mail: the checks before the first real message.

Sending domains are added and verified through the operator endpoints, with OPERATOR_TOKEN: the SES guide shows the calls. Adding domains from the dashboard is planned.

Settings that differ from the managed service

Section titled “Settings that differ from the managed service”
Setting On a self-hosted installation
ADMIN_EMAILS Installation admins: admin of every workspace, and the approvers of every sending workflow.
ALLOWED_EMAILS Other addresses that may sign in. Nobody else can.
SEND_APPROVAL_DELIVERY email mails approval links. response returns them to the API key that activated the workflow instead. It suits a single developer on a private installation, but drops the guarantee that a person other than the caller approves, and it needs ADMIN_EMAILS unset (so sign-in goes by ALLOWED_EMAILS alone).
MAX_WORKSPACES_PER_USER, SEND_CONFIRMATION_TTL, SEND_CONFIRMATION_RATE_LIMIT, SEND_APPROVAL_DAILY_LINK_CAP The limits in Errors and limits.

Leave CUSTOMER_LITE_CLOUD unset: it turns on the managed service’s behaviour.

Pull the new version, rebuild the dashboard, apply the migrations (step 5), and deploy again (step 6). Migrations are applied before the Worker that needs them.