Development Setup
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.bluefly.io:llm/demos/llm-platform-demo.git llm-platform
cd llm-platform
Note: If using HTTPS instead of SSH:
git clone https://gitlab.bluefly.io/llm/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: /Users/flux423/Sites/LLM/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.bluefly.io"
export GITLAB_TOKEN="your-personal-access-token"
# Persist in shell profile (~/.zshrc or ~/.bashrc)
echo 'export GITLAB_URL="https://gitlab.bluefly.io"' >> ~/.zshrc
echo 'export GITLAB_TOKEN="your-personal-access-token"' >> ~/.zshrc
source ~/.zshrc
Get your GitLab token:
1. Visit: https://gitlab.bluefly.io/-/user_settings/personal_access_tokens
2. Create token with scopes: api, read_api, read_registry, write_registry
3. 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.bluefly.io"
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:
1. Open Settings → PHP
2. Set CLI Interpreter: /opt/homebrew/bin/php (macOS) or /usr/bin/php8.3 (Linux)
3. Enable Composer: Point to composer.phar or global composer
4. Enable Drupal support: Languages & Frameworks → PHP → Drupal → Enable
5. 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