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
0009_data_api_grants.sql — explicit Data API grants (required for new Supabase projects created after Oct 30, 2026)
0010_extend_audit_log_actions.sql — extends the audit log to cover actions added since 0001
0011_security_lint_fixes.sql — fixes Supabase security linter warnings
0012_is_email_registered.sql — RPC the register page uses to distinguish "already registered" from "not on class list"
0013_reading_display_name_and_citation.sql — adds reading display name/citation columns and fixes a duplicate-row bug on re-upload

Run every migration through 0013 — the app code depends on columns and RPCs added as late as that one. Skipping any of them will break pages, not just optional features.

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. Verify the storage bucket

The migrations already created the course-files bucket for you — migration 0004 creates it and 0007 adds the readings MIME type, so there's nothing to create by hand. In the Supabase dashboard, go to Storage and confirm course-files exists with:

Public: off (private)
File size limit: 10 MB (a hard cap set by the migration — don't raise it in the dashboard, a later migration run will reset it)
Allowed MIME types: application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.oasis.opendocument.text, application/pdf

If any of this looks wrong, double-check migrations 0004 and 0007 ran successfully rather than editing the bucket directly.

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.