Getting started with Sports Agents

Clone the source, set the environment, apply migrations, create the first admin, and run onboarding.

Access

The source is public at openshiporg/openfront-sports-agents. To try it without installing, use the live site.

Requirements

  • Node.js 20 or later (package.json sets "node": ">=20.0.0").
  • npm.
  • A PostgreSQL database you can migrate.
  • A Stripe account in test mode if you want to try invoice card payments.

Clone and install

git clone git@github.com:openshiporg/openfront-sports-agents.git
cd openfront-sports-agents
npm install

Environment

Create a .env file. The repository has no .env.example.

DATABASE_URL=postgresql://user:password@127.0.0.1:5432/openfront_sports_agents
SESSION_SECRET=replace-with-at-least-32-random-characters
PUBLIC_SIGNUPS_ALLOWED=false

Generate a secret with openssl rand -hex 32. In production the app refuses to sign invoice proofs without SESSION_SECRET.

Variables the code reads:

VariableUsed for
DATABASE_URLPostgreSQL connection
SESSION_SECRETSession cookies and the signed invoice proof
PUBLIC_SIGNUPS_ALLOWEDSet to true to open the dashboard sign-up page. Default is closed
NEXT_PUBLIC_STRIPE_KEYStripe publishable key for the invoice payment form
STRIPE_SECRET_KEYStripe adapter
STRIPE_WEBHOOK_SECRETStripe webhook signature check
OPENROUTER_API_KEY, OPENROUTER_MODEL, OPENROUTER_MAX_TOKENSShared key for the dashboard assistant
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_FROM, SMTP_STORE_LINKPassword reset email
S3_BUCKET_NAME, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_ENDPOINTThe NKS image storage setting. No list in this product uses it

Use Stripe test keys (pk_test_, sk_test_). Never commit .env.

Migrations

The repo has checked-in Prisma migrations in migrations/. Apply them with:

npm run migrate

npm run dev runs keystone build, then npm run migrate, then next dev. It changes whatever database DATABASE_URL points at, so point it at a development database.

npm run migrate:gen creates a development migration after a model change. Run it only against a disposable database.

Run locally

npm run dev

Next.js picks its default port and prints it. If that port is busy it picks the next free one. Read the port from the output.

  • Public site: /
  • Dashboard: /dashboard
  • GraphQL: /api/graphql

First admin

On an empty database, open /dashboard/init. The form asks for name, email, and password. That user gets an Admin role with every permission switched on.

Create other staff from the dashboard lists. Give each role only the permissions the job needs. See Roles and permissions.

Onboarding

After sign-in, the sidebar shows a setup card for users with canManageOnboarding. The card hides once the agency has any athlete, or once onboarding is completed or dismissed.

Open the dialog and pick a template:

  • Complete agency: the full seed.
  • Basic agency: one agent, one athlete, one agreement, one contract, and one deal.

The dialog runs ordered phases and shows each record as it saves. Every record is looked up before it is created, so running it again reuses what exists.

The full seed creates the agency "Meridian Sports Group", five roles, five staff users, four certifications, nine teams, 14 athletes, ten agreements, four contacts, nine brands, six playing contracts, 12 endorsement deals, 20 agent splits, two payment providers, and the money records. See Onboarding seed.

This is starter data. Replace the agency name, staff, and clients before real use.

Checks

npx tsc --noEmit
node --import tsx --test features/keystone/lib/*.test.ts
npm run test:security
npm run build

npm run build runs keystone build, applies migrations, then runs next build. Point DATABASE_URL at a development database when you run it.

On this page