Getting started with Convenience

Requirements

• Node.js 20 or later (package.json engines is >=20.0.0). The README suggests Node.js 22 for Next.js 16.
• npm. The repo ships a package-lock.json.
• A PostgreSQL database you are allowed to migrate.
• S3-compatible object storage for product photos in production.

Hosted app

The hosted app is at convenience.openship.org.

Install

git clone https://github.com/openshiporg/openfront-convenience.git
cd openfront-convenience
npm install

Environment

Create .env in the repo root. The repo has no .env.example.

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

DATABASE_URL=postgresql://user:password@127.0.0.1:5432/openfront_convenience
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:

Any env://NAME credential reference you set on a payment provider also needs NAME in the environment, with a value of at least 32 characters. Keep .env out of source control.

Migrations and local run

npm run dev

npm run dev runs keystone build --no-ui, applies the checked-in migrations with prisma migrate deploy, and starts Next.js. The repo has 30 migration directories. 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.

npm run dev applies migrations to whatever DATABASE_URL points at.

Once running:

• Public site: /
• Operator dashboard: /dashboard
• Operator pages: /dashboard/platform
• GraphQL API: /api/graphql
• Health check: /api/health/live

First user and onboarding

1. While the database has no users, every route redirects to /dashboard/init. Create the first user there. That user becomes an approved platform admin.
2. Sign in. The dashboard opens the onboarding dialog. Pick Starter store to prefill the form, or Blank.
3. Fill in the business, store, address, timezone, currency, and standard tax percent. Tick This store sells fuel if needed, and Add starter products for the 18 starter items. Choose Draft or Published for the storefront.
4. Submit. onboardConvenienceBusiness creates the business, store, Owner role and employee, two stock locations, a price book, tax categories and rate, a register, a loyalty program, an external-terminal payment provider, and optional fuel and sample catalog. See Onboarding for the full list.
5. Open /dashboard/platform/store-settings to set the public name, logo, hours, and location, and to add registers and stock locations.
6. Add staff at /dashboard/platform/staff. Give each person a role with only the permissions they need. Each cashier sets a POS PIN.

"Skip for now" in the sidebar dismisses the dialog without creating anything.

Scripts