Configure Supabase

Mosayic uses Supabase for auth, the database, and storage. While developing, you run Supabase locally — it’s a Docker stack of Postgres + GoTrue (auth) + Storage + a Studio web UI. When you ship, your app points at a hosted Supabase project instead.

This step starts the local stack and wires its credentials into your mobile and API code.

What supabase start does

The Supabase CLI manages a small fleet of Docker containers:

• Postgres on port 54322
• PostgREST (auto-generated REST API) on port 54321
• GoTrue (auth server)
• Realtime
• Storage
• Inbucket (an SMTP catcher for testing email flows) on port 54324
• Supabase Studio on port 54323 — a local dashboard you can open in your browser

The first run downloads several Docker images and takes a few minutes. Subsequent starts take seconds.

Run the step

1. Make sure Docker is running. If you skipped the earlier check, open Docker Desktop now and wait for the whale icon in your menu bar to settle.

2. Click “Start Supabase” in the dashboard.

   The backend runs (via the extension):

   cd <project>/api
   supabase start

3. Wait for the green status. The dashboard shows live output from the CLI. When it’s done, you’ll see something like:

   API URL:    http://127.0.0.1:54321
   Studio URL: http://127.0.0.1:54323
   anon key:   eyJhbGc...
   service_role key: eyJhbGc...

4. The dashboard reads those credentials and patches them into your project. Specifically:

   • mobile/.env gets EXPO_PUBLIC_SUPABASE_URL and EXPO_PUBLIC_SUPABASE_PUB_KEY (the anon key)
   • api/.env gets SUPABASE_URL and SUPABASE_SECRET_KEY (the service role key)

   It also rewrites the URLs to use your machine’s LAN IP instead of 127.0.0.1, so when your phone hits these values they point at your laptop, not the phone itself.

Note

The EXPO_PUBLIC_ prefix is meaningful: any env var with that prefix is bundled into the mobile app at build time and is therefore public. The anon key is designed to be safe in client code as long as your Postgres Row-Level Security policies are correct. The service role key, by contrast, must never ship in mobile code — it’s only used server-side from your API.

Open Supabase Studio

While the local stack is running, you can open Studio at http://127.0.0.1:54323 to:

• Browse your tables
• Run SQL queries
• Inspect users that have signed up
• View storage buckets
• See realtime subscriptions

Studio is just a browser tab — it doesn’t need any login because it’s purely local.

Stopping and restarting

You don’t normally need to think about this — Supabase keeps running until you stop Docker. If you want to stop it explicitly:

cd <project>/api
supabase stop

The dashboard’s Preview screen also has Start/Stop buttons that do the same thing.

When things go wrong

• Port already in use. Something else (maybe a previous Supabase instance) is on 54321. Run supabase stop and try again. The Preview screen has a “Kill port” button that does this for you.
• Docker not running. Start Docker Desktop and re-try.
• supabase start hangs. Network issues pulling Docker images. Cancel and re-run; partial downloads resume.

Migrations

Each Mosayic project ships with a starter migration in api/supabase/migrations/. When you run supabase start, the CLI applies these to your local Postgres. As you build features and add tables, you’ll add new migration files (Mosayic’s Blueprint cards walk you through this).

When you eventually deploy to a hosted Supabase project, GitHub Actions runs supabase db push to apply the same migrations there. There’s no schema drift between local and prod — both come from the same SQL files.

Next

Almost done. The next screen is the All Services Connected checklist, then Your First Build.