# Deployment

Deploy a test environment to your Cloudflare account, step by step.

OrbCart runs in **your** Cloudflare account. There is no OrbCart server in between.

## What runs where

| Piece                      | What it does                                                  |
| -------------------------- | ------------------------------------------------------------- |
| One Worker per environment | Serves the API and calls your systems.                        |
| Durable Objects            | Hold Carts, Payments and Orders. The source of truth.         |
| D1 (optional)              | The Order list for the Admin API and the Explorer.            |
| Cron trigger               | The daily EU VAT import, if you use `eu-standard`.            |
| Your storefront            | Anywhere you like. Only the commerce Worker needs Cloudflare. |

`test` and `live` are separate environments with separate keys and data.

## Deploy a test environment

Until `orbcart deploy` exists, a test environment is a few Wrangler commands. Run
them from your commerce Worker's directory. `examples/nordgrat` is the reference.

### Deploy the Worker

```sh
pnpm exec wrangler deploy --name shop-commerce-test
```

The first deploy creates the D1 database for the Order list. Apply its schema,
now and after every runtime update:

```sh
pnpm exec wrangler d1 migrations apply PROJECTION --remote
```

### Set the root secret

Generated and piped straight in, so it never appears on screen or in your history:

```sh
openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n' | pnpm exec wrangler secret put ROOT_SECRET --name shop-commerce-test
```

### Set your provider keys

Only for the providers your Channels use. [Which keys →](/payments)

```sh
pnpm exec wrangler secret put STRIPE_SECRET_KEY --name shop-commerce-test
pnpm exec wrangler secret put STRIPE_PUBLISHABLE_KEY --name shop-commerce-test
pnpm exec wrangler secret put STRIPE_WEBHOOK_SECRET --name shop-commerce-test
```

Until every required secret is set, the Worker answers each request with
`internal_error`. `pnpm exec wrangler tail --name shop-commerce-test` shows what's missing.

### Point the webhooks at it

| Provider | URL                                                                |
| -------- | ------------------------------------------------------------------ |
| Stripe   | `https://shop-commerce-test.<account>.workers.dev/webhooks/stripe` |
| Adyen    | `https://shop-commerce-test.<account>.workers.dev/webhooks/adyen`  |
| PayPal   | `https://shop-commerce-test.<account>.workers.dev/webhooks/paypal` |

### Issue keys for the storefront

```sh
pnpm exec orbcart keys issue --env test --channel de --url https://shop-commerce-test.<account>.workers.dev
```

This writes the URL, a publishable key and a secret key to
`.orbcart/keys/test-de.env`. Give the storefront what it needs from there.

### Prime EU VAT

Only for Channels with `tax: "eu-standard"`:

```sh
pnpm exec orbcart tax sync --env test
```

### Open the Explorer to your team

```sh
pnpm exec orbcart access setup --env test --host shop-commerce-test.<account>.workers.dev --allow @example.com
pnpm exec orbcart members add you@example.com --role owner --env test
```

The Explorer is at `https://<host>/explorer`. [CLI →](/sdks/cli)

## Connect the storefront

* Add the storefront's origin to the Channel's `origins` and set `returnUrl` to its return page. Then deploy the Worker again.
* Give the storefront `ORBCART_URL` and `ORBCART_PUBLISHABLE_KEY`. Only a server-side part gets `ORBCART_SECRET_KEY`.
* With Apple Pay, register the storefront's domain with your provider. [Express →](/payments/express#setup-checklist)

## Updating

```sh
pnpm exec wrangler deploy --name shop-commerce-test
pnpm exec wrangler d1 migrations apply PROJECTION --remote
```

Secrets stay on the Worker between deploys. Open Carts keep working: a Cart
remembers its Channel, so don't rename or remove a Channel that still has Carts.

## Checklist before real money

* [ ] Everything on the [security checklist](/security#before-you-go-live) is done: keys, secrets, `origins`, webhooks.
* [ ] `orbcart tax status` shows today in `availableOn`, if you use EU VAT.
* [ ] `deliverOrder` deduplicates by `order.id`.
* [ ] Every Channel names its `withdrawal_policy` and `privacy_policy` in [`legal`](/configuration#legal). Without them a `live` Worker serves nothing.
* [ ] Your confirmation email and an [order page](/commerce/order-page) are in place.

<Callout type="warn" title="Pre-release">
  `orbcart keys issue` only supports `test` today. A guided `live` setup arrives with `orbcart
    deploy`. Check the [status page](/status) before taking real orders.
</Callout>