Skip to content

Getting Started

Follow this guide to get your own instance of ravenbot up and running.

📋 Prerequisites

Before you begin, ensure you have the following installed:

  • Docker & Docker Compose: Recommended for most users.
  • Go 1.25+: Only required if running locally (outside Docker).
  • templ: Required for local development (generates Go code from .templ templates). Install with go install github.com/a-h/templ/cmd/templ@latest.
  • Git: To clone the repository.
  • AI Backend:
    • Gemini: An API Key from Google AI Studio.
    • Ollama: A running Ollama instance (local or remote).

🚀 Quick Start (Docker)

The fastest way to deploy ravenbot is using Docker.

1. Clone the Repository

git clone https://github.com/raythurman2386/ravenbot.git
cd ravenbot

2. Configure Environment

Copy the example environment file and edit it with your credentials: 

cp .env.example .env
Open .env and at minimum set:

  • AI_BACKEND: gemini or ollama
  • GEMINI_API_KEY: Your Google AI key (if using Gemini)
  • BRAVE_API_KEY: Brave Search API key (required for web search)
  • TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID: For Telegram access (optional)
  • DISCORD_BOT_TOKEN / DISCORD_CHANNEL_ID: For Discord access (optional)

3. Build and Launch

docker compose up -d --build

The bot starts immediately. Access points:

  • Web UI: http://localhost:8080 — chat, reports, agents, missions, tools
  • Telegram: Send /help to your bot
  • Discord: Send /help in your configured channel

🛠 Local Development Setup

If you want to contribute or run without Docker:

  1. Install Go 1.25+: Required.
  2. Install templ: go install github.com/a-h/templ/cmd/templ@latest
  3. Download Dependencies: 
    go mod download
  4. Set Environment Variables: Export the same variables from .env to your shell.
  5. Build (generates templ + compiles): 
    make build
  6. Run: 
    ./ravenbot
# With debug logging:
LOG_LEVEL=debug ./ravenbot

The Web UI is available at http://localhost:8080 immediately after startup.

Development Commands

make check   # Full check: format, vet, lint, test (run before every commit)
make templ   # Regenerate Go code from .templ templates
make test    # Run tests
make fmt     # Format code
make cover   # Test with coverage report
make clean   # Remove build artifacts

📦 What's Next?

Once your bot is running, you might want to: