# Cloudflare

Cloudflare runs your console (a Worker) and publishes your apps' web previews. You use **your own** Cloudflare account.

**Time:** about 10 minutes. **Needs:** a Cloudflare account. A domain is **optional** for both presets:

- **No domain:** each app goes live free at `<app-name>.<your-subdomain>.workers.dev`, where `<your-subdomain>` is your account's workers.dev subdomain. App email is off; support mail goes to your own address.
- **With a domain** whose DNS is in Cloudflare (for example `acme.com`): each app goes live at `<app-name>.acme.com`, and app email can run on `apps.acme.com` (see [Resend](resend.md)).

You can start without a domain and add one later in **Settings → Identity**. Apps launched after that use the domain; an earlier workers.dev site stays up until you delete its Worker.

## Steps

### A. For the installer (everyone)

1. Sign up at <https://dash.cloudflare.com>.
2. In a terminal run `npx wrangler login`. It opens your browser. Approve.
3. If you have several Cloudflare accounts, run `export CLOUDFLARE_ACCOUNT_ID=<your account id>` first.

**You should now see** your account when you run `npx wrangler whoami`.

### B. For runs, no domain

1. Open **Workers & Pages** in the dashboard once. If Cloudflare asks you to pick a workers.dev subdomain, pick one. Note it: in `starwisp-console.acme-labs.workers.dev` it is `acme-labs`.
2. Open <https://dash.cloudflare.com/profile/api-tokens> → **Create Token** → **Create Custom Token**.
3. Permissions: **Account · Workers Scripts · Edit**. That is all.
4. Account Resources: **Include →** your account.
5. Create the token and copy it. It is shown once.
6. Copy your **Account ID** from **Workers & Pages → Overview** (right-hand panel).

An account-owned token (Manage Account → Account API Tokens) works too; save the Account ID with it so the Test can check it.

### C. For runs, with a domain

Do B, but in step 3 also add **Zone · DNS · Edit**, **Zone · Workers Routes · Edit**, **Zone · Zone Settings · Read**, **Zone · Zone · Read** and **Zone · SSL and Certificates · Edit**, with Zone Resources **Include → Specific zone →** your domain. Then open your domain's zone **Overview** and copy the **Zone ID** from the right-hand panel.

**Least privilege:** scope the token to one account (and, with a domain, one zone). Never use the Global API Key. Add an expiry date if you want to; remember to renew it.

## Where it goes

Console → **Settings → Vault** → card **Cloudflare API token**:

| Field | Value |
|---|---|
| **API token** | the token (secret `CLOUDFLARE_API_TOKEN`) |
| **Account ID** | 32 hex characters (`CLOUDFLARE_ACCOUNT_ID`) |
| **Zone ID (only with a house domain)** | 32 hex characters (`CLOUDFLARE_ZONE_ID`); leave it empty with no domain |

Click **Test now**. Then in **Settings → Identity**:

- No domain: leave **House domain** empty and set **Free web address** to your workers.dev subdomain (`acme-labs`). When the console itself runs on workers.dev, the form fills it in for you, along with **Console address** (so only your console can show the live app in its phone preview); press Save.
- With a domain: set **House domain** (for example `acme.com`).

The Setup row **Where apps go live** has a Test: with a domain it checks Cloudflare lists the domain; without one it checks your account's workers.dev subdomain is the one you saved.

**You should now see** a passing test on the card and on that row.

## What it gates

The **launch** stage, which both presets run: publishing each app's site (landing page, `/privacy`, `/terms`, `/support` and the web app at `/app`). With a domain it also creates the `<app-name>.acme.com` DNS record. The installer itself uses your `wrangler` login, not this token.

Without a domain, Launch names each app's Worker after the app (`<app-name>`). It never replaces a Worker it did not make: if your account already has a Worker with that name, Launch stops and says so.

## What it costs

The free Workers plan covers a small console and previews (about 100,000 requests a day). Workers Paid is $5 a month if you outgrow it. A domain is optional; one costs about $10 to $15 a year (an estimate; prices vary by registrar).

## Slow prerequisites

None without a domain. A new domain's DNS can take minutes to hours to start working. Moving an existing domain's nameservers to Cloudflare can take up to a day.

## Common problems

See [install](../install.md) for deploy errors such as "Cloudflare needs to know which account to use".