Installation Guide

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

📜 Step-by-Step Guide

🐳 Quick Start: Docker (recommended)

Requirements: Docker and Docker Compose

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

Useful commands:

docker compose down        # Stop
docker compose build --no-cache  # Rebuild
docker compose logs -f     # Logs

✅ Done! App available at: http://localhost:5000

---

Manual Installation

Requirements

• Node.js ≥ 18.0.0
• PostgreSQL ≥ 17
• Redis ≥ 7
• Python ≥ 3.10 (3.13 recommended, for generated bots)
• Git

Step 1: Install Git

🐧 Linux (Ubuntu/Debian)	🏁 Windows	🍎 macOS
Option 1: Via terminal (recommended): Ubuntu/Debian: sudo apt update && sudo apt install -y git Fedora/CentOS: sudo dnf install -y git Arch Linux: sudo pacman -S git Option 2: From website: Go to git-scm.com/install/linux Select your distribution Follow the installation instructions Verify installation: git --version	Option 1: Via winget (recommended): winget install --id Git.Git -e --source winget Option 2: Via installer: Download from git-scm.com/install/windows Run the .exe file Keep default settings (click "Next") Verify installation: Open PowerShell as administrator (Win + X → "Terminal (Admin)"): git --version If the version is not displayed, restart PowerShell	Option 1: Via Homebrew (recommended): # Install Homebrew (if not installed) /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Install Git brew install git Option 2: From website: Go to git-scm.com/install/mac Download the macOS installer (.dmg) Open the .dmg file and drag Git to Applications Verify installation: git --version Homebrew is a package manager for macOS that simplifies software installation

---

Step 2: Install Node.js LTS

🐧 Linux	🏁 Windows	🍎 macOS
Option 1: Via terminal (recommended): curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt install -y nodejs node -v && npm -v Option 2: From website: Go to nodejs.org Download the .deb or .rpm package Install: sudo dpkg -i nodejs_*.deb	Option 1: Via winget: winget install OpenJS.NodeJS.LTS node -v && npm -v Option 2: From website: Go to nodejs.org Download the installer (.msi) Run and follow the instructions Verify installation: node -v npm -v	Option 1: Via Homebrew: brew install node@lts node -v && npm -v Option 2: From website: Go to nodejs.org Download the installer (.pkg) Run and follow the instructions

---

Step 3: Install PostgreSQL

🐧 Linux	🏁 Windows	🍎 macOS
Option 1: Via terminal: sudo apt install -y postgresql postgresql-contrib sudo systemctl enable postgresql sudo systemctl start postgresql Option 2: Official repository: Visit postgresql.org/download/linux Select your distribution Follow the instructions	Option 1: Via winget (recommended): winget install PostgreSQL.PostgreSQL.17 During installation, remember the password for the postgres user (default: postgres). Port: 5432. Verify installation: psql -U postgres -c "SELECT version();" Option 2: From website: Go to postgresql.org/download/windows Download the installer Run and remember the postgres password	Option 1: Via Homebrew: brew install postgresql@15 brew services start postgresql@15 Option 2: From website: Go to postgresql.org/download/macosx Download the installer Run and follow the instructions

---

Step 4: Install Python 3

🐧 Linux	🏁 Windows	🍎 macOS
Option 1: Via terminal: sudo apt install -y python3 python3-venv python3-pip python3 --version Option 2: Official website: Visit python.org/downloads Select the version for Linux Follow the compilation instructions	Option 1: Via winget: winget install Python.Python.3.12 Option 2: From website: Go to python.org/downloads Download the installer During installation, check "Add Python to PATH" Verify installation: python --version	Option 1: Via Homebrew: brew install python python3 --version Option 2: From website: Go to python.org/downloads Download the macOS installer (.pkg) Run and follow the instructions

---

Step 5: Install Redis

🐧 Linux (Ubuntu/Debian)	🏁 Windows	🍎 macOS
Option 1: Via terminal: sudo apt install -y redis-server sudo systemctl enable redis-server sudo systemctl start redis-server Verify installation: redis-cli ping Should respond with PONG	Option 1: Memurai (recommended for Windows): Memurai is a native Windows port, fully compatible with Redis 7.2+. It installs as a Windows service and works without WSL. winget install Memurai.MemuraiDeveloper After installation, the service starts automatically. Management: net start Memurai # Start net stop Memurai # Stop Option 2: Via WSL2: Install Redis inside WSL: sudo apt install -y redis-server sudo service redis-server start Option 3: Docker: docker run -d --name redis -p 6379:6379 redis:alpine Verify installation: redis-cli ping Should respond with PONG	Option 1: Via Homebrew: brew install redis brew services start redis Verify installation: redis-cli ping Should respond with PONG

---

Step 6: Database Setup

🐧 Linux	🏁 Windows	🍎 macOS
sudo -u postgres psql CREATE DATABASE telegram_bot_builder; GRANT ALL PRIVILEGES ON DATABASE telegram_bot_builder TO postgres; \q By default, the built-in postgres user is used. The password is set during PostgreSQL installation.	psql -U postgres CREATE DATABASE telegram_bot_builder; GRANT ALL PRIVILEGES ON DATABASE telegram_bot_builder TO postgres; \q The postgres password is set during installation. If you forgot it, reinstall or change it via ALTER USER postgres PASSWORD 'new_password';	psql postgres CREATE DATABASE telegram_bot_builder; GRANT ALL PRIVILEGES ON DATABASE telegram_bot_builder TO postgres; \q On macOS, the postgres user is usually created without a password when installed via Homebrew.

