Supabase setup

IsotopeAI stores everything in a Supabase project you own. There are two ways to set one up: run one command, or do it by hand in the dashboard. The command is not a shortcut for the impatient — it does four things the manual route leaves out, and two of them are invisible until the app breaks.

The one-command setup #

From an isotope-apk checkout, with a personal access token and nothing else:

# provision a project you already created and left empty
./supabase.sh setup --pat sbp_xxx --ref abcdefghijklmnop

# or create the project too, wait for its database, then provision it
./supabase.sh setup --pat sbp_xxx --create "my-isotope"

It runs five phases in dependency order and asserts each one landed:

It writes no database rows — no users, no seed data, no files. The project it leaves behind is empty and ready for its owner's first signup.

Writing .env

On success, setup writes .env pointing at the new project. It never overwrites an existing one — that file holds the service-role key and every API key on the machine, so it is moved to .env.old first. Run it twice and the original is rotated to a timestamped name rather than buried.

These four are owned by the script, because they identify the project it just set up:

SUPABASE_URL
SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY
SUPABASE_ACCESS_TOKEN

Everything else is carried across from the old file: PORT, the AI keys, the admin settings, and SESSION_SECRET — regenerating that last one would silently log out every existing browser session for no reason. Any key the script does not recognise is preserved under a comment rather than dropped. The file is written 0600.

Pass --no-env to skip it, for a checkout whose secrets are managed elsewhere or a project you are provisioning for a different machine. The web console offers the same choice as a checkbox.

Checking a project without changing it

check is read-only and answers the question the counts alone cannot:

./supabase.sh check --pat sbp_xxx --ref abcdefghijklmnop

Thirteen checks in four groups. Every one of them exists because that exact thing silently failed at some point:

Each failure prints the command or migration that fixes it. Add --json for a machine-readable report; that is what the web console consumes.

The web console

./supabase.sh ui        # http://127.0.0.1:8000

A four-step flow — connect, choose a project, read the readiness report, then run. Step four does not appear until step three has run, so you cannot act on a project before the console has told you what state it is in. It binds to loopback only, because the page accepts a management-API token and can provision or overwrite a project.

Jobs run detached with their state on disk, so closing the tab or restarting the server does not stop or lose one. ./supabase.sh status reports the same job from a terminal with no server running.

Doing it by hand #

Everything below is the manual equivalent. It is worth reading even if you use the command, because it explains what the command is doing — and if you follow it instead, remember the signup trigger and the buckets, which are the two things the SQL file alone does not fully cover.

Two facts worth having up front, because they change what you need to do.

What it creates, counted from the file rather than estimated:

Row-level security is enabled on all 42 tables — not most of them. If you find a table without it after running the file, something did not apply.

Create the project #

1. Create a free project

   At supabase.com/dashboard. Pick the region closest to you — every request from your device makes a round trip, so region is the single largest factor in how fast the app feels.

   Save the database password Supabase shows you. It is displayed once, it is not the same as any API key, and backup.sh needs it for DATABASE_URL.

2. Wait for provisioning to finish

   Roughly two minutes. Running SQL against a project that is still starting fails in ways that look like schema errors rather than timing errors, which sends you debugging the wrong thing.

3. Run the schema

   SQL Editor → New query. Upload isotope-complete.sql rather than pasting it, then run.

   Expect Success. No rows returned. That is the correct output — the file creates objects and selects nothing.

4. Confirm it actually applied

   Do not take the success message on trust. Run this and check the numbers:

   select
     (select count(*) from pg_tables where schemaname = 'public')                as tables,
     (select count(*) from pg_proc p join pg_namespace n on n.oid = p.pronamespace
        where n.nspname = 'public')                                             as functions,
     (select count(*) from pg_policies where schemaname = 'public')             as policies,
     (select count(*) from pg_tables
        where schemaname = 'public' and rowsecurity = false)                    as tables_without_rls;

   tables_without_rls must be 0. Anything else means a table is world-readable to any holder of the anon key — which is a public value.

Extensions

The file enables five, all of which Supabase already ships — nothing needs installing:

Storage buckets #

Four buckets, and the exact values matter — the server checks them on startup and corrects the public flag if it is wrong. Taken from ensureStorageBuckets() in server.mjs:

Paths in the last two are owner-scoped: {auth.uid()}/…. The first segment being the owner's uid is what makes the RLS policy expressible as (storage.foldername(name))[1] = auth.uid()::text.

A fifth bucket, notes, was removed. It had a 10 MB limit, an owner-scoped policy, zero objects and zero references — no upload path in the bridge, none in any reachable bundle. Its only mention anywhere was a health check asserting it existed, which is worse than no check: it could only ever fail for a reason nobody should act on, and it passed happily while the two buckets above were absent. If your project still has it, supabase/024_drop_unused_notes_bucket.sql removes it — and refuses if it turns out to contain anything.

You can skip creating them manually. ./supabase.sh setup creates all four as one of its phases. Failing that, with ENABLE_ADMIN_MODE=true and a service-role key present, the server creates them on startup and logs each one:

[Storage] Created bucket "user-content" (public=false)
[Storage] Created bucket "avatars" (public=true)
[Storage] Created bucket "group-icons" (public=true)
[Storage] Created bucket "study-material" (public=false)

It only creates buckets that return 404, so it is safe on every restart. Without admin mode it does nothing, and you create them in the dashboard instead.

Keys, and which are safe to expose #

Project Settings → API. Four values exist and they are not equally sensitive — treating them as if they were is how the service key ends up somewhere it should not be.

