Create a local Supabase project

The best place to learn Supabase is a local stack on your own machine. You get the whole platform, Postgres, Auth, Storage, the Data API, and Studio, running in Docker containers you can throw away and rebuild. No hosted project gets touched while you experiment.

You need two things: the Supabase CLI and a Docker-compatible runtime such as Docker Desktop or OrbStack. On a Mac, Homebrew installs the CLI with brew install supabase/tap/supabase.

Then, in an empty directory:

supabase init
# Finished supabase init.

This creates a supabase folder. That folder is the description of your project: config.toml for configuration, migrations/ for schema changes, seed.sql for test data, and functions/ for Edge Functions. Everything in it belongs in Git.

Now start the services:

supabase start

The first run downloads the container images, so give it a few minutes. When it finishes, the CLI prints the local URLs and keys. You can print them again at any time:

supabase status
#          API URL: http://127.0.0.1:54321
#           DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
#       Studio URL: http://127.0.0.1:54323

Open the Studio URL in your browser. That’s the same dashboard you get on the hosted platform, pointed at your local database. Write down the API URL and the local keys, because the client code in the next lessons needs them.

Prove it can be rebuilt

Start from an empty directory and prove it can be rebuilt:

supabase init
supabase start
supabase status
supabase db reset

Commit configuration, migrations, and intentional seed data. Do not commit generated credentials or temporary container state. Stop the stack, start it again, and run the same reset before depending on dashboard edits that have no migration.

supabase db reset drops the local database and rebuilds it from nothing but your migration files and seed.sql. If it comes back clean, your project state lives in files, not inside a running container. That is the property we want, and it is the reason a table you created by clicking around in Studio does not count until a migration describes it.

What goes in Git

Commit supabase/config.toml, supabase/migrations/, supabase/seed.sql, and your functions. Leave out the supabase/.temp/ folder the CLI writes for itself. The default local keys are the same on every machine, so leaking them is harmless, but never put the keys of a hosted project in the repository. The habit matters more than the single case.

One caution before you move on. The local stack is very close to the hosted platform, but the official docs say it is not identical in every feature. When something works locally and fails on a hosted project, check the docs for that feature before you assume a bug in your code.