BotVa -- Деплой

Варіанти встановлення

Локальне встановлення

Вимоги

• Node.js 20+ (node --version)
• macOS або Linux
• Git

Кроки

# 1. Клонувати
git clone https://github.com/cohe4ko/BotVa.git BotVa
cd BotVa

# 2. Встановити залежності та зібрати
./scripts/deploy.sh setup

# 3. Створити бота (CLI або через адмін-панель)
npm run new-bot -- my-bot personal-assistant --emoji 🧑‍💼 --name "Мій Бот"

# 4. Налаштувати токени
#    Відкрий bots/my-bot/.env та встанови:
#    - TELEGRAM_BOT_TOKEN  (отримати у @BotFather)
#    - ALLOWED_CHAT_ID     (надіслати /chatid боту)

# 5. Залогінитись в Claude CLI
#    Запустити адмін-панель → Термінал (/terminal)
#    та пройти логін через підписку (не API key)

# 6. Запустити
./scripts/deploy.sh start

Також можна створити бота через веб: ./scripts/deploy.sh admin → http://localhost:3000 → Create Bot.

Веб-інсталятор

Крок 1: IP-адреса та домен сервера. Крок 2: токен бота, інтеграції

Найшвидший спосіб встановити BotVa на VPS -- через готовий веб-інсталятор:

https://botva-installer.onrender.com/

Інсталятор підключається до сервера по SSH, встановлює залежності, клонує репозиторій, створює першого бота та запускає систему. Підтримує Ubuntu 24.04 (DigitalOcean, Hetzner, будь-який VPS з 1 GB RAM).

Що потрібно:

1. Створити VPS (наприклад, дроплет на DigitalOcean)
2. Відкрити інсталятор, ввести IP-адресу та root-пароль
3. Вказати Telegram-токен від @BotFather та chat ID
4. Натиснути Install -- через 3-5 хвилин бот працює

Опціонально: домен для адмін-панелі (HTTPS через Cloudflare), Groq API Key (голосові повідомлення).

cd installer
npm install
npm start
# Відкриється http://localhost:3456

Docker

cd installer
docker build -t botva-installer .
docker run -p 3456:3456 botva-installer

Для деплою самого BotVa в Docker -- використовуйте веб-інсталятор або ручне встановлення на VPS.

Конфігурація

Кожен бот має свій .env файл в bots/<name>/.env. Шаблон: .env.example.

Обов'язкові

Google API

Голос

Моделі

Адмін-панель

Пам'ять

Agent

Rich messages та прогрес

Інтеграції

Email (SMTP)

Публікація файлів

Логування

Crash-нотифікації (кореневий .env)

Структура бота

bots/<name>/
├── .env                         # Токени та API-ключі
├── CLAUDE.md                    # Інструкції для AI (збирається з workspace-files/)
├── workspace-files/             # Модульні workspace файли
│   ├── IDENTITY.md              # Ім'я, emoji, опис ролі
│   ├── SOUL.md                  # Душа: правила, інструменти, стиль (read-only)
│   ├── ROLE.md                  # Спеціалізація, сценарії (read-only)
│   ├── TOOLS.md                 # Таблиця "коли який інструмент" (read-only)
│   ├── USER.md                  # Профіль користувача (бот оновлює)
│   └── MEMORY.md                # Курована пам'ять (бот оновлює)
├── knowledge/                   # Знання, профілі, diary
│   ├── user-profile.md          # Базовий профіль користувача
│   ├── KEY_EVENTS.md            # Важливі події
│   └── memories/                # Щоденні логи (YYYY-MM-DD.md)
└── store/
    └── botva.db                 # SQLite база (сесії, пам'ять, usage)

Що НЕ в git (потрібно копіювати вручну)

MCP-сервери

Збираються автоматично при ./scripts/deploy.sh setup. Конфігурація:

• Кореневий: .mcp.json (спільні MCP-сервери)
• Per-bot: bots/<name>/.mcp.json (специфічні для бота)

Вбудовані MCP-сервери в mcp-servers/:

• colleague -- міжботова комунікація (Unix-сокети)
• manager -- координація менеджером

Зовнішні (підключаються через env-змінні):

• google-workspace -- Calendar, Gmail, Drive
• home-assistant -- розумний дім
• stagehand -- AI-браузер
• playwright-remote -- headless Chrome
• miro -- дошки, діаграми

Управління

deploy.sh

./scripts/deploy.sh setup      # Встановити залежності, зібрати
./scripts/deploy.sh start      # Запустити всі боти
./scripts/deploy.sh stop       # Зупинити всі боти
./scripts/deploy.sh restart    # Перезапустити
./scripts/deploy.sh build      # Перезібрати TypeScript + MCP
./scripts/deploy.sh status     # Показати статус
./scripts/deploy.sh backup     # Створити бекап
./scripts/deploy.sh restore    # Відновити з бекапу

npm scripts

npm run build       # Зібрати TypeScript
npm start           # Запустити (після збірки)
npm run dev         # Dev-режим (tsx)
npm run admin       # Адмін-панель
npm run new-bot     # Створити бота
npm run delete-bot  # Видалити бота
npm run status      # Статус ботів
npm run typecheck   # Перевірка типів
npm test            # Тести

З Telegram

• /admin -- запустити адмін-панель (автостоп через 20 хв)
• /admin stop -- зупинити адмін-панель

Автозапуск

macOS (launchd)

./scripts/deploy.sh launchd

Створює LaunchAgent, який автоматично запускає ботів при старті системи.

Linux (systemd)

# Створити сервіс (виконується при ./scripts/deploy.sh setup на Linux)
sudo systemctl enable botva
sudo systemctl start botva

# Перевірити статус
sudo systemctl status botva

Бекап та відновлення

Що бекапити

tar czf botva-backup.tar.gz \
  bots/ \
  workspace/ \
  .mcp.json \
  .env

Ці файли НЕ зберігаються в git -- вони містять токени, персональні дані та бази.

Відновлення

cd BotVa
tar xzf botva-backup.tar.gz
./scripts/deploy.sh setup
./scripts/deploy.sh start

Також доступний бекап через адмін-панель (розділ Backup) з SHA256-верифікацією.

Міграція на інший сервер

1. На старому сервері: tar czf botva-backup.tar.gz bots/ workspace/ .mcp.json .env
2. На новому: клонуй репо, розпакуй бекап
3. ./scripts/deploy.sh setup && ./scripts/deploy.sh start