The minimum .env to boot is two lines:

SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_ANON_KEY=<your-anon-public-key>

Finding your project ref

The ref is the subdomain of your project URL — for https://abcdefghijklm.supabase.co it is abcdefghijklm. It appears in three places you will need later: the OAuth callback URL, the auth storage key sb-<ref>-auth-token in localStorage, and the DATABASE_URL host for backups. When a session appears to vanish on login, a mismatched ref is the first thing to check.

Google sign-in (optional) #

Email and password work out of the box and need no configuration. Google sign-in is extra work, and on a self-hosted install that work has a catch worth understanding before you start.

Why 127.0.0.1 is the whole problem

The app calls signInWithOAuth({ provider: 'google' }) with redirectTo: window.location.origin + '/dashboard'. That origin is whatever you loaded the app from — normally http://127.0.0.1:3000. The redirect chain is:

your browser
  → accounts.google.com          (consent screen)
  → <project-ref>.supabase.co/auth/v1/callback   (Supabase exchanges the code)
  → http://127.0.0.1:3000/dashboard?code=...      (back to your device)

Google only needs to trust the middle URL, which is a real HTTPS address on supabase.co — so that part is fine. The last hop is between Supabase and your browser, and Supabase does permit loopback redirect URLs. This is why the setup is possible at all.

1. Create the OAuth client in Google Cloud

1. Open Google Cloud Console → APIs & Services → Credentials. Create a project first if you have none.

2. Configure the OAuth consent screen. Choose External, fill in an app name and support email, and add the scopes userinfo.email and userinfo.profile. Nothing else is needed — the app reads only email and display name.

3. Leave publishing status as Testing and add your own Google account under Test users. A testing app is capped at 100 users and shows an "unverified app" warning; for a personal install that is the correct trade rather than submitting for verification.

4. Create credentials → OAuth client ID → Web application.

5. Authorised redirect URI. Exactly one entry, and it is your Supabase callback — not your local address:

   https://<project-ref>.supabase.co/auth/v1/callback

   Find <project-ref> in your SUPABASE_URL. Leave Authorised JavaScript origins empty: the browser never calls Google directly, so it needs no origin, and adding 127.0.0.1 there is the most common way this setup goes wrong.

6. Copy the Client ID and Client secret.

2. Enable the provider in Supabase

1. Supabase dashboard → Authentication → Providers → Google. Toggle it on and paste the Client ID and Client secret.

2. Still in Authentication, open URL Configuration and add your local address to Redirect URLs:

   http://127.0.0.1:3000/dashboard
   http://localhost:3000/dashboard

   Both, because 127.0.0.1 and localhost are different origins to a browser and you will not always arrive by the same one.

   These are the exact paths the app redirects to — signInWithOAuth sends redirectTo: window.location.origin + '/dashboard', and nothing else. Listing the exact URL rather than a pattern is what Supabase itself recommends for anything you are not treating as a preview deployment.

3. Set Site URL to http://127.0.0.1:3000. This is the fallback Supabase uses when no redirectTo is supplied — password-reset and email-confirmation links use it.

In this setup the difference never bites, because the Google side takes exactly one literal URI — your Supabase callback — and never sees your local address at all. The only place a pattern could appear is Supabase's own list, where it is supported. If you have read that “wildcards are not allowed”, that is Google's rule being applied to the wrong system.

3. Re-enable the button

With the provider configured, remove the hiding logic. In server.mjs, find hideGoogleUI and return early:

function hideGoogleUI() {
  return;   // Google OAuth configured — see docs/supabase-setup.html#google-auth
}

Then restart and confirm the round trip:

isotope restart

# the button should now be visible on /auth
# after signing in, confirm the identity was linked:
#   Supabase dashboard → Authentication → Users → your row → Identities

Common failures

Confirming the provider is live

Supabase exposes its own auth configuration publicly. This is the fastest way to know whether the provider is actually enabled, without touching the dashboard:

curl -s https://<project-ref>.supabase.co/auth/v1/settings \
  -H "apikey: <your-anon-public-key>" | python3 -m json.tool

Look at external. A correctly configured project shows both:

{
  "external": {
    "google": true,
    "email": true,
    ...
  },
  "disable_signup": false,
  "mailer_autoconfirm": true
}

Three fields are worth reading while you are here:

This endpoint needs only the anon key, which is public by design — so it is safe to run and safe to paste into a bug report.

Verify #

isotope restart

# reachable and schema present?
curl -s http://127.0.0.1:3000/api/health | python3 -m json.tool

Then sign up in the app. A successful signup writes one row to public.users and triggers immediately create the matching rows in user_profiles, user_stats_summary, user_points, user_onboarding and community_enrollments.

Upgrading an existing project #

isotope-complete.sql is safe to re-run and will add anything missing. Measured on a live project: 1771 statements, 0 failures on the first run and 0 on a second run over the same database, with table, policy, function, trigger, index and constraint counts identical afterwards. Three patches apply only to older projects:

This is intended — Events and Store were removed from the product — but it means the order matters. On a fresh project the correct sequence is:

isotope-complete.sql        # full schema, 42 tables
community-patch-v6.sql      # optional; removes Events + Store, leaves 38 tables
performance-patch.sql       # indexes
sql/verify-security.sql     # check

Run community-patch-v6.sql only if you want Events and Store gone, or if you are repairing an older database. events-expansion.sql is now redundant with the removal block inside v6; it exists so legacy setup instructions that reference it stay safe rather than recreating a feature that no longer ships. Running isotope-complete.sql again after either file will recreate all four tables.