Getting started

Prerequisites

Node.js 20 or newer
PostgreSQL
Git and npm
an empty, isolated database

Clone and install

git clone https://github.com/openshiporg/openship.git
cd openship
npm install

Configure the local environment

Copy the repository's .env.example when present and set at least:

DATABASE_URL="postgresql://username:password@localhost:5432/openship"
SESSION_SECRET="replace-with-a-random-string-at-least-32-characters"

Add only the SMTP, AI, shop or channel secrets required by the handler you intend to test. Keep credentials out of source control.

Review migrations and start

npm run dev

The current script generates the Keystone schema, runs prisma migrate deploy, and starts Next.js. Confirm the database target and migration history before running it.

Create the first dashboard user

Open /dashboard/init, create the first operator, and sign in at /dashboard. Current source has no Openship onboarding mutation or seed, so platform, shop, channel, link, and match records are configured manually. Do not copy credentials from a public example.

Build one synthetic route

Create one test shop, one test channel, a link, and one exact variant match. Current compiled handlers cover Shopify and Openfront; the docs site's POST-only demo endpoints can exercise custom-handler shapes with in-memory synthetic data. Route a synthetic order and inspect both Openship and the downstream test system.

Evaluation checks

API keys and sessions cannot read another user's shops, channels, matches or orders.
Shop and Channel credential fields are denied or encrypted before real secrets are stored.
Database-selected HTTP/function destinations are constrained to reviewed allowlists and cannot reach private or metadata networks through DNS or redirects.
retries do not create duplicate downstream purchases.
webhook signatures and event IDs are checked before state changes.
a partial channel failure remains visible and can be retried or reconciled.

npm run build currently deploys migrations before building, the checked-in lint script uses the removed Next.js 16 next lint command, and the package has no test or typecheck script. Do not represent a release as fully verified or connect a production shop/supplier until the owning source adds current gates and the exact handler passes product, order, ownership, egress, credential, cancellation, fulfillment, tracking, replay, retry, and reconciliation tests.