Development Setup

Separation of Duties: See Separation of Duties - Getting started guides document onboarding. They do NOT own agent manifests, execution, or infrastructure configuration.

Complete guide to setting up your local development environment for the LLM Platform with DDEV and agent development with BuildKit CLI.

Prerequisites

Before starting, ensure you've met all System Requirements.

Quick verification:

# Check versions
php --version          # Should be 8.3+
node --version         # Should be v20.x+
composer --version     # Should be 2.6+
git --version          # Should be 2.40+
docker --version       # Should be 24.x+ or OrbStack
ddev version           # Should be 1.22+

# Check available disk space
df -h .                # Should have 20+ GB free

Installation Methods

Choose your preferred installation approach:

Option 1: DDEV Development (Recommended)

Best for Drupal development with automatic service orchestration.

Option 2: LLMCLI Infrastructure Management

Best for microservices development and custom infrastructure configurations.

Option 3: Manual Setup

Best for understanding the platform architecture and advanced customization.

Option 1: DDEV Development Setup (Recommended)

DDEV provides a complete, containerized Drupal development environment with one-command setup.

Step 1: Install DDEV

macOS:

brew install ddev/ddev/ddev

Linux (Ubuntu/Debian):

curl -fsSL https://raw.githubusercontent.com/ddev/ddev/master/scripts/install_ddev.sh | bash

Windows (WSL2):

# Inside WSL2 Ubuntu terminal
curl -fsSL https://raw.githubusercontent.com/ddev/ddev/master/scripts/install_ddev.sh | bash

Verify installation:

ddev version
# Should show v1.22.0 or higher

Step 2: Clone LLM Platform Repository

# Create workspace directory
mkdir -p ~/Sites/LLM
cd ~/Sites/LLM

# Clone platform repository
git clone git@gitlab.com:llm/demos/llm-platform-demo.git llm-platform
cd llm-platform

Note: If using HTTPS instead of SSH:

git clone https://gitlab.com/blueflyio/agent-platform/demos/llm-platform-demo.git llm-platform

Step 3: Install DDEV Addons

The platform includes custom DDEV addons for enhanced workflows:

# Install platform-specific addons (one-time setup)
./infrastructure/ddev-addons/install-addons.sh

This installs:

ddev tddai - AI-enhanced TDD commands
ddev ai - AI provider integration commands
ddev git-safe - Safe git operations with checks
ddev platform - Platform management commands
ddev qdrant - Vector database operations

Step 4: Start DDEV Environment

# Start DDEV containers
ddev start

# Check platform status
ddev platform status

Expected output:

Project:    llm-platform
Type:       drupal11
PHP:        8.3
Database:   PostgreSQL 15
URL:        https://llm-platform.ddev.site
Services:   web, db, redis, qdrant
Status:     Running

Step 5: Install Drupal Dependencies

# Install PHP dependencies via Composer
ddev composer install

# This may take 5-10 minutes on first run
# Composer will download ~200 MB of dependencies

Step 6: Import Drupal Configuration

# Import existing configuration
ddev drush cim -y

# Clear Drupal caches
ddev drush cr

Step 7: Access Your Development Site

Web Browser:

Platform URL: https://llm-platform.ddev.site
MailHog (email testing): https://llm-platform.ddev.site:8026
phpMyAdmin: https://llm-platform.ddev.site:8037

Default admin credentials:

Username: admin
Password: admin

Change admin password immediately:

ddev drush user:password admin "YourSecurePassword"

Step 8: Verify Service Connectivity

# Check database connection
ddev drush sql:cli --extra="SELECT version();"

# Check Redis connection
ddev exec redis-cli ping
# Should return: PONG

# Check Qdrant vector database
curl http://localhost:6333/health
# Should return: {"status":"ok"}

DDEV Daily Workflow

Starting your day:

cd ~/Sites/LLM/llm-platform
ddev start                    # Start all services
ddev platform status          # Verify everything is running

Common development commands:

# Drupal operations
ddev drush cr                 # Clear cache
ddev drush cex                # Export configuration
ddev drush cim -y             # Import configuration
ddev drush updb               # Run database updates

# Code quality
ddev tddai check web/modules/custom/   # Check coding standards
ddev tddai fix web/modules/custom/     # Auto-fix violations

# Git operations
ddev git-safe add .           # Stage changes with safety checks
ddev git-safe commit "message" # Commit with policy validation

