botbook/src/chapter-01/quick-start.md

# Quick Start

## Installation in 3 Steps

### 1. Run BotServer

```bash
./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 Drive...
   ✓ Object storage ready
   ✓ Buckets created
📦 Installing Cache...
   ✓ 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?

### Bootstrap Flow

<img src="../assets/chapter-01/quick-start-bootstrap.svg" alt="Bootstrap Flow" style="max-height: 400px; width: 100%; object-fit: contain;">

The **automatic bootstrap** process:

1. ✅ Detected your OS (Linux/macOS/Windows)
2. ✅ Downloaded PostgreSQL database to botserver-stack/
3. ✅ Downloaded drive (S3-compatible storage) to botserver-stack/
4. ✅ Downloaded cache component to botserver-stack/
5. ✅ Generated secure credentials → `.env` (from blank environment)
6. ✅ Created database schema
7. ✅ Deployed default bots to object storage
8. ✅ Started UI server on port 8080

**Zero manual configuration required!**

### Using Existing Services

If you already have PostgreSQL or drive storage running, update `.env`:

```bash
# Point to your existing services
DATABASE_URL=postgres://myuser:mypass@myhost:5432/mydb
DRIVE_SERVER=http://my-drive:9000
DRIVE_ACCESSKEY=my-access-key
DRIVE_SECRET=my-secret-key
```

---

## Step 2: Write a Simple Tool

### How Tools Work

<img src="../assets/chapter-01/tool-execution-flow.svg" alt="Tool Execution Flow" style="max-height: 400px; width: 100%; object-fit: contain;">

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

```bas
' Student enrollment tool
PARAM name, email, course
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!

---

## Step 3: 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 Deployment (LXC)

For production isolation, BotServer supports **LXC** (Linux Containers):

```bash
# Create container
lxc-create -n botserver -t download -- -d ubuntu -r jammy -a amd64

# Start and attach
lxc-start -n botserver
lxc-attach -n botserver

# Install BotServer inside container
./botserver
```

**Benefits**: 
- ✅ Process isolation
- ✅ Resource control
- ✅ Easy management
- ✅ Lightweight virtualization

---



## Optional Components

After installation, add more features:

```bash
./botserver install email      # Email server
./botserver install directory  # Identity provider
./botserver install llm        # Local LLM server (offline mode)
./botserver install meeting    # 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
```

Deploy new bots by uploading to object storage (creates a new bucket), not the local filesystem. The `work/` folder is for internal use only.

### Local Development with Auto-Sync

Edit bot files locally and sync automatically to drive storage:

**Free S3 Sync Tools:**
- **Cyberduck** - GUI file browser (Windows/Mac/Linux)
- **rclone** - Command-line sync (All platforms)
- **WinSCP** - File manager with S3 (Windows)
- **S3 Browser** - Freeware S3 client (Windows)

**Quick Setup with rclone:**
```bash
# Configure for drive storage
rclone config  # Follow prompts for S3-compatible storage

# Auto-sync local edits to bucket
rclone sync ./mybot.gbai drive:mybot --watch
```

Now when you:
- Edit `.csv` → Bot config reloads automatically
- Edit `.bas` → Scripts compile automatically
- Add docs to `.gbkb/` → Knowledge base updates

---

## 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)
```bas
' 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 automatically generates `.env` from a blank environment with secure random credentials:

```env
# Auto-generated during bootstrap
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`:

```csv
name,value
server_port,8080
llm-url,http://localhost:8081
episodic-memory-threshold,4
theme-color1,#0d2b55
```

---

## Troubleshooting

### Port 8080 in use?

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

```csv
name,value
server_port,3000
```

### Clean install?

```bash
# Remove everything and start fresh
rm -rf botserver-stack/
rm .env
./botserver  # Will regenerate everything
```

### Check component status

```bash
./botserver status tables    # PostgreSQL
./botserver status drive     # Drive storage
./botserver status cache     # Cache component
```

---

## Documentation

- **[Full Installation Guide](docs/src/chapter-01/installation.md)** - Detailed bootstrap explanation
- **[Tool Definition](docs/src/chapter-08/tool-definition.md)** - Creating tools
- **[BASIC Keywords](docs/src/chapter-05/keywords.md)** - Language reference
- **[Package System](docs/src/chapter-02/README.md)** - Creating bots
- **[Architecture](docs/src/chapter-06/architecture.md)** - How it works

---

## 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:**
   ```bas
   ' 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!** 🎉