Руководство по установке

🇷🇺 Русский | 🇬🇧 English

📜 Пошаговая инструкция

🐳 Быстрый старт: Docker (рекомендуется)

Требования: Docker и Docker Compose

git clone https://github.com/fedorabakumets/telegram-bot-builder.git
cd telegram-bot-builder
docker compose up -d
docker compose logs -f

Полезные команды:

docker compose down        # Остановить
docker compose build --no-cache  # Пересобрать
docker compose logs -f     # Логи

✅ Готово! Приложение доступно по адресу: http://localhost:5000

Ручная установка

Требования

Node.js ≥ 18.0.0
PostgreSQL ≥ 17
Redis ≥ 7
Python ≥ 3.10 (рекомендуется 3.13, для сгенерированных ботов)
Git

Шаг 1: Установка Git

🐧 Linux (Ubuntu/Debian) 🏁 Windows 🍎 macOS

🐧 Linux (Ubuntu/Debian)	🏁 Windows	🍎 macOS
Способ 1: Через терминал (рекомендуется): Ubuntu/Debian: `sudo apt update && sudo apt install -y git` Fedora/CentOS: `sudo dnf install -y git` Arch Linux: `sudo pacman -S git` Способ 2: С сайта: Перейдите на git-scm.com/install/linux Выберите ваш дистрибутив Следуйте инструкции по установке Проверка установки: `git --version`	Способ 1: Через winget (рекомендуется): `winget install --id Git.Git -e --source winget` Способ 2: Через установщик: Скачайте с git-scm.com/install/windows Запустите `.exe` файл Оставьте настройки по умолчанию (нажимайте "Next") Проверка установки: Откройте PowerShell от имени администратора (`Win + X` → "Терминал (администратор)"): `git --version` Если версия не отображается, перезапустите PowerShell	Способ 1: Через Homebrew (рекомендуется): `# Установка Homebrew (если не установлен) /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Установка Git brew install git` Способ 2: С сайта: Перейдите на git-scm.com/install/mac Скачайте установщик для macOS (`.dmg`) Откройте `.dmg` файл и перетащите Git в Applications Проверка установки: `git --version` Homebrew — менеджер пакетов для macOS, упрощает установку программ

Способ 1: Через терминал (рекомендуется):

Ubuntu/Debian:

sudo apt update && sudo apt install -y git

Fedora/CentOS:

sudo dnf install -y git

Arch Linux:

sudo pacman -S git

Способ 2: С сайта:

Перейдите на git-scm.com/install/linux
Выберите ваш дистрибутив
Следуйте инструкции по установке

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

git --version

Способ 1: Через winget (рекомендуется):

winget install --id Git.Git -e --source winget

Способ 2: Через установщик:

Скачайте с git-scm.com/install/windows
Запустите .exe файл
Оставьте настройки по умолчанию (нажимайте "Next")

Проверка установки: Откройте PowerShell от имени администратора (Win + X → "Терминал (администратор)"):

git --version

Если версия не отображается, перезапустите PowerShell

Способ 1: Через Homebrew (рекомендуется):

# Установка Homebrew (если не установлен)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Установка Git
brew install git

Способ 2: С сайта:

Перейдите на git-scm.com/install/mac
Скачайте установщик для macOS (.dmg)
Откройте .dmg файл и перетащите Git в Applications

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

git --version

Homebrew — менеджер пакетов для macOS, упрощает установку программ

Шаг 2: Установка Node.js LTS

🐧 Linux 🏁 Windows 🍎 macOS

🐧 Linux	🏁 Windows	🍎 macOS
Способ 1: Через терминал (рекомендуется): `curl -fsSL https://deb.nodesource.com/setup_lts.x \| sudo -E bash - sudo apt install -y nodejs node -v && npm -v` Способ 2: С сайта: Перейдите на nodejs.org Скачайте `.deb` или `.rpm` пакет Установите: `sudo dpkg -i nodejs_*.deb`	Способ 1: Через winget: `winget install OpenJS.NodeJS.LTS node -v && npm -v` Способ 2: С сайта: Перейдите на nodejs.org Скачайте установщик (`.msi`) Запустите и следуйте инструкциям Проверьте установку: `node -v npm -v`	Способ 1: Через Homebrew: `brew install node@lts node -v && npm -v` Способ 2: С сайта: Перейдите на nodejs.org Скачайте установщик (`.pkg`) Запустите и следуйте инструкциям

