Skip to main content

Локальный запуск без Docker (PostgreSQL демоном)

Этот гайд описывает полный локальный запуск проекта с:

  • локально собранным API (без Docker);
  • PostgreSQL демоном на машине;
  • runtime-backend, runtime-host и builder-web.

Инструкция ориентирована на Linux (Ubuntu/Debian). Для macOS/Windows шаги похожи, но команды установки пакетов отличаются.

1. Предварительные требования

1.1. Node.js + pnpm​

Рекомендуемая версия Node.js указана в репозитории. Пример установки через nvm:

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
corepack enable
corepack prepare pnpm@latest --activate

Проверка:

node -v
pnpm -v

1.2. Git​

sudo apt update
sudo apt install -y git

2. Установка PostgreSQL

sudo apt update
sudo apt install -y postgresql postgresql-contrib
sudo systemctl enable postgresql
sudo systemctl start postgresql

Проверка статуса:

sudo systemctl status postgresql

3. Создание пользователей и баз

Ниже пример с двумя пользователями:

  • lowcode_user для API;
  • runtime_backend для preview‑DB.

3.1. Создать пользователя и базы для API​

sudo -u postgres psql <<'SQL'
CREATE USER lowcode_user WITH PASSWORD 'lowcode_password';
CREATE DATABASE lowcode OWNER lowcode_user;
CREATE DATABASE lowcode_shadow OWNER lowcode_user;
SQL

3.2. Создать пользователя и базу для preview‑DB​

sudo -u postgres psql <<'SQL'
CREATE USER runtime_backend WITH PASSWORD 'password';
CREATE DATABASE preview_db OWNER runtime_backend;
SQL

Проверка подключения:

psql postgresql://lowcode_user:lowcode_password@localhost:5432/lowcode -c "\dt"
psql postgresql://runtime_backend:password@localhost:5432/preview_db -c "\dt"

4. Конфигурация .env

4.1. API​

Файл: apps/api/.env

Обязательно:

DATABASE_URL=postgresql://lowcode_user:lowcode_password@localhost:5432/lowcode
SHADOW_DATABASE_URL=postgresql://lowcode_user:lowcode_password@localhost:5432/lowcode_shadow
JWT_ACCESS_SECRET=change-me-access
JWT_REFRESH_SECRET=change-me-refresh
SERVICE_AUTH_ID=runtime-backend
SERVICE_AUTH_SECRET=dev-service-secret
SERVICE_AUTH_JWT_SECRET=dev-service-jwt-secret
PROJECT_SECRETS_KEY=<случайный_64_hex>

Где взять PROJECT_SECRETS_KEY​

Сгенерируйте 32 байта в hex:

openssl rand -hex 32

S3/Storage​

Для работы с attachments нужен S3‑совместимый storage. Можно использовать MinIO локально или любой внешний S3. Минимальные поля:

S3_ENDPOINT=...
S3_BUCKET=...
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...
S3_REGION=...

Если storage не настроен, загрузки файлов и attachments работать не будут.

4.2. runtime-backend​

Файл: apps/runtime-backend/.env (можно скопировать из .env.example).

Ключевые поля:

API_BASE_URL=http://localhost:3000
DATABASE_URL=postgres://runtime_backend:password@localhost:5432/preview_db

RUNTIME_BACKEND_AUTH_TOKEN=dev-runtime-backend-token
API_SERVICE_ID=runtime-backend
API_SERVICE_SECRET=dev-service-secret

API_SERVICE_* должны совпадать с SERVICE_AUTH_* из API.

4.3. runtime-host​

Файл: apps/runtime-host/.env

VITE_API_BASE_URL=http://localhost:3000
VITE_RUNTIME_BACKEND_URL=http://localhost:3001
VITE_RUNTIME_BACKEND_TOKEN=dev-runtime-backend-token

VITE_RUNTIME_BACKEND_TOKEN должен совпадать с RUNTIME_BACKEND_AUTH_TOKEN.

4.4. builder-web​

Файл: apps/builder-web/.env.development

VITE_API_BASE_URL="http://localhost:3000"
VITE_RUNTIME_HOST_BASE_URL="http://localhost:4174"

5. Установка зависимостей

Из корня репозитория:

pnpm install

6. Миграции Prisma (API)

pnpm --filter @lowcode/api prisma:generate
pnpm --filter @lowcode/api prisma:migrate

Prisma migrate dev использует shadow‑DB. Поэтому SHADOW_DATABASE_URL должен быть рабочим.

Если не хотите shadow‑DB — можно выполнить:

pnpm --filter @lowcode/api exec prisma migrate deploy --schema prisma/schema.prisma

7. Запуск сервисов

7.1. API​

pnpm --filter @lowcode/api dev

API будет доступен на http://localhost:3000.

7.2. runtime-backend​

pnpm --filter @lowcode/runtime-backend dev

runtime-backend будет доступен на http://localhost:3001.

7.3. runtime-host​

pnpm --filter @lowcode/runtime-host dev

runtime-host по умолчанию доступен на http://localhost:4174.

7.4. builder-web​

pnpm --filter @lowcode/builder-web dev

builder-web по умолчанию доступен на http://localhost:5173.

8. Проверка работоспособности

  1. Открой builder-web (5173), авторизуйся.
  2. Создай проект, добавь страницу.
  3. Нажми Open in runtime-host — откроется runtime-host.
  4. В runtime-host проверь, что:
    • статус ready;
    • dataSources выполняются через runtime-backend;
    • preview‑DB подключена.
  5. Нажми Export project и скачай архив.

9. Частые ошибки

9.1. Prisma просит reset базы​

Обычно это означает drift между миграциями и фактической схемой. Самый быстрый вариант без потери данных — использовать:

pnpm --filter @lowcode/api exec prisma migrate deploy --schema prisma/schema.prisma

9.2. runtime-host не может вызвать runtime-backend​

Проверь:

  • VITE_RUNTIME_BACKEND_URL
  • VITE_RUNTIME_BACKEND_TOKEN
  • RUNTIME_BACKEND_AUTH_TOKEN

Токены должны совпадать.

9.3. runtime-backend пишет DATABASE_URL is not configured​

Проверь apps/runtime-backend/.env и перезапусти сервис.

10. Полезные команды

pnpm --filter @lowcode/api prisma:generate
pnpm --filter @lowcode/api prisma:migrate
pnpm --filter @lowcode/api dev

pnpm --filter @lowcode/runtime-backend dev
pnpm --filter @lowcode/runtime-host dev
pnpm --filter @lowcode/builder-web dev