Getting started with Vape

Requirements

• Node.js matching package.json engines (>=20.9.0); the README recommends Node.js 22 for Next.js 16.
• npm (the repository ships a package-lock.json).
• A PostgreSQL database you are allowed to migrate.
• S3-compatible object storage for product and claim images in production.

Live demo

A hosted demo runs at vape.openship.org. It is a demonstration instance with demo data; it does not represent a licensed retailer, and regulated checkout is gated there as it is in source.

Install

git clone https://github.com/openshiporg/openfront-vape.git
cd openfront-vape
npm ci
cp .env.example .env

Environment

features/keystone/index.ts refuses to start without DATABASE_URL and SESSION_SECRET, and rejects a session secret shorter than 32 characters. The S3 values fall back to development placeholders outside production and are required when NODE_ENV=production.

DATABASE_URL=postgresql://user:password@127.0.0.1:5432/openfront_vape
SESSION_SECRET=replace-with-at-least-32-random-characters   # openssl rand -hex 32

S3_BUCKET_NAME=your-bucket
S3_REGION=your-region
S3_ACCESS_KEY_ID=your-access-key-id
S3_SECRET_ACCESS_KEY=your-secret-access-key
S3_ENDPOINT=https://your-s3-compatible-endpoint

Optional settings read by the code:

Keep .env out of source control.

Migrations and local run

npm run dev

npm run dev runs keystone build --no-ui, applies checked-in migrations with prisma migrate deploy, and starts Next.js. To change the schema, run npm run migrate:gen against a disposable database; it rebuilds the schema, regenerates the dashboard view order, and runs keystone prisma migrate dev. Commit model changes and their migrations together.

Once running:

• Storefront: /[countryCode] (for example /us)
• Operator dashboard: /dashboard
• GraphQL API: /api/graphql

First operator and onboarding

1. Visit /dashboard/init on an empty database to create the first administrator, then sign in.
2. Open the onboarding dialog from the dashboard. Setup seeds a store, a us region (tax rate 0), currency, country, three shipping options, four categories, three collections, ten draft products, a Manual payment provider, a manual fulfillment provider, and, if your role has canManageCompliance, a draft RegulatedMerchantProfile with the kill switch on.
3. Fill in store business details and the five required policies (shipping, returns, age verification, privacy, terms) at /dashboard/platform/store.
4. Work through the blockers listed on /dashboard/platform/overview and /dashboard/platform/compliance: activate a merchant profile, add launch jurisdictions and an active signed rule set, classify and authorize variants, and record provider approvals.

Onboarding does not enable regulated transactions, and the seeded Manual provider is refused by storefront checkout. See Architecture and workflows for the full go-live sequence.

Deployment

Scripts in package.json:

A typical release builds, applies migrations as a separate step against a backed-up database, then starts:

npm run build
npm run migrate
npm start

The included railway.toml builds with keystone build --no-ui && next build and starts with npm run migrate && next start, because the build environment cannot reach an internal database. The README also includes a Vercel import button. Either way, provision PostgreSQL, S3-compatible storage, SMTP, and any payment or shipping credentials yourself, and share the same database, SESSION_SECRET, and storage across all application processes. There is no persistent background worker in the source; webhook redelivery is triggered through the retryWebhookDeliveries mutation.