Способ 1: Через терминал (рекомендуется):

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs
node -v && npm -v

Способ 2: С сайта:

Перейдите на nodejs.org
Скачайте .deb или .rpm пакет
Установите: sudo dpkg -i nodejs_*.deb

Способ 1: Через winget:

winget install OpenJS.NodeJS.LTS
node -v && npm -v

Способ 2: С сайта:

Перейдите на nodejs.org
Скачайте установщик (.msi)
Запустите и следуйте инструкциям
Проверьте установку:

node -v
npm -v

Способ 1: Через Homebrew:

brew install node@lts
node -v && npm -v

Способ 2: С сайта:

Перейдите на nodejs.org
Скачайте установщик (.pkg)
Запустите и следуйте инструкциям

Шаг 3: Установка PostgreSQL

🐧 Linux 🏁 Windows 🍎 macOS

🐧 Linux	🏁 Windows	🍎 macOS
Способ 1: Через терминал: `sudo apt install -y postgresql postgresql-contrib sudo systemctl enable postgresql sudo systemctl start postgresql` Способ 2: Официальный репозиторий: Посетите postgresql.org/download/linux Выберите дистрибутив Следуйте инструкции	Способ 1: Через winget (рекомендуется): `winget install PostgreSQL.PostgreSQL.17` При установке запомните пароль для пользователя `postgres` (по умолчанию: `postgres`). Порт: `5432`. Проверка установки: `psql -U postgres -c "SELECT version();"` Способ 2: С сайта: Перейдите на postgresql.org/download/windows Скачайте установщик Запустите и запомните пароль `postgres`	Способ 1: Через Homebrew: `brew install postgresql@15 brew services start postgresql@15` Способ 2: С сайта: Перейдите на postgresql.org/download/macosx Скачайте установщик Запустите и следуйте инструкциям

Способ 1: Через терминал:

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

Способ 2: Официальный репозиторий:

Посетите postgresql.org/download/linux
Выберите дистрибутив
Следуйте инструкции

Способ 1: Через winget (рекомендуется):

winget install PostgreSQL.PostgreSQL.17

При установке запомните пароль для пользователя postgres (по умолчанию: postgres). Порт: 5432.

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

psql -U postgres -c "SELECT version();"

Способ 2: С сайта:

Перейдите на postgresql.org/download/windows
Скачайте установщик
Запустите и запомните пароль postgres

Способ 1: Через Homebrew:

brew install postgresql@15
brew services start postgresql@15

Способ 2: С сайта:

Перейдите на postgresql.org/download/macosx
Скачайте установщик
Запустите и следуйте инструкциям

Шаг 4: Установка Python 3

🐧 Linux 🏁 Windows 🍎 macOS

🐧 Linux	🏁 Windows	🍎 macOS
Способ 1: Через терминал: `sudo apt install -y python3 python3-venv python3-pip python3 --version` Способ 2: Официальный сайт: Посетите python.org/downloads Выберите версию для Linux Следуйте инструкции по компиляции	Способ 1: Через winget: `winget install Python.Python.3.12` Способ 2: С сайта: Перейдите на python.org/downloads Скачайте установщик При установке отметьте "Add Python to PATH" Проверьте установку: `python --version`	Способ 1: Через Homebrew: `brew install python python3 --version` Способ 2: С сайта: Перейдите на python.org/downloads Скачайте установщик для macOS (`.pkg`) Запустите и следуйте инструкциям

Способ 1: Через терминал:

sudo apt install -y python3 python3-venv python3-pip
python3 --version

Способ 2: Официальный сайт:

Посетите python.org/downloads
Выберите версию для Linux
Следуйте инструкции по компиляции

Способ 1: Через winget:

winget install Python.Python.3.12