---

Step 7: Clone the Project

🐧 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

---

Step 8: Environment Setup

1. Copy the template:

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

2. Minimal variables for local development:

NODE_ENV=development
PORT=5000

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

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

# Session signing secret
SESSION_SECRET=any-random-string-for-local

# Admin panel and OpenAPI docs login key
ADMIN_API_KEY=any-random-string-for-local

🔐 SESSION_SECRET is mandatory in production. In development you may use any string (or omit it entirely — a dev fallback with a warning is used). But in NODE_ENV=production the app intentionally refuses to start if SESSION_SECRET is missing: without it anyone could forge a session cookie and log in as another user. Generate a strong random value:

# Linux/macOS (or Git Bash on Windows)
openssl rand -hex 32
# Any OS with Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Changing SESSION_SECRET invalidates all active sessions — users will need to log in again.

🔑 ADMIN_API_KEY is required in production for the admin panel and protected OpenAPI docs. In development you may omit it — the insecure dev fallback dev-only-insecure-admin-key is used (with a log warning). In production without ADMIN_API_KEY, /admin and /admin/docs are not mounted. Generate a separate value the same way as SESSION_SECRET.

📖 API documentation:

Mode	URL	Access
Development	http://localhost:5000/docs	Public (for local work)
Development	http://localhost:5000/admin	Key from ADMIN_API_KEY (or dev fallback)
Production	https://your-domain/admin/login	ADMIN_API_KEY only
Production	https://your-domain/admin/docs	After login: Swagger, Scalar, Redoc, RapiDoc

OpenAPI spec: /docs-json (dev) or /admin/openapi.json (prod, after login).

💡 Telegram Login is configured via Setup Wizard on first launch — no manual setup needed.

---

Step 9: Install Dependencies and Run

1. Install Node.js dependencies:

npm install

2. Install Python dependencies (for running bots):

pip install -r requirements.txt

3. Run the application:

Mode	Command	Description
🧪 Development	npm run dev	Run with auto-reload on changes
🚀 Production	npm run build → npm run start	Build and run the production version

✅ Done! App available at: http://localhost:5000

After startup you also have:

• Editor: http://localhost:5000
• OpenAPI (dev): http://localhost:5000/docs — UI hub
• Admin: http://localhost:5000/admin/login — key from ADMIN_API_KEY (or dev-only-insecure-admin-key if unset)

---

Step 10: Telegram Login Setup (Setup Wizard)

⚠️ For local development (NODE_ENV=development) this step is optional — the app works without authentication. Setup Wizard is only needed for production deployment.

On first launch in production, the Setup Wizard will appear — it will ask you to enter credentials for Telegram authentication.

How to get credentials from BotFather:

1. Open @BotFather → select your bot → Bot Settings → Login Widget

2. Switch to OIDC:

3. Confirm the switch:

4. Copy the Client ID and Client Secret:

5. Set the Redirect URIs (your application address):

For local development: http://localhost:5000

6. Enter the obtained credentials in the Setup Wizard:

• Client ID — numeric ID
• Client Secret — secret key
• Bot Username — bot name without @

✅ After saving, the application is ready to use!

---

Step 11: Connect an AI agent via MCP (optional)

💡 You only need this step if you want to connect an AI agent (Kiro / Cursor / Claude Desktop) to edit bots on the canvas in real time. It is not required for normal use.

The MCP agent is identified by a personal access token (PAT) — like a GitHub/n8n API key. The token is tied to your account and grants access only to your own projects.

1. Open a project → "Agent" tab → "Create token" button.

2. Set a name (e.g. "Kiro on laptop") → "Create".

3. The full mcp_… token is shown exactly once — copy it immediately. Only an sha-256 hash is stored in the database; the secret is never shown again.

4. Copy the ready-made snippet — default is Remote URL (no repo clone). Paste into your MCP client config:

{
  "mcpServers": {
    "botcraft-builder": {
      "url": "https://<your-domain>/mcp",
      "headers": {
        "Authorization": "Bearer mcp_..."
      }
    }
  }
}

For local development (repo clone required), the Agent tab also has a Stdio snippet:

{
  "mcpServers": {
    "botcraft-builder": {
      "command": "npm",
      "args": ["run", "mcp:bot-builder"],
      "cwd": "<path to project directory>",
      "env": {
        "API_BASE_URL": "http://localhost:5000",
        "MCP_AGENT_TOKEN": "mcp_..."
      }
    }
  }
}

• Remote details: docs/mcp/remote-http.md.
• Treat the Bearer / MCP_AGENT_TOKEN like a password; never commit it.
• You can revoke the token instantly on the Agent tab.
• Server flag: MCP_HTTP_ENABLED (enabled by default).

💡 Need to update the project? See 🔄 How to Update from GitHub

---