Manual

Installation

Stand up your own copy of Gesso Lite. About 30 minutes if you've used Supabase and Vercel before; longer if it's all new.

Prerequisites

A GitHub account
A Supabase account (free tier is fine)
A Vercel account (free Hobby tier is fine)
Node.js 20 or later, locally, if you want to run a dev server
A domain you control, if you want a real URL (otherwise you'll be on a *.vercel.app URL)

1. Fork the repo

Go to github.com/stockphrase/gesso-lite and click Fork. You'll get your own copy at github.com/your-username/gesso-lite.

2. Create a Supabase project

Go to supabase.com and sign in.
New Project. Pick any name (e.g. "gesso-lite-prod"). Set a strong database password and save it.
Pick the region closest to your users.
Wait ~2 minutes for the project to be ready.

3. Run the database migrations

In your forked repo there's a supabase/migrations/ directory with numbered SQL files. Open the Supabase dashboard for your new project, go to SQL Editor, and run each migration file in order:

0001_initial_schema.sql — tables, RLS policies, helpers, triggers
0002_is_instructor_email.sql — RPC for the registration page
0003_handle_new_user_with_name.sql — captures display name
0004_storage_submissions.sql — submission file policies
0005_student_code.sql — generates per-student short codes
0006_storage_returns.sql — return file policies
0007_storage_readings.sql — readings file policies
0008_course_templates.sql — templates table

After running them all, paste this into the SQL editor to verify everything's in place:

SELECT table_name FROM information_schema.tables
WHERE table_schema = 'public' ORDER BY table_name;

You should see: allowed_emails, app_config, assignments, audit_log, course_memberships, course_templates, courses, profiles, reading_files, submissions.

4. Set the instructor email

Gesso Lite is single-instructor. Tell the database who that is:

INSERT INTO public.app_config (id, instructor_email)
VALUES (1, 'your-email@example.com')
ON CONFLICT (id) DO UPDATE SET instructor_email = EXCLUDED.instructor_email;

When you register the first user with this email address, they're automatically promoted to instructor. Other users register as students by default.

5. Configure storage

In the Supabase dashboard: Storage → New bucket
Name: course-files
Public: off (private)
File size limit: 50 MB
Allowed MIME types: application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.oasis.opendocument.text, application/pdf

6. Disable email confirmation

Authentication → Providers → Email → uncheck "Confirm email". Save. (For a class of trusted students added by whitelist, this removes a major source of friction.)

7. Get your API keys

Settings → API. You'll need:

Project URL (e.g. https://xxxxx.supabase.co)
Anon key (public)
Service role key (secret — never commit it)

8. Deploy to Vercel

Go to vercel.com/new.
Import your forked repo.
Framework: Next.js (auto-detected). Root directory: ./. Default build settings.

Expand Environment Variables and add three:

NEXT_PUBLIC_SUPABASE_URL = https://xxxxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY = (paste anon key)
SUPABASE_SERVICE_ROLE_KEY = (paste service role key)

Deploy.

9. Tell Supabase about your URL

After Vercel finishes, copy the URL it gives you (e.g. gesso-lite-yourname.vercel.app) and add it to Supabase:

Authentication → URL Configuration
Site URL: https://your-vercel-url
Redirect URLs: https://your-vercel-url/**

This lets the password-reset flow work in production.

10. Register as the instructor

Visit your Vercel URL → /register. Use the email address you set in step 4. Pick a password.

After registration, you should land on a courses list page. If you see "(instructor)" in the role badge, the auto-promotion worked.

Custom domain (optional): in Vercel → Settings → Domains, add your domain. Vercel gives you a CNAME record to set at your DNS provider. After DNS propagates (5–30 minutes), update Supabase's Site URL and Redirect URLs to use the custom domain.

Troubleshooting

Build fails on Vercel

Check the build log. Most common: TypeScript errors that didn't show locally. Fix and push again — Vercel auto-redeploys.

"Invalid login credentials" but the user exists

Env vars on Vercel don't match Supabase. Re-paste both keys carefully, watching for leading/trailing whitespace.

Password-reset email arrives but the link 404s

Site URL or Redirect URLs in Supabase don't include your production URL. Update them.

Course deletion fails on production

The SUPABASE_SERVICE_ROLE_KEY environment variable is missing or wrong. Check Vercel → Settings → Environment Variables.