Skip to content

Quick start

Quick start

Zero to a running provider console with a seeded catalog, on SQLite, with no external services — no Postgres, no Redis, no Stripe, no live Cbox ID. This is the local-development path; the production checklist covers the real deployment.

Prerequisites

  • PHP 8.4+ with the usual Laravel extensions (see Requirements).
  • Composer 2.
  • Node 18+ and npm (for the front-end assets).

1. Clone and set up

git clone https://github.com/cboxdk/cbox-billing.git
cd cbox-billing
composer setup

composer setup runs the whole first-time sequence: composer install, copy .env.example → .env (if absent), generate APP_KEY, run migrations, and build the front-end assets. See its exact steps in Installation.

For local development, set these three in .env (the template ships production-safe defaults):

APP_ENV=local
APP_DEBUG=true
DB_CONNECTION=sqlite

SQLite is zero-config — DB_DATABASE defaults to database/database.sqlite, which the setup scripts create for you. Do not run SQLite in production.

2. Seed the catalog and an organization

php artisan migrate:fresh --seed

This seeds a demo product with a four-plan ladder (Starter / Team / Business / Scale), each priced in DKK + EUR + USD, with per-meter entitlements, recurring included-credit grants, and a tiered price schedule per plan (graduated, volume, package, stairstep). It also seeds a first organization and the on-prem licensing profiles. See First run & seed data.

3. Run the app

composer run dev

This starts four processes concurrently — php artisan serve, the queue listener, php artisan pail (logs), and Vite. The provider console is at http://localhost:8000/.

4. Sign in (demo mode)

With no CBOX_ID_ISSUER configured, the login screen offers a demo sign-in button — a local operator session with no live identity provider. Click it to land on the dashboard. Once you point CBOX_ID_ISSUER at a real Cbox ID instance, demo sign-in disappears and the OIDC flow takes over (see OIDC login).

5. Try the enforcement API

The metered hot path lives under /api/v1 and is token-authenticated. Issue an operator token, then reserve and commit against a seeded meter:

php artisan billing:token "local dev" --org=<org-id>
# → prints the bearer token once

curl -s http://localhost:8000/api/v1/reserve \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"org":"<org-id>","meters":[{"meter":"api.requests","estimate":1}]}'
# → {"outcome":"allowed","reservation_id":"..."}

Full request/response shapes are in the enforcement API reference.

6. Verify

composer qa   # pint --test · phpstan · pest · license-check · composer audit

See Running the tests for the individual gates.

Next steps

← Previous Introduction Next → Requirements