Как поднять Supabase локально — полное руководство для вайбкодеров

Работать с облачным Supabase удобно, пока проект маленький и интернет стабильный. Но как только начинаются реальные итерации — частые правки схемы, тест авторизации, отладка Storage — облако превращается в тормоз: долгие запросы, случайный лимит на бесплатном плане, невозможность работать офлайн.

Локальный Supabase решает это полностью. Вы получаете точную копию всего стека — PostgreSQL, Auth, Storage, Realtime, Studio — прямо на своей машине. Это стандартный способ разработки в 2026 году, и в этой статье я покажу, как это сделать правильно, с нуля до первого рабочего запроса.

## 1. Что именно запускается локально

Supabase — это не одна программа, а набор сервисов, скреплённых Docker Compose. Когда вы поднимаете его локально, запускаются:

• PostgreSQL 15 — основная база данных.
• PostgREST — автоматически генерирует REST API из вашей схемы БД.
• GoTrue — сервис авторизации (email, OAuth, magic link).
• Realtime — WebSocket-сервер для подписок на изменения в таблицах.
• Storage API — S3-совместимое хранилище файлов.
• Kong — API-шлюз, через который проходят все запросы.
• Supabase Studio — веб-интерфейс для управления всем стеком (на порту 54323).
• Inbucket — локальный почтовый сервер для тестирования писем (на порту 54324).

Всё это поднимается одной командой и работает идентично облаку. Миграции, которые вы пишете локально, применяются в облаке без изменений.

## 2. Требования перед началом

Убедитесь, что установлено:

• Docker Desktop (или Docker Engine + Docker Compose на Linux). Версия 20.10+.
• Node.js 18+ — нужен для установки Supabase CLI через npm.
• Свободно ~4 ГБ RAM (все контейнеры вместе потребляют 2–3 ГБ).
• ~3 ГБ на диске для образов.

Проверить можно так:

docker --version
# Docker version 26.1.0 или выше

node --version
# v20.x.x или выше

## ## 3. Установка Supabase CLI

Supabase CLI — это единственная утилита, которая вам нужна. Она управляет локальным стеком, миграциями и связью с облаком.

macOS / Linux (через npm)

npm install -g supabase

macOS (через Homebrew)

brew install supabase/tap/supabase

Windows

# Через Scoop
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase

Проверяем установку:

supabase --version
# 1.200.x или выше

## 4. Инициализация проекта

Перейдите в папку вашего проекта и инициализируйте Supabase:

cd my-project
supabase init

Команда создаёт папку supabase/ со следующей структурой:

supabase/
├── config.toml        # конфигурация локального стека
├── migrations/        # SQL-миграции
└── seed.sql           # начальные данные (опционально)

Файл config.toml — это главный конфиг. По умолчанию он уже рабочий, но вы можете изменить порты, если что-то конфликтует:

[api]
port = 54321          # PostgREST + Kong

[db]
port = 54322          # PostgreSQL

[studio]
port = 54323          # Supabase Studio

[inbucket]
port = 54324          # Тестовая почта

[storage]
file_size_limit = "50MiB"

## 5. Запуск локального стека

supabase start

Первый запуск займёт 3–7 минут — Docker скачает все образы (~2 ГБ). Последующие запуски — 15–30 секунд.

После успешного старта в терминале появится вывод с ключами:

Started supabase local development setup.

         API URL: http://127.0.0.1:54321
     GraphQL URL: http://127.0.0.1:54321/graphql/v1
  S3 Storage URL: http://127.0.0.1:54321/storage/v1/s3
          DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
      Studio URL: http://127.0.0.1:54323
    Inbucket URL: http://127.0.0.1:54324
        anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Сохраните эти значения — они понадобятся для подключения из вашего приложения.

Если забыли — можно получить снова:

supabase status

## 6. Supabase Studio — локальный дашборд

Откройте в браузере http://127.0.0.1:54323.

Вы увидите полноценный Supabase Studio — тот же интерфейс, что и в облаке. Здесь можно:

• Просматривать и редактировать таблицы через Table Editor.
• Писать SQL-запросы через SQL Editor.
• Управлять пользователями через Authentication.
• Загружать файлы через Storage.
• Просматривать логи всех сервисов.

Inbucket (тестовая почта) доступен на http://127.0.0.1:54324. Все письма от Auth (подтверждение email, magic link, сброс пароля) приходят сюда — не нужно настраивать SMTP для разработки.

## 7. Подключение к проекту из кода

Переменные окружения (.env)

NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Инициализация клиента (JS/TS)

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

Если используете Next.js с серверными компонентами, добавьте SUPABASE_SERVICE_ROLE_KEY для серверных операций:

// Только на сервере — никогда не передавайте в браузер
const supabaseAdmin = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
)

## 8. Миграции — правильный способ менять схему

Никогда не меняйте схему базы напрямую через Studio в долгосрочных проектах — изменения потеряются при сбросе или не попадут в облако. Используйте миграции.

