How to Install Supabase: Step-by-Step Guide

How to Install Supabase: A Complete Beginner’s Guide

Supabase is an open-source backend-as-a-service platform built on top of PostgreSQL. It offers developers a powerful alternative to Firebase, featuring real-time APIs, authentication, and storage without managing infrastructure. This step-by-step tutorial will guide you through the installation and setup of Supabase on your own machine or server.

Prerequisites

Basic knowledge of command line interface (CLI)
Docker installed on your system (recommended for local installation)
A modern OS such as Linux, macOS, or Windows with WSL 2
Node.js and npm installed (for CLI and client integration)
Optional: PostgreSQL knowledge for advanced database interactions

Step 1: Install Docker

Supabase uses Docker containers for local deployments. Installing Docker is the easiest way to get all its components running seamlessly.

Go to the official Docker website: Docker Installation Guide (Official site)
Follow the instructions specific to your operating system
After installation, verify Docker is running by executing docker --version in your terminal

Step 2: Clone the Supabase GitHub Repository

While you can use the Supabase CLI to start projects, having the repo helps understand and customize your local setup.

git clone https://github.com/supabase/supabase.git
cd supabase

Step 3: Install the Supabase CLI

The Supabase CLI is essential to manage your local projects, start the development environment, and deploy to the cloud.

Install via npm with the following command:

npm install -g supabase

Check installation with supabase --version

Step 4: Initialize a New Supabase Project

Create a new project folder and initialize Supabase local instance.

mkdir my-supabase-project
cd my-supabase-project
supabase init

This command will create configuration files and a Docker Compose setup.

Step 5: Start the Supabase Local Development Environment

Run the following to get Supabase services running locally:

supabase start

You will see output indicating containers for Postgres, API, Studio (dashboard), and other services starting up.

Step 6: Access Supabase Studio and Use the API

Open your browser and visit http://localhost:54321 to access the Supabase Studio dashboard. From here, you can manage your database, authentication, and storage.

Step 7: Connect Your Application to Supabase

Use the Supabase client library to connect your app to the backend.

npm install @supabase/supabase-js

// Example connection code
import { createClient } from '@supabase/supabase-js'

const supabaseUrl = 'http://localhost:54321'
const supabaseKey = 'your-anon-key'
const supabase = createClient(supabaseUrl, supabaseKey)

Troubleshooting Tips

Docker not starting: Ensure Docker Desktop or service is running properly. Restart if needed.
Port conflicts: Default Supabase ports might conflict with other services. Adjust the ports in the Docker Compose override.
Supabase CLI issues: Ensure Node.js and npm are up to date. Try reinstalling the CLI if problems persist.
Database errors: Check Postgres logs via Docker for insights using docker logs supabase-db.

Summary Checklist

Docker installed and running
Supabase CLI installed
New project initialized with supabase init
Local Supabase services started with supabase start
Supabase Studio accessed locally
Client library integrated into your application

For more database installation guides and backend tutorials, check our how to install FaunaDB tutorial and explore similar content on database setups.

With Supabase installed locally, you now have a powerful backend platform to build modern applications with minimal setup. Happy coding!