# The test environment

Every product, the admin and Nordgrat's shop on Cloudflare, seeded, with one command.

```sh
pnpm ship test            # every product, the admin and Nordgrat's shop, seeded, then a read of each
pnpm ship test --plan     # what a run would deploy, make and skip; changes nothing
pnpm ship test --reset    # empties every product's data first, once you type the environment's name
```

**What it needs:** Wrangler signed in to the Cloudflare account (`pnpm exec wrangler login`), and
`.env.test` at the root, copied from `.env.test.example`, which names every key: the Postgres
connection strings, the owner the seed signs up, OrbSearch's key and the payment providers' sandbox
keys. The file is ignored and never printed.

## What it does

In the order the bindings and keys need: the catalog's database (migrations, Hyperdrive, the media
bucket); OrbCart (the ERP's stand-in, its lists' migrations, its Worker, and a publishable and a
secret key per Channel); the catalog's Worker, holding OrbCart's secret key and OrbSearch's, and
its seed Worker, which starts Nordgrat's catalog season on Cloudflare beside the database; OrbPage
(its bucket and Worker), the admin, which binds all three, and the shop, holding OrbCart's keys,
while the season plays; then the rest of Nordgrat's one seed (`pnpm --filter @orbcart/demo seed`),
which follows the season until it has played, asks OrbSearch to fetch the catalog's feed at once
and writes OrbPage's site and the shop's content, and a read of every product and the shop.

This machine builds, uploads what changed and follows; the season's thousands of writes never leave
Cloudflare. Once the season has played, a run writes only the site and content OrbPage still misses
(`seed --content`), so a run that stopped after the season fills OrbPage on the next. A reset took
13 minutes on 2 November, the season 10 of them. A seed that stopped halfway resumes on the next
run. Secrets it can make (signing keys, sign-in and root secrets) it makes once; keys between
products live only as Worker secrets and in OrbCart's ignored key files.

## A second run changes nothing that did not change

A Worker is deployed with a tag, the first 16 hex digits of a SHA-256 over its built bundle, its
config and the values of the secrets handed to it, such as OrbCart's keys; a run builds it again,
compares that digest with the tag of the version serving all traffic and deploys only when they
differ or a secret it requires is missing. So a handed-in secret whose value changed is written
again, while a secret the ship made (a signing key, a sign-in or root secret) is made once and
never rewritten.

`--reset` empties the catalog's database, OrbPage's site and OrbCart: its Worker gets a fresh root
secret, then with that secret wipes every Durable Object Cloudflare lists for it and empties its
lists, its key files go, and the catalog and the shop are deployed with the fresh keys it issues.

## By hand, once per environment

The command names at its end what it cannot do: the Postgres database and its roles, Nordgrat's
shop on the OrbSearch box with its key and the admin as its staff issuer, and the Stripe and PayPal
webhooks, whose secrets go into `.env.test`. Each product's own ship (`pnpm ship test` in
`catalog/`, `pnpm --filter @orbpage/runtime ship test`,
`pnpm --filter @orbcart/example-nordgrat ship test --url …`) brings that product up alone.
OrbCart's own deployment, step by step, is in [Deployment](/docs/run/deployment).