# Run it locally

The catalog, OrbCart, OrbPage and the admin on your machine, seeded with the Clay & Crema demo shop, with one command.

Want to look first? Nordgrat's shop runs at [demo.orbcart.dev](https://demo.orbcart.dev/en). It
reads its products from the catalog, its pages from OrbPage and its search from OrbSearch, and
checks out with OrbCart.

To run the same family on your machine, clone the repository and start it:

```sh
pnpm install
pnpm dev
```

**What it needs:** Docker running, Node 24 and pnpm; nothing to write by hand. It ends with where
everything answers:

| What                                  | Address                  |
| ------------------------------------- | ------------------------ |
| Clay & Crema, the demo shop           | http://localhost:5173/en |
| The admin, with every product's panel | http://localhost:8789    |
| OrbCatalog                            | http://localhost:8787    |
| OrbCart                               | http://localhost:8797    |
| OrbPage                               | http://localhost:8807    |

and with the owner who signs in to the admin, as `catalog/.env` names them: on a new shop
`owner@claycrema.test`, whose password is `ORBCATALOG_OWNER_PASSWORD` there. It never prints the
password.

## What it does

In the order the keys need, every line of every process in this one terminal behind its
product's name:

1. The family's Postgres from `compose.yaml` on 55432 with every product's migrations (`pnpm database`).
2. Each local secret a file lacks, made once and never rewritten: `ROOT_SECRET` in the root's
   `.dev.vars`, `BETTER_AUTH_SECRET` in the admin's and Nordgrat's storefront's, `SIGNING_KEY` in
   `catalog/.dev.vars`, and, while the shop has no owner yet, the owner's email and password in
   `catalog/.env`. An owner who signed up through the setup link puts their own there for the
   content to be seeded.
3. Nordgrat's ERP stand-in on 8798, its OrbCart on 8797, whose `orbcart dev` writes its
   keys into `apps/nordgrat-cart/.dev.vars`, and OrbPage.
4. OrbCart's secret key handed into `catalog/.dev.vars`, its address and publishable key into
   `apps/clay-crema/.dev.vars` with the shopper sign-in's secret, which encrypts its signing keys
   in the shared Postgres; then the catalog, the admin and Clay & Crema on 5173.
5. Once each answers, Clay & Crema's seed. The catalog's (`pnpm --filter @orbcatalog/worker seed`)
   signs the owner up and writes the settings, Schema, stores, photographs, categories and 17
   products with their offers. The content's (`pnpm --filter @orbcommerce/clay-crema content`)
   declares the shop's sections and writes its pages, home page and menus in English and German.
   Both write only what is missing, so a seed that stopped halfway resumes on the next run.

Every secrets file is ignored by git.

**A second run** starts the processes and changes nothing else: every secret is there, OrbCart
keeps the keys it still knows, and the catalog and OrbPage hold Clay & Crema. Nordgrat's season
and content run only by hand: `pnpm --filter @orbcatalog/worker season` and
`pnpm --filter @orbcart/demo seed --content`. Ctrl-C stops
every process; `docker compose -p orbcommerce down -v` empties the database, and the next
`pnpm dev` seeds again.

## Switching worktrees

One checkout runs the family at a time. Stop it before starting `pnpm dev` in another linked
worktree. Postgres stays in the same Docker volume; each service's local Worker state stays in
the primary Git checkout, at its existing path:

| Service      | State directory in the primary checkout              |
| ------------ | ---------------------------------------------------- |
| Catalog      | `catalog/.wrangler/state`                            |
| OrbCart      | `apps/nordgrat-cart-worker/.wrangler/state`          |
| OrbPage      | `page/runtime/.wrangler/state`                       |
| Admin        | `apps/admin/.wrangler/state`                         |
| Shop         | `apps/nordgrat-cart/.wrangler/state`                 |
| ERP stand-in | `apps/nordgrat-cart-worker/stand-in/.wrangler/state` |