Способ 2: С сайта:

Перейдите на python.org/downloads
Скачайте установщик
При установке отметьте "Add Python to PATH"
Проверьте установку:

python --version

Способ 1: Через Homebrew:

brew install python
python3 --version

Способ 2: С сайта:

Перейдите на python.org/downloads
Скачайте установщик для macOS (.pkg)
Запустите и следуйте инструкциям

Шаг 5: Установка Redis

🐧 Linux (Ubuntu/Debian) 🏁 Windows 🍎 macOS

🐧 Linux (Ubuntu/Debian)	🏁 Windows	🍎 macOS
Способ 1: Через терминал: `sudo apt install -y redis-server sudo systemctl enable redis-server sudo systemctl start redis-server` Проверка установки: `redis-cli ping` Должен ответить `PONG`	Способ 1: Memurai (рекомендуется для Windows): Memurai — нативный Windows-порт, полностью совместимый с Redis 7.2+. Устанавливается как Windows-служба и работает без WSL. `winget install Memurai.MemuraiDeveloper` После установки служба запускается автоматически. Управление: `net start Memurai # Запустить net stop Memurai # Остановить` Способ 2: Через WSL2: Установите Redis внутри WSL: `sudo apt install -y redis-server sudo service redis-server start` Способ 3: Docker: `docker run -d --name redis -p 6379:6379 redis:alpine` Проверка установки: `redis-cli ping` Должен ответить `PONG`	Способ 1: Через Homebrew: `brew install redis brew services start redis` Проверка установки: `redis-cli ping` Должен ответить `PONG`

Способ 1: Через терминал:

sudo apt install -y redis-server
sudo systemctl enable redis-server
sudo systemctl start redis-server

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

redis-cli ping

Должен ответить PONG

Способ 1: Memurai (рекомендуется для Windows):

Memurai — нативный Windows-порт, полностью совместимый с Redis 7.2+. Устанавливается как Windows-служба и работает без WSL.

winget install Memurai.MemuraiDeveloper

После установки служба запускается автоматически. Управление:

net start Memurai   # Запустить
net stop Memurai    # Остановить

Способ 2: Через WSL2:

Установите Redis внутри WSL:

sudo apt install -y redis-server
sudo service redis-server start

Способ 3: Docker:

docker run -d --name redis -p 6379:6379 redis:alpine

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

redis-cli ping

Должен ответить PONG

Способ 1: Через Homebrew:

brew install redis
brew services start redis

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

redis-cli ping

Должен ответить PONG

Шаг 6: Настройка базы данных

🐧 Linux	🏁 Windows	🍎 macOS
`sudo -u postgres psql` `CREATE DATABASE telegram_bot_builder; GRANT ALL PRIVILEGES ON DATABASE telegram_bot_builder TO postgres; \q` По умолчанию используется встроенный пользователь `postgres`. Пароль задаётся при установке PostgreSQL.	`psql -U postgres` `CREATE DATABASE telegram_bot_builder; GRANT ALL PRIVILEGES ON DATABASE telegram_bot_builder TO postgres; \q` Пароль `postgres` задаётся при установке. Если забыли — переустановите или измените через `ALTER USER postgres PASSWORD 'новый_пароль';`	`psql postgres` `CREATE DATABASE telegram_bot_builder; GRANT ALL PRIVILEGES ON DATABASE telegram_bot_builder TO postgres; \q` На macOS пользователь `postgres` обычно создаётся без пароля при установке через Homebrew.

Шаг 7: Клонирование проекта

🐧 Linux 🏁 Windows 🍎 macOS

🐧 Linux	🏁 Windows	🍎 macOS
`cd /opt sudo git clone https://github.com/fedorabakumets/telegram-bot-builder.git sudo chown -R "$USER":"$USER" telegram-bot-builder cd telegram-bot-builder`	`mkdir C:\projects cd C:\projects git clone https://github.com/fedorabakumets/telegram-bot-builder.git cd telegram-bot-builder`	`mkdir -p ~/projects cd ~/projects git clone https://github.com/fedorabakumets/telegram-bot-builder.git cd telegram-bot-builder`