# Testing
ddev phpunit web/modules/custom/llm/   # Run PHPUnit tests
ddev ai test providers        # Test AI integrations

Stopping for the day:

ddev stop                     # Stop services (preserves data)
# Or
ddev poweroff                 # Stop ALL DDEV projects

Option 2: LLMCLI Infrastructure Setup

For developers who want more control over individual services or are working on microservices.

Step 1: Install LLMCLI

npm install -g @bluefly/llmcli

Verify installation:

llmcli --version

Step 2: Configure Services

cd ~/Sites/LLM/llm-platform

# Start core services (databases, cache, search)
llmcli infra core

# This starts:
# - PostgreSQL (port 5432)
# - Redis (port 6379)
# - Qdrant (port 6333)
# - MongoDB (port 27017)

Verify core services:

llmcli infra status

# Expected output:
#  PostgreSQL    - Running (port 5432)
#  Redis         - Running (port 6379)
#  Qdrant        - Running (port 6333)
#  MongoDB       - Running (port 27017)

Step 3: Start AI Services

# Start AI Gateway, TDDAI, Ollama, LibreChat
llmcli infra ai

# This starts:
# - LLM Gateway (port 4000)
# - TDDAI service
# - Ollama (port 11434)
# - LibreChat (port 3000)

Step 4: Optional Monitoring Stack

# Start Prometheus, Grafana, Jaeger for observability
llmcli infra monitoring

# Access monitoring:
# - Grafana: http://localhost:3001 (admin/admin)
# - Prometheus: http://localhost:9090
# - Jaeger: http://localhost:16686

Step 5: Configure Drupal for LLMCLI

# Install Drupal dependencies
composer install

# Create local settings file
cp web/sites/default/default.settings.php web/sites/default/settings.php
chmod 644 web/sites/default/settings.php

# Edit web/sites/default/settings.php and add:

<?php
// Database configuration
$databases['default']['default'] = [
  'database' => 'llm_platform',
  'username' => 'llm_user',
  'password' => 'llm_password',
  'host' => 'localhost',
  'port' => '5432',
  'driver' => 'pgsql',
  'prefix' => '',
];

// Redis configuration
$settings['redis.connection']['interface'] = 'PhpRedis';
$settings['redis.connection']['host'] = 'localhost';
$settings['redis.connection']['port'] = '6379';
$settings['cache']['default'] = 'cache.backend.redis';

Step 6: Install Drupal Site

# Install Drupal via Drush
./vendor/bin/drush site:install standard \
  --db-url=pgsql://llm_user:llm_password@localhost:5432/llm_platform \
  --site-name="LLM Platform" \
  --account-name=admin \
  --account-pass=admin \
  -y

# Import configuration
./vendor/bin/drush cim -y

# Clear cache
./vendor/bin/drush cr

Step 7: Start PHP Development Server

# Option 1: PHP built-in server
php -S localhost:8080 -t web

# Option 2: Use Symfony CLI
symfony server:start -d --port=8080

Access site:

Platform: http://localhost:8080

Option 3: Manual Setup

For advanced users who want complete control.

Database Setup

PostgreSQL:

# macOS (using Homebrew)
brew install postgresql@15
brew services start postgresql@15

# Create database and user
createuser -P llm_user      # Enter password when prompted
createdb -O llm_user llm_platform

# Linux (Ubuntu)
sudo apt install postgresql-15
sudo systemctl start postgresql
sudo -u postgres createuser -P llm_user
sudo -u postgres createdb -O llm_user llm_platform

Redis Setup

# macOS
brew install redis
brew services start redis

# Linux (Ubuntu)
sudo apt install redis-server
sudo systemctl start redis-server

Qdrant Vector Database

# Using Docker
docker run -d -p 6333:6333 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant:v1.7.4

# Verify
curl http://localhost:6333/health

Web Server Setup

Apache (macOS):

brew install httpd
brew services start httpd

# Configure virtual host in /opt/homebrew/etc/httpd/httpd.conf
# Point DocumentRoot to ~/Sites/LLM/llm-platform/web

Nginx:

# Install
brew install nginx   # macOS
# or
sudo apt install nginx   # Linux

# Configure site
# See: $LLM_ROOT/llm-platform/infrastructure/nginx.conf.example

BuildKit CLI Setup

BuildKit CLI is essential for OSSA agent development and workflow automation.

Step 1: Install BuildKit Globally

# Install from npm
npm install -g @bluefly/agent-buildkit

# Verify installation
buildkit --version

Expected output:

buildkit version 0.1.2

Step 2: Configure GitLab Integration

# Set up GitLab authentication
export GITLAB_URL="https://gitlab.com"
export GITLAB_TOKEN="your-personal-access-token"

# Persist in shell profile (~/.zshrc or ~/.bashrc)
echo 'export GITLAB_URL="https://gitlab.com"' >> ~/.zshrc
echo 'export GITLAB_TOKEN="your-personal-access-token"' >> ~/.zshrc
source ~/.zshrc

Get your GitLab token:

Visit: https://gitlab.com/-/user_settings/personal_access_tokens
Create token with scopes: api, read_api, read_registry, write_registry
Copy token and save to ~/.tokens/gitlab

mkdir -p ~/.tokens
echo "your-token-here" > ~/.tokens/gitlab
chmod 600 ~/.tokens/gitlab

Step 3: Initialize BuildKit Project

cd ~/Sites/LLM/llm-platform

# Initialize BuildKit configuration
buildkit init

# This creates:
# - .buildkit/config.yml
# - .buildkit/agents/
# - .buildkit/workflows/

Step 4: Verify BuildKit Commands

# Test core commands
buildkit agents list         # List available agents
buildkit ossa validate      # Validate OSSA manifests
buildkit golden --help      # Show golden commands

# Test GitLab integration
buildkit gitlab issues list --project llm/demos/llm-platform-demo

OSSA CLI Setup

OSSA CLI provides validation and scaffolding for OSSA-compliant agents.

Install OSSA CLI

# Install globally
npm install -g @bluefly/openstandardagents

# Verify
ossa --version

Create Your First OSSA Agent

# Generate agent scaffold
ossa generate worker --name "Test Agent" --id test-agent

# This creates:
# - agent.ossa.yaml (OSSA manifest)
# - src/index.ts (agent implementation)
# - README.md

# Validate manifest
ossa validate agent.ossa.yaml

Expected output:

 OSSA manifest is valid
  Agent ID: test-agent
  Agent Type: worker
  OSSA Version: 0.2.4

Environment Configuration

Environment Variables

Create .env file in project root:

# Copy example environment file
cp .env.example .env

# Edit .env with your configuration
nano .env

Essential variables:

# Database
DATABASE_URL="postgresql://llm_user:llm_password@localhost:5432/llm_platform"

# Redis
REDIS_HOST="localhost"
REDIS_PORT="6379"

# Qdrant
QDRANT_URL="http://localhost:6333"

# LLM Gateway
LLM_GATEWAY_URL="http://localhost:4000/api/v1"

# GitLab
GITLAB_URL="https://gitlab.com"
GITLAB_TOKEN="see ~/.tokens/gitlab"

# AI Providers (optional)
OPENAI_API_KEY="sk-..."
ANTHROPIC_API_KEY="sk-ant-..."

Token Management

Store all API tokens securely:

mkdir -p ~/.tokens

# GitLab token
echo "your-gitlab-token" > ~/.tokens/gitlab

# OpenAI token (optional)
echo "sk-your-openai-key" > ~/.tokens/openai

# Anthropic token (optional)
echo "sk-ant-your-anthropic-key" > ~/.tokens/anthropic