The primary checkout is the original checkout Git lists first, not whichever checkout holds
the `main` branch. Keep it available. Linked worktrees use its state in place: nothing is moved,
copied or reset. Builds and deployments do not use this local path discovery. Separate clones
are not a supported handoff: they do not share a primary checkout. Bare repositories and
separate-Git-directory layouts whose primary working tree Git cannot identify are rejected,
not assigned a fresh store.

`pnpm dev` exclusively creates `.wrangler/orbcommerce-dev.lock` in that primary checkout before
changing secrets, preparing Postgres or starting a service. A second launcher in the same Git
family exits without doing those things, even if every port is free. Normal shutdown retains
ownership until its database/seed commands and service process groups have stopped, then removes
the lock. Wait for the launcher to exit before restarting. A child that will not stop keeps the
lock held; there is no timeout that assumes it is safe to overlap.

This guarantee covers cooperating `pnpm dev` launchers in one primary checkout and its linked
worktrees on this machine, using local files and ordinary POSIX process groups. Standalone
product commands, older launchers without the lock, separate clones and programs that escape
the launcher's process groups are outside it. Port checks remain an additional diagnostic, not
the ownership mechanism. Postgres itself stays up between launches as before.

An abruptly killed launcher leaves its lock in place, even if its PID no longer exists. Never
remove it merely because the ports are free or the PID is gone. For recovery:

1. Read the lock's launcher PID, worktree and process-group IDs. Inspect the launcher's process
   tree and every member of those groups, including descendants whose parent has already exited
   (`ps -eo pid,ppid,pgid,args` on Linux).
2. Stop the remaining family commands and wait until those groups contain no process. Recheck
   the fixed ports. A crash can interrupt the recording of a newly spawned group, so the record
   alone is not a complete process inventory. Identify and stop all commands from that launch;
   if shutdown cannot be established, leave the lock in place rather than guessing it is stale.
3. Only once shutdown is certain, manually remove that exact lock file and restart `pnpm dev`.
   Leave the database volume and every `.wrangler/state` directory untouched.

The catalog's image bytes and uploaded import files live in its local Worker state. Completed
import jobs, their history and the seed's completion live in Postgres. Switching worktrees
does not require importing again or replaying the seed. Do not empty the database to fix missing
pictures. If a previous worktree holds the only copy of valuable local bytes, stop before this
handoff and identify the authoritative store; worktree-local stores are left untouched and
never merged automatically.

Secrets, sign-in configuration and the readiness marker remain checkout-local. Prepare the
new checkout's credentials separately; sharing Worker state does not synchronize them. Catalog,
admin and shop Vite development servers also use the primary paths when started alone. Standalone
Wrangler commands need `--persist-to` with the corresponding absolute directory above; `pnpm dev`
passes it for OrbCart, OrbPage and the ERP stand-in.

## The payment keys are yours

Stripe's and PayPal's sandbox keys cannot be made: `STRIPE_SECRET_KEY`, `STRIPE_PUBLISHABLE_KEY`
and `STRIPE_WEBHOOK_SECRET` (from
`stripe listen --latest --all-snapshot --forward-to localhost:8797/webhooks/stripe`, which runs
beside it), `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET` and `PAYPAL_WEBHOOK_ID` go into the root's
`.dev.vars`. Until they are there, the command names those missing at its end, and OrbCart still
takes carts but leaves out the methods of a provider without its keys, so checkout cannot pay; its
log names the providers it left out. With them, `4242 4242 4242 4242` pays and the order shows in
the admin's Orders. More cards are in [Test payments](/docs/shop/test-payments).

## It says what it cannot do

Docker not running, or a port taken (another checkout's `pnpm dev`, say), stops it before it starts
anything, naming the cause. The family's own Postgres, started from any checkout, is shared and
fine. One checkout runs the family at a time. Each product's README says how to run that product
alone; OrbCart's is the [OrbCart quickstart](/docs/get-started/orbcart).

## Next steps

- Keep products in the admin: [The catalog in the admin](/docs/admin/catalog).
- Read them in a shop: [Read the catalog](/docs/shop/catalog).
- Write OrbPage content from a script: [Write content from code](/docs/page/write-content).
- Put the family on Cloudflare: [The test environment](/docs/run/test-environment).