Skip to content

Development Guide

Jump to bottom
mrveiss edited this page Apr 14, 2026 · 1 revision

Development Guide

Prerequisites

  • Docker 24.0+ and Docker Compose v2
  • Python 3.11+ (for backend development without Docker)
  • Node.js 20+ (for frontend development without Docker)
  • Git

Dev Environment Setup

Quick Start (Docker)

git clone https://github.com/mrveiss/AutoBot-AI.git
cd AutoBot-AI
cp .env.example .env

# Start dev stack with hot reload
docker compose -f docker-compose.dev.yml up -d

# Watch logs
docker compose -f docker-compose.dev.yml logs -f

The dev compose mounts source directories so changes trigger hot reload without rebuilding containers.

Backend Only (Local Python)

cd autobot-backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Start dependencies via Docker, backend locally
docker compose up -d autobot-database redis chromadb

# Run backend
uvicorn app_factory:create_app --factory --reload --port 8000

Frontend Only (Local Node)

cd autobot-frontend
npm install

# Start with hot reload
npm run dev

Frontend dev server proxies API calls to http://localhost:8000 by default.

Repository Structure

AutoBot-AI/
├── autobot-backend/        # FastAPI application
│   ├── api/                # Route handlers
│   ├── agents/             # AI agent definitions
│   ├── agent_loop/         # Conversation management
│   └── app_factory.py      # App factory / entrypoint
├── autobot-frontend/       # Vue.js application
│   ├── src/
│   │   ├── components/     # UI components
│   │   ├── views/          # Page views
│   │   └── stores/         # Pinia state stores
├── autobot-database/       # DB migrations (Alembic)
├── autobot-infrastructure/ # Ansible playbooks
├── autobot-browser-worker/ # Chromium automation
├── autobot-ai-stack/       # Ollama config and model management
└── autobot/                # Shared utilities

Running Tests

Backend Tests

cd autobot-backend

# Unit tests
python -m pytest

# With coverage
python -m pytest --cov=. --cov-report=html

# Specific test file
python -m pytest api/test_chat.py -v

# Integration tests (requires running dependencies)
docker compose up -d autobot-database redis chromadb
python -m pytest -m integration

Frontend Tests

cd autobot-frontend

# Unit tests
npm run test:unit

# E2E tests (requires running backend)
npm run test:e2e

# Cypress interactive
npx cypress open

Git Workflow

Branch Naming

feature/short-description     # New features
fix/short-description         # Bug fixes
docs/short-description        # Documentation only
ci/short-description          # CI/CD changes
refactor/short-description    # Refactoring

Commit Message Format

type(scope): short description

# Types: feat, fix, docs, ci, refactor, test, chore
# Examples:
feat(chat): add streaming response support
fix(fleet): handle SSH timeout on slow nodes
docs(api): add knowledge base endpoint examples

Pull Request Process

  1. Fork the repo and create a branch from Dev_new_gui
  2. Make your changes with tests
  3. Ensure all tests pass: python -m pytest / npm run test:unit
  4. Open a PR targeting Dev_new_gui (not main)
  5. Fill out the PR template
  6. Request review

Code Style

Python (Backend)

  • Formatter: black
  • Linter: ruff
  • Type hints required for all new functions
  • Async functions preferred for I/O
# Format
black autobot-backend/

# Lint
ruff check autobot-backend/

TypeScript/JavaScript (Frontend)

  • Formatter: Prettier
  • Linter: ESLint
  • Composition API (not Options API)
cd autobot-frontend
npm run lint
npm run format

Environment Variables

Copy .env.example to .env and adjust as needed. Key variables:

Variable Description Default
AUTOBOT_SECRET_KEY JWT signing key (required)
POSTGRES_PASSWORD Database password autobot
OLLAMA_MODEL Default AI model llama3
CHROMA_HOST ChromaDB host chromadb

See Configuration Reference for the full list.

Database Migrations

AutoBot uses Alembic for schema migrations.

cd autobot-database

# Apply all migrations
alembic upgrade head

# Create a new migration
alembic revision --autogenerate -m "add column to nodes table"

# Downgrade one step
alembic downgrade -1

Adding a New API Endpoint

  1. Create a new route file in autobot-backend/api/ (or add to an existing one)
  2. Register the router in app_factory.py
  3. Add tests in the same directory (test_<name>.py)
  4. Update API Documentation wiki page

Useful Make Commands

make up           # Start all services
make down         # Stop all services
make test         # Run all tests
make lint         # Lint all code
make format       # Format all code
make logs         # Tail all service logs
make shell        # Open bash in backend container

Getting Help

Clone this wiki locally