# Secure permissions
chmod 600 ~/.tokens/*

Development Workspace Structure

Organize your development workspace:

~/Sites/LLM/
 llm-platform/              # Main Drupal platform
 all_drupal_custom/         # Custom module source
    modules/
    themes/
    recipes/
 agent-buildkit/            # BuildKit CLI source
 openstandardagents/        # OSSA specification
 llm-platform-worktrees/    # Git worktrees for feature branches

Create workspace:

mkdir -p ~/Sites/LLM/{llm-platform,all_drupal_custom/{modules,themes,recipes},llm-platform-worktrees}

IDE Configuration

VS Code

Recommended extensions:

{
  "recommendations": [
    "bmewburn.vscode-intelephense-client",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "redhat.vscode-yaml",
    "ms-azuretools.vscode-docker",
    "drupal.drupal",
    "neilbrayfield.php-docblocker"
  ]
}

Save to .vscode/extensions.json in project root.

Workspace settings:

{
  "php.validate.executablePath": "/opt/homebrew/bin/php",
  "php.suggest.basic": false,
  "intelephense.stubs": [
    "apache",
    "bcmath",
    "Core",
    "ctype",
    "curl",
    "date",
    "dom",
    "fileinfo",
    "filter",
    "gd",
    "hash",
    "iconv",
    "json",
    "libxml",
    "mbstring",
    "mysqli",
    "openssl",
    "pcre",
    "PDO",
    "pdo_mysql",
    "Phar",
    "Reflection",
    "session",
    "SimpleXML",
    "SPL",
    "standard",
    "tokenizer",
    "xml",
    "xmlreader",
    "xmlwriter",
    "zip",
    "zlib"
  ],
  "intelephense.environment.phpVersion": "8.3.0",
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[php]": {
    "editor.defaultFormatter": "bmewburn.vscode-intelephense-client"
  }
}

Save to .vscode/settings.json.

PHPStorm

Configuration:

Open Settings PHP
Set CLI Interpreter: /opt/homebrew/bin/php (macOS) or /usr/bin/php8.3 (Linux)
Enable Composer: Point to composer.phar or global composer
Enable Drupal support: Languages & Frameworks PHP Drupal Enable
Set Drupal installation path: web/

Verify Installation

Run comprehensive verification:

# DDEV verification
ddev platform status

# Database connection
ddev drush sql:cli --extra="SELECT 'Database OK' as status;"

# Redis connection
ddev exec redis-cli ping

# Qdrant health
curl http://localhost:6333/health

# Drupal site status
ddev drush status

# BuildKit CLI
buildkit agents list

# OSSA CLI
ossa --version

# Run basic tests
ddev phpunit web/modules/custom/llm/tests/

All green? You're ready to develop!

Troubleshooting

DDEV Won't Start

# Check Docker/OrbStack is running
docker ps

# Remove corrupted DDEV state
ddev delete -O
ddev start

# Check logs
ddev logs

Composer Install Fails

# Clear Composer cache
ddev composer clear-cache

# Update Composer
ddev composer self-update

# Retry installation
ddev composer install --no-cache

Database Connection Issues

# Check database is running
ddev describe

# Recreate database
ddev delete -O
ddev start
ddev drush site:install standard --db-url=...

Port Conflicts

# Check what's using port 8080
lsof -i :8080

# Stop conflicting service
kill -9 $(lsof -t -i:8080)

# Or use DDEV router
ddev config --router-http-port=8888 --router-https-port=8889

BuildKit Command Not Found

# Reinstall globally
npm uninstall -g @bluefly/agent-buildkit
npm install -g @bluefly/agent-buildkit

# Check npm global path
npm config get prefix
# Should be in your PATH
echo $PATH | grep $(npm config get prefix)

Next Steps

Now that your development environment is set up:

Create your first agent: Your First Agent
Build a workflow: Your First Workflow
Deploy to production: Production Deployment
Learn common pitfalls: Common Pitfalls

Development Setup

Development Setup

Prerequisites

Installation Methods

Option 1: DDEV Development (Recommended)

Option 2: LLMCLI Infrastructure Management

Option 3: Manual Setup

Option 1: DDEV Development Setup (Recommended)

Step 1: Install DDEV

Step 2: Clone LLM Platform Repository

Step 3: Install DDEV Addons

Step 4: Start DDEV Environment

Step 5: Install Drupal Dependencies

Step 6: Import Drupal Configuration

Step 7: Access Your Development Site

Step 8: Verify Service Connectivity

DDEV Daily Workflow

Option 2: LLMCLI Infrastructure Setup

Step 1: Install LLMCLI

Step 2: Configure Services

Step 3: Start AI Services

Step 4: Optional Monitoring Stack

Step 5: Configure Drupal for LLMCLI

Step 6: Install Drupal Site

Step 7: Start PHP Development Server

Option 3: Manual Setup

Database Setup

Redis Setup

Qdrant Vector Database

Web Server Setup

BuildKit CLI Setup

Step 1: Install BuildKit Globally

Step 2: Configure GitLab Integration

Step 3: Initialize BuildKit Project

Step 4: Verify BuildKit Commands

OSSA CLI Setup

Install OSSA CLI

Create Your First OSSA Agent

Environment Configuration

Environment Variables

Token Management

Development Workspace Structure

IDE Configuration

VS Code

PHPStorm

Verify Installation

Troubleshooting

DDEV Won't Start

Composer Install Fails

Database Connection Issues

Port Conflicts

BuildKit Command Not Found

Next Steps

Additional Resources