GeneralBots/botserver
2
1
Fork 0
Code Issues Pull requests Projects Releases 323 Packages Wiki Activity Actions
botserver/docs/QUICK_START.md

6.9 KiB
Raw Blame History

BotServer Quick Start

Installation in 3 Steps

1. Run BotServer

./botserver

That's it! No configuration needed.

2. Wait for Bootstrap (2-5 minutes)

You'll see:

🚀 BotServer starting...
📦 Bootstrap: Detecting system...
📦 Installing PostgreSQL...
   ✓ Database created
   ✓ Schema initialized
   ✓ Credentials saved to .env
📦 Installing MinIO...
   ✓ Object storage ready
   ✓ Buckets created
📦 Installing Valkey...
   ✓ Cache server running
🤖 Creating bots from templates...
   ✓ default.gbai → Default bot
   ✓ announcements.gbai → Announcements bot
✅ BotServer ready at http://localhost:8080

3. Open Browser

http://localhost:8080

Start chatting with your bot!

What Just Happened?

The automatic bootstrap process:

  1. ✅ Detected your OS (Linux/macOS/Windows)
  2. ✅ Installed PostgreSQL database
  3. ✅ Installed MinIO object storage
  4. ✅ Installed Valkey cache
  5. ✅ Generated secure credentials → .env
  6. ✅ Created database schema
  7. ✅ Created default bots from templates/
  8. ✅ Started web server on port 8080

Zero manual configuration required!

Create Your First Tool

Tools are just .bas files. Create enrollment.bas:

' Student enrollment tool
PARAM name AS string    LIKE "John Smith"        DESCRIPTION "Student name"
PARAM email AS string   LIKE "john@example.com"  DESCRIPTION "Email address"
PARAM course AS string  LIKE "Computer Science"  DESCRIPTION "Course to enroll"

DESCRIPTION "Processes student enrollment"

SAVE "enrollments.csv", name, email, course, NOW()
TALK "Welcome to " + course + ", " + name + "!"

The LLM automatically discovers this tool and knows when to call it!

Add Knowledge Base

Drop documents in a .gbkb/ folder:

mybot.gbai/
  mybot.gbkb/
    docs/
      manual.pdf
      faq.docx
      guide.txt

The bot automatically:

  • Indexes documents with vector embeddings
  • Answers questions from the content
  • Updates when files change

Container Mode (LXC)

BotServer uses LXC (Linux Containers) for containerized deployment:

# Force container mode
./botserver --container

# Components run in isolated LXC containers
# - PostgreSQL in {tenant}-tables container
# - MinIO in {tenant}-drive container
# - Valkey in {tenant}-cache container

Benefits:

  • ✅ Clean isolation - system-level containers
  • ✅ Easy cleanup - lxc delete {container}
  • ✅ No system pollution - everything in containers
  • ✅ Lightweight - more efficient than VMs

Requires: LXC/LXD installed (sudo snap install lxd)

Build from Source

git clone https://github.com/GeneralBots/BotServer.git
cd BotServer
cargo run

Same automatic bootstrap process!

Optional Components

After installation, add more features:

./botserver install email      # Stalwart email server
./botserver install directory  # Zitadel identity provider
./botserver install llm        # Local LLM server (offline mode)
./botserver install meeting    # LiveKit video conferencing

Example Bot Structure

mybot.gbai/
├── mybot.gbdialog/          # Dialog scripts
│   ├── start.bas            # Entry point (required)
│   ├── get-weather.bas      # Tool (auto-discovered)
│   └── send-email.bas       # Tool (auto-discovered)
├── mybot.gbkb/              # Knowledge base
│   ├── docs/                # Document collection
│   └── faq/                 # FAQ collection
├── mybot.gbot/              # Configuration
│   └── config.csv           # Bot parameters
└── mybot.gbtheme/           # UI theme (optional)
    └── custom.css

Save to templates/mybot.gbai/ and restart - bot created automatically!

How It Really Works

You DON'T write complex dialog flows. Instead:

1. Add Documents

mybot.gbkb/
  policies/enrollment-policy.pdf
  catalog/courses.pdf

2. Create Tools (Optional)

' enrollment.bas - just define what it does
PARAM name AS string
PARAM course AS string
SAVE "enrollments.csv", name, course

3. Start Chatting!

User: I want to enroll in computer science
Bot: I'll help you enroll! What's your name?
User: John Smith
Bot: [Automatically calls enrollment.bas with collected params]
     Welcome to Computer Science, John Smith!

The LLM handles ALL conversation logic automatically!

Configuration (Optional)

Bootstrap creates .env automatically:

DATABASE_URL=postgres://gbuser:RANDOM_PASS@localhost:5432/botserver
DRIVE_SERVER=http://localhost:9000
DRIVE_ACCESSKEY=GENERATED_KEY
DRIVE_SECRET=GENERATED_SECRET

You can also configure per-bot settings in config.csv:

name,value
server_port,8080
llm-url,http://localhost:8081
prompt-compact,4
theme-color1,#0d2b55

Troubleshooting

Port 8080 in use?

Edit templates/default.gbai/default.gbot/config.csv:

name,value
server_port,3000

Clean install?

# Remove everything and start fresh
rm -rf /opt/gbo  # Linux/macOS
./botserver

Check component status

./botserver status tables    # PostgreSQL
./botserver status drive     # MinIO
./botserver status cache     # Valkey

Documentation

The Magic Formula

📚 Documents + 🔧 Tools + 🤖 LLM = ✨ Intelligent Bot

What You DON'T Need:

  • ❌ IF/THEN logic
  • ❌ Intent detection
  • ❌ Dialog flow charts
  • ❌ State machines
  • ❌ Complex routing

What You DO:

  • ✅ Drop documents in .gbkb/
  • ✅ Create simple .bas tools (optional)
  • ✅ Start chatting!

The LLM understands context, calls tools, searches documents, and maintains conversation naturally.

Philosophy

  1. Just Run It - No manual configuration
  2. Simple Scripts - BASIC-like language anyone can learn
  3. Automatic Discovery - Tools and KBs auto-detected
  4. Secure by Default - Credentials auto-generated
  5. Production Ready - Built for real-world use

Real Example: Education Bot

  1. Add course materials:

    edu.gbkb/
  courses/computer-science.pdf
  policies/enrollment.pdf

  2. Create enrollment tool:

    ' enrollment.bas
PARAM name AS string
PARAM course AS string
SAVE "enrollments.csv", name, course

  3. Just chat:

    User: What courses do you offer?
Bot: [Searches PDFs] We offer Computer Science, Data Science...

User: I want to enroll
Bot: [Calls enrollment.bas] Let me help you enroll...

No programming logic needed - the LLM handles everything! 🎉