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.jsonsets"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 installEnvironment
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=falseGenerate a secret with openssl rand -hex 32. In production the app refuses to sign invoice proofs without SESSION_SECRET.
Variables the code reads:
| Variable | Used for |
|---|---|
DATABASE_URL | PostgreSQL connection |
SESSION_SECRET | Session cookies and the signed invoice proof |
PUBLIC_SIGNUPS_ALLOWED | Set to true to open the dashboard sign-up page. Default is closed |
NEXT_PUBLIC_STRIPE_KEY | Stripe publishable key for the invoice payment form |
STRIPE_SECRET_KEY | Stripe adapter |
STRIPE_WEBHOOK_SECRET | Stripe webhook signature check |
OPENROUTER_API_KEY, OPENROUTER_MODEL, OPENROUTER_MAX_TOKENS | Shared key for the dashboard assistant |
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_FROM, SMTP_STORE_LINK | Password reset email |
S3_BUCKET_NAME, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_ENDPOINT | The 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 migratenpm 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 devNext.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 buildnpm run build runs keystone build, applies migrations, then runs next build. Point DATABASE_URL at a development database when you run it.