cd /opt
sudo git clone https://github.com/fedorabakumets/telegram-bot-builder.git
sudo chown -R "$USER":"$USER" telegram-bot-builder
cd telegram-bot-builder

mkdir C:\projects
cd C:\projects
git clone https://github.com/fedorabakumets/telegram-bot-builder.git
cd telegram-bot-builder

mkdir -p ~/projects
cd ~/projects
git clone https://github.com/fedorabakumets/telegram-bot-builder.git
cd telegram-bot-builder

Шаг 8: Настройка окружения

1. Скопируйте шаблон:

🐧 Linux	🏁 Windows	🍎 macOS
`cp .env.example .env nano .env`	`copy .env.example .env notepad .env`	`cp .env.example .env nano .env`

2. Минимальные переменные для локальной разработки:

NODE_ENV=development
PORT=5000

# PostgreSQL
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/telegram_bot_builder

# Redis (Memurai на Windows, redis на Linux/macOS)
REDIS_URL=redis://localhost:6379

# Секрет для подписи сессий
SESSION_SECRET=любая-случайная-строка-для-локалки

# Ключ входа в /admin (OpenAPI и ops-панель)
ADMIN_API_KEY=любая-случайная-строка-для-локалки

🔐 SESSION_SECRET — обязателен в production. В режиме development можно указать любую строку (или вовсе опустить — будет dev-fallback с предупреждением). Но в NODE_ENV=production приложение специально не запустится, если SESSION_SECRET не задан: без него любой смог бы подделать cookie сессии и войти под чужим аккаунтом. Сгенерируйте надёжное случайное значение:
# Linux/macOS (или Git Bash на Windows)
openssl rand -hex 32
# Любая ОС с Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
При смене SESSION_SECRET все активные сессии становятся недействительными — пользователям нужно будет войти заново.

🔑 ADMIN_API_KEY — обязателен в production для доступа к админ-панели и OpenAPI-документации. В development переменную можно не задавать — будет использоваться небезопасный dev-fallback dev-only-insecure-admin-key (с предупреждением в лог). В production без ADMIN_API_KEY маршруты /admin и /admin/docs не монтируются. Сгенерируйте отдельное значение тем же способом, что и для SESSION_SECRET.

📖 Документация API:

Режим Адрес Доступ
Development http://localhost:5000/docs Публично (удобно при разработке)
Development http://localhost:5000/admin По ключу ADMIN_API_KEY (или dev-fallback)
Production https://ваш-домен/admin/login Только по ADMIN_API_KEY
Production https://ваш-домен/admin/docs После входа: Swagger, Scalar, Redoc, RapiDoc

Спецификация OpenAPI: /docs-json (dev) или /admin/openapi.json (prod, после входа).

Режим	Адрес	Доступ
Development	`http://localhost:5000/docs`	Публично (удобно при разработке)
Development	`http://localhost:5000/admin`	По ключу `ADMIN_API_KEY` (или dev-fallback)
Production	`https://ваш-домен/admin/login`	Только по `ADMIN_API_KEY`
Production	`https://ваш-домен/admin/docs`	После входа: Swagger, Scalar, Redoc, RapiDoc

💡 Не хотите настраивать Telegram Login? Добавьте SKIP_AUTH=true в .env — авторизация будет отключена в любом режиме (dev и production). Вместо Telegram виджета появится простая форма ввода ID. При SKIP_AUTH=true строгая проверка id_token на POST /api/auth/telegram не включается.

✅ Production checklist (строгий Telegram Login):

SESSION_SECRET задан

Telegram Client ID настроен (Setup Wizard или env)

TELEGRAM_BOT_TOKEN — для Mini App HMAC (без него Mini App login в prod недоступен)

SKIP_AUTH не задан (иначе вход по ID без proof)

Документация: docs/features/studio-auth.md, docs/api/auth.md

💡 Telegram Login настраивается через Setup Wizard при первом запуске — вручную заполнять не нужно.

Шаг 9: Установка зависимостей и запуск

1. Установка зависимостей Node.js:

npm install

