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.
What runs where
Section titled “What runs where”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.
Try it locally first
Section titled “Try it locally first”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.
Deploy
Section titled “Deploy”You need Node 24 or later, pnpm, and a Cloudflare account on which you can create Workers with Durable Objects, D1, and Queues.
- Install and build. In a checkout of the repository:
pnpm install, thenpnpm --filter @customer-lite/app-dashboard build. The Worker serves the dashboard’s build, andwranglerrefuses to deploy without it. - Create the resources. From
apps/workers:npx wrangler d1 create <database-name>andnpx wrangler queues create deliveries. - Write your deployment configuration. Copy
apps/workers/wrangler.jsoncto a new file inapps/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_nameanddatabase_idfrom step 2; APP_ORIGINto<app-origin>(it must behttps:for real mail);- the
SYSTEM_MAILbinding andSYSTEM_MAIL_FROM, which sign-in codes and approval links are mailed from (ADR 0029); SEND_APPROVAL_DELIVERYtoemail, 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.
- your Worker’s
- Set the secrets with
npx wrangler secret put <NAME> --config <your-config>: at leastBETTER_AUTH_SECRET, andFAKE_EMAIL_WEBHOOK_SECRETwhile you use the fake provider. Setting up sign-in lists every sign-in setting. - Apply the database migrations:
npx wrangler d1 migrations apply CONTROL_DB --remote --config <your-config>. - Deploy:
npx wrangler deploy --config <your-config>. - Sign in. Open
<app-origin>and sign in with an address fromADMIN_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>.
Send real email
Section titled “Send real email”The Worker starts with EMAIL_PROVIDER=fake, which sends nothing. To send through your own Amazon SES account:
- Setting up Amazon SES: credentials, configuration sets, delivery events back to the Worker, and your sending domains.
- 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.
Updating
Section titled “Updating”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.