ORBCOMMERCE DOCUMENTATION
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. 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:
pnpm install
pnpm devWhat 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:
- The family's Postgres from
compose.yamlon 55432 with every product's migrations (pnpm database). - Each local secret a file lacks, made once and never rewritten:
ROOT_SECRETin the root's.dev.vars,BETTER_AUTH_SECRETin the admin's and Nordgrat's storefront's,SIGNING_KEYincatalog/.dev.vars, and, while the shop has no owner yet, the owner's email and password incatalog/.env. An owner who signed up through the setup link puts their own there for the content to be seeded. - Nordgrat's ERP stand-in on 8798, its OrbCart on 8797, whose
orbcart devwrites its keys intoapps/nordgrat-cart/.dev.vars, and OrbPage. - OrbCart's secret key handed into
catalog/.dev.vars, its address and publishable key intoapps/clay-crema/.dev.varswith 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. - 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:
- 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,argson Linux). - 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.
- Only once shutdown is certain, manually remove that exact lock file and restart
pnpm dev. Leave the database volume and every.wrangler/statedirectory 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.
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.
Next steps
- Keep products in the admin: The catalog in the admin.
- Read them in a shop: Read the catalog.
- Write OrbPage content from a script: Write content from code.
- Put the family on Cloudflare: The test environment.