Создать новую миграцию

supabase migration new create_posts_table

Создаётся файл supabase/migrations/20260527120000_create_posts_table.sql. Напишите в нём SQL:

create table posts (
  id uuid default gen_random_uuid() primary key,
  title text not null,
  content text,
  user_id uuid references auth.users(id) on delete cascade,
  created_at timestamptz default now()
);

-- Включаем Row Level Security
alter table posts enable row level security;

-- Политика: пользователь видит только свои посты
create policy "Users can view own posts"
  on posts for select
  using (auth.uid() = user_id);

-- Политика: пользователь может создавать посты
create policy "Users can insert own posts"
  on posts for insert
  with check (auth.uid() = user_id);

Применить миграции

supabase db reset

Эта команда сбрасывает локальную БД и применяет все миграции заново + seed.sql. Используйте её когда нужно получить чистое состояние.

Применить только новые миграции без сброса:

supabase migration up

Сгенерировать TypeScript-типы из схемы

supabase gen types typescript --local > src/types/database.types.ts

После этого у вас будут полные типы для всех таблиц — ИИ-ассистент будет работать с ними значительно точнее.

## 9. Seed-данные — тестовое наполнение базы

Файл supabase/seed.sql выполняется при каждом supabase db reset. Добавьте туда тестовые данные:

-- Создаём тестового пользователя (только для локальной разработки)
insert into auth.users (id, email, encrypted_password, email_confirmed_at)
values (
  '00000000-0000-0000-0000-000000000001',
  'test@example.com',
  crypt('password123', gen_salt('bf')),
  now()
);

-- Тестовые посты
insert into posts (title, content, user_id) values
  ('Первый пост', 'Привет, мир!', '00000000-0000-0000-0000-000000000001'),
  ('Второй пост', 'Supabase локально — это просто.', '00000000-0000-0000-0000-000000000001');

## 10. Остановка и управление стеком

# Остановить (данные сохраняются)
supabase stop

# Остановить и удалить все данные (полный сброс)
supabase stop --no-backup

# Посмотреть статус всех сервисов
supabase status

# Логи конкретного сервиса
supabase logs db       # PostgreSQL
supabase logs auth     # GoTrue
supabase logs realtime # Realtime
supabase logs storage  # Storage

## 11. Синхронизация с облачным проектом

Когда локальная разработка готова, можно связать локальный проект с облаком:

# Авторизоваться в Supabase
supabase login

# Связать с облачным проектом
supabase link --project-ref ваш-project-ref

# Применить все локальные миграции в облаке
supabase db push

project-ref можно найти в URL вашего проекта на supabase.com: https://app.supabase.com/project/ваш-project-ref.

Важно: supabase db push применяет только новые миграции. Уже применённые в облаке миграции он не трогает.

## 12. Типичные проблемы и решения

Docker не запускается

# Убедитесь, что Docker Desktop запущен
docker info

# Если ошибка "port already in use" — найдите и остановите процесс
lsof -i :54321
kill -9 <PID>

Studio не открывается

Подождите 30–60 секунд после supabase start — Studio запускается последним. Если не помогло:

supabase stop && supabase start

Ошибка при миграции

Если миграция сломала схему — сбросьте базу:

supabase db reset

Auth не отправляет письма

Письма в локальной среде не отправляются на реальный email. Откройте Inbucket: http://127.0.0.1:54324 — все письма там.

Конфликт портов на Windows/Mac

Измените порты в supabase/config.toml и перезапустите стек.

## 13. Советы для работы с ИИ-ассистентом

Если вы используете Cursor, Claude Code или аналогичный инструмент — добавьте в AGENTS.md или системный промпт:

## Supabase

- Локальный стек запущен через `supabase start`
- URL: http://127.0.0.1:54321
- Все изменения схемы — только через миграции в `supabase/migrations/`
- Типы сгенерированы в `src/types/database.types.ts`
- RLS включён на всех таблицах — всегда добавляй политики при создании таблицы
- Для сброса базы: `supabase db reset`

ИИ будет понимать структуру проекта и не будет предлагать менять схему напрямую через Studio.

## Заключение

Локальный Supabase — это не «сложная настройка», а стандартный рабочий процесс, который занимает 10 минут при первом запуске и ускоряет разработку в разы. Вы получаете полный контроль над стеком, работаете офлайн, тестируете миграции без страха сломать облачную базу и применяете всё в прод одной командой.

Краткий маршрут:

1. npm install -g supabase — установить CLI.
2. supabase init — инициализировать проект.
3. supabase start — запустить стек.
4. Studio на http://127.0.0.1:54323 — управлять данными.
5. Миграции через supabase migration new — менять схему.
6. supabase db push — выкатить в облако.

Если у вас уже есть облачный проект и вы хотите подтянуть его схему локально — пишите в комментариях, разберём этот сценарий отдельно.