2. Установка Python-зависимостей (для запуска ботов):

pip install -r requirements.txt

3. Запуск приложения:

Для разработки достаточно одной команды:

npm run dev

Она запускает сервер и клиент одновременно с автоперезагрузкой — любые изменения в коде сразу применяются без перезапуска. Открывай в браузере http://localhost:5000 и работай.

Режим	Команда	Описание
🧪 Разработка	`npm run dev`	Запуск с автоперезагрузкой при изменениях
🚀 Продакшен	`npm run build` → `npm run start`	Сборка и запуск готовой версии

✅ Готово! Приложение доступно по адресу: http://localhost:5000

После запуска также доступны:

Редактор: http://localhost:5000
OpenAPI (dev): http://localhost:5000/docs — hub с выбором UI
Админка: http://localhost:5000/admin/login — ключ из ADMIN_API_KEY (или dev-only-insecure-admin-key, если переменная не задана)

Шаг 10: Настройка Telegram Login (Setup Wizard)

⚠️ Для локальной разработки (NODE_ENV=development) этот шаг необязателен — приложение работает без авторизации. Setup Wizard нужен только при деплое в продакшен.

💡 Если вы не хотите настраивать Telegram Login вообще — добавьте SKIP_AUTH=true в .env. Авторизация будет отключена в любом режиме, вход по Telegram ID без верификации.

При первом открытии приложения в продакшене появится Setup Wizard — он попросит ввести данные для авторизации через Telegram.

Как получить данные из BotFather:

1. Откройте @BotFather → выберите бота → Bot Settings → Login Widget

2. Переключитесь на OIDC:

3. Подтвердите переключение:

4. Скопируйте Client ID и Client Secret:

5. Укажите Redirect URIs (адрес вашего приложения):

Для локальной разработки: http://localhost:5000

6. Введите полученные данные в Setup Wizard:

Client ID — числовой ID
Client Secret — секретный ключ
Bot Username — имя бота без @

✅ После сохранения приложение готово к работе!

Шаг 11: Подключение ИИ-агента через MCP (опционально)

💡 Этот шаг нужен, только если вы хотите подключить ИИ-агента (Kiro / Cursor / Claude Desktop) для редактирования ботов на холсте в реальном времени. Для обычной работы он не требуется.

MCP-агент идентифицируется по персональному токену (PAT) — как API-ключ у GitHub/n8n. Токен привязан к вашему аккаунту и даёт доступ только к вашим проектам.

1. Откройте проект → вкладка «Агент» → кнопка «Создать токен».

2. Задайте название (например «Kiro на ноуте») → «Создать».

3. Полный токен mcp_… показывается ровно один раз — сразу скопируйте его. В базе хранится только sha-256 хеш, повторно секрет не отобразится.

4. Там же скопируйте готовый сниппет — по умолчанию Remote URL (без клона репо). Вставьте в конфиг MCP-клиента:

{
  "mcpServers": {
    "botcraft-builder": {
      "url": "https://<ваш-домен>/mcp",
      "headers": {
        "Authorization": "Bearer mcp_..."
      }
    }
  }
}

Для локальной разработки (нужен клон репо) во вкладке «Агент» есть сниппет Stdio:

{
  "mcpServers": {
    "botcraft-builder": {
      "command": "npm",
      "args": ["run", "mcp:bot-builder"],
      "cwd": "<путь к каталогу проекта>",
      "env": {
        "API_BASE_URL": "http://localhost:5000",
        "MCP_AGENT_TOKEN": "mcp_..."
      }
    }
  }
}

Remote: подробности в docs/mcp/remote-http.md.

MCP_AGENT_TOKEN / Bearer — токен из шага 3. Храните как пароль, не коммитьте.

Токен можно мгновенно отозвать на вкладке «Агент».

Флаг сервера: MCP_HTTP_ENABLED (по умолчанию включён).

💡 Нужно обновить проект? См. 🔄 Как обновить проект с GitHub

📜 Пошаговая инструкция​

Ручная установка​

Требования​

📜 Пошаговая инструкция

Ручная установка

Требования