Skip to content

Quick Start

Jump to bottom
sarmakska edited this page Jun 1, 2026 · 3 revisions

Quick-Start

From clone to running locally in under fifteen minutes.

Prerequisites

1. Clone and install

git clone https://github.com/sarmakska/staff-portal.git
cd staff-portal
npm install

2. Create a Supabase project

In the Supabase dashboard:

  1. Create a new project. Note the project URL and the anon and service-role keys.
  2. Open the SQL Editor.
  3. Run every file in supabase/migrations/ in numbered order, oldest first, through to 025_sso_accruals_gdpr.sql.

3. Configure environment

Copy .env.local.example to .env.local and fill in real values:

NEXT_PUBLIC_SUPABASE_URL=https://YOUR_PROJECT.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...
RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=staff@yourdomain.com
NEXT_PUBLIC_APP_URL=http://localhost:3000
CRON_SECRET=any-random-string
NEXT_AUTH_DOMAIN=@yourcompany.com
NEXT_PUBLIC_ADMIN_EMAIL=you@yourcompany.com
GROQ_API_KEY=gsk_...           # optional, only for the assistant

NEXT_AUTH_DOMAIN restricts signups to your organisation's email domain. NEXT_PUBLIC_ADMIN_EMAIL is granted the admin role automatically on first login.

4. Configure Supabase Auth

Under Authentication, URL Configuration, set the Site URL to http://localhost:3000 and add http://localhost:3000/auth/callback to the redirect URLs.

5. Run the toolchain and the dev server

npm run lint && npm test     # confirm the toolchain is healthy
npm run dev                  # open http://localhost:3000

Sign up at /signup with an address on your configured domain, verify your email, and sign in. The address in NEXT_PUBLIC_ADMIN_EMAIL receives the admin role automatically; other roles are assigned from the Roles and Users admin page or directly in the user_roles table.

6. Optional: enable single sign-on

Configure the provider app or SAML connection in the Supabase dashboard under Authentication, Providers or Authentication, SSO. Then in the app under Admin, Single Sign-On, map your email domain to the provider. Staff on that domain are routed to the identity provider at login. See Single-Sign-On.

7. Production deploy (Vercel)

npx vercel

Add the same environment variables in the Vercel dashboard and set NEXT_PUBLIC_APP_URL to your production URL. Update the Supabase Site URL and redirect URLs to match. The cron jobs in vercel.json are picked up automatically; the leave-accrual job runs monthly and the year-end rollover runs on 1 January.

Common issues

  • Build fails locally with missing environment variables. The production build reads public Supabase variables at build time. Ensure .env.local exists or pass placeholder values as the CI workflow does.
  • Login redirect loop or invalid redirect URL. The Supabase Site URL and redirect URLs do not match NEXT_PUBLIC_APP_URL. Set both and avoid a trailing slash.
  • Signup is rejected. The address does not end with NEXT_AUTH_DOMAIN. Use an address on your configured domain.
  • PDF generation 500s on Vercel. The PDF routes run on the Node runtime, not Edge. Confirm the route declares the Node runtime.
  • the assistant returns nothing. Confirm GROQ_API_KEY is set and the model name in app/api/chat/route.ts is one Groq currently serves.

Next steps

Clone this wiki locally