Skip to main content

DDEV Development Environment

DDEV Development Environment

Local development setup and workflow for the LLM Platform

Overview

DDEV provides a containerized development environment for the LLM Platform, enabling rapid local development with all services pre-configured and ready to use.

Technology: Docker, DDEV URL: https://llm-platform.ddev.site Prerequisites: Docker Desktop, DDEV

Quick Start

# Navigate to platform
cd $LLM_ROOT/llm-platform

# Start DDEV
ddev start

# Check status
ddev platform status

# Access platform
open https://llm-platform.ddev.site

Installation

Prerequisites

# Install Docker Desktop
# Download from: https://www.docker.com/products/docker-desktop

# Install DDEV
brew install ddev/ddev/ddev

# Verify installation
ddev version
docker --version

First-Time Setup

# 1. Clone repository
git clone git@gitlab.com:bluefly/llm-platform.git
cd llm-platform

# 2. Install DDEV addons (one-time)
./infrastructure/ddev-addons/install-addons.sh

# 3. Start DDEV
ddev start

# 4. Install dependencies
ddev composer install

# 5. Import configuration
ddev drush cim -y

# 6. Clear cache
ddev drush cr

# 7. Access platform
open https://llm-platform.ddev.site

DDEV Configuration

.ddev/config.yaml

name: llm-platform
type: drupal10
docroot: web
php_version: "8.3"
webserver_type: nginx-fpm
router_http_port: "80"
router_https_port: "443"
xdebug_enabled: false
additional_hostnames:
  - api.llm-platform.ddev.site
  - mcp.llm-platform.ddev.site
additional_fqdns: []
mariadb_version: "10.11"
mysql_version: ""
use_dns_when_possible: true
composer_version: "2"
web_environment:
  - DRUPAL_HASH_SALT=random-hash-salt
  - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
  - OPENAI_API_KEY=${OPENAI_API_KEY}

Custom Commands

DDEV provides custom commands for the LLM Platform:

# Platform management
ddev platform status           # Check all services
ddev platform deploy local     # Deploy locally
ddev platform logs             # View logs

# AI operations
ddev ai test providers         # Test AI integrations
ddev ai chat                   # Interactive AI chat

# TDD operations
ddev tddai check web/modules/custom/  # Check code standards
ddev tddai fix web/modules/custom/    # Auto-fix violations

# Git operations
ddev git-safe commit "message"       # Safe commit with checks
ddev git-safe push                   # Safe push with validation

# Qdrant operations
ddev qdrant collections list         # List collections
ddev qdrant search documents "query" # Search vectors

# LLM operations
ddev llm complete "prompt"           # LLM completion
ddev llm chat                        # Chat interface

Service Configuration

Core Services

All services are automatically started with DDEV:

ServiceURLPurpose
Drupal Platformhttps://llm-platform.ddev.siteMain application
LLM Gatewayhttp://localhost:4000AI routing
Qdranthttp://localhost:6333Vector database
PostgreSQLlocalhost:5432Primary database
Redislocalhost:6379Cache & sessions
Mailhoghttp://llm-platform.ddev.site:8025Email testing

Additional Services

# Start LLM Gateway
ddev exec -s llm-gateway npm run dev

# Start Agent Mesh
ddev exec -s agent-mesh npm run dev

# Start Agent Tracer
ddev exec -s agent-tracer npm run dev

Environment Variables

# Edit .ddev/config.yaml
web_environment:
  - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
  - OPENAI_API_KEY=${OPENAI_API_KEY}
  - QDRANT_URL=http://qdrant:6333
  - REDIS_URL=redis://redis:6379
  - DATABASE_URL=postgresql://db:db@db:5432/db

# Restart to apply changes
ddev restart

Development Workflow

Daily Development

# Start day
ddev start
ddev platform status

# Pull latest changes
git pull origin development
ddev composer install
ddev drush updb -y
ddev drush cim -y
ddev drush cr

# Make changes
# ... edit code ...

# Run tests
ddev tddai check web/modules/custom/llm
ddev exec phpunit web/modules/custom/llm

# Commit changes
ddev git-safe commit "feat: add new feature"
ddev git-safe push

# End day
ddev stop

Module Development

# Sync custom modules
cd $LLM_ROOT/all_drupal_custom/modules
# ... make changes ...

# Sync to platform
buildkit drupal sync --modules --dry-run
buildkit drupal sync --modules

# Enable module in DDEV
ddev drush en my_module -y
ddev drush cr

Database Operations

# Export configuration
ddev drush cex -y

# Import configuration
ddev drush cim -y

# Update database
ddev drush updb -y

# Rebuild cache
ddev drush cr

# Database snapshot
ddev snapshot

# Restore snapshot
ddev snapshot restore

Debugging

Xdebug

# Enable Xdebug
ddev xdebug on

# Disable Xdebug (improves performance)
ddev xdebug off

# Check Xdebug status
ddev xdebug status

Configure IDE:

  • PHPStorm: Preferences PHP Debug Port 9003
  • VSCode: Install PHP Debug extension, use port 9003

Logs

# View web logs
ddev logs

# View PHP error log
ddev logs -f

# View specific service logs
ddev logs -s llm-gateway

# Platform logs
ddev platform logs

Testing

# PHPUnit tests
ddev exec phpunit web/modules/custom/llm

# With coverage
ddev exec phpunit --coverage-html coverage web/modules/custom/llm

# Specific test
ddev exec phpunit --filter testUserCreation

# PHPCS (code standards)
ddev exec phpcs --standard=Drupal,DrupalPractice web/modules/custom/

# PHPCS auto-fix
ddev exec phpcbf --standard=Drupal,DrupalPractice web/modules/custom/

# PHPStan (static analysis)
ddev exec phpstan analyze web/modules/custom/llm

Troubleshooting

DDEV Won't Start

# Check Docker is running
docker ps

# Restart Docker Desktop

# Remove containers and start fresh
ddev delete -O
ddev start

# Check for port conflicts
ddev poweroff
ddev start

Performance Issues

# Disable Xdebug
ddev xdebug off

# Increase Docker resources
# Docker Desktop  Settings  Resources
# CPU: 4+ cores
# Memory: 8GB+

# Use Mutagen for file sync (macOS)
ddev config --mutagen-enabled
ddev restart

Database Issues

# Reset database
ddev snapshot restore

# Or reimport
ddev import-db --src=backup.sql.gz

# Check database connection
ddev mysql

Module Not Found

# Sync modules from source
buildkit drupal sync --modules

# Rebuild cache
ddev drush cr

# Clear all caches
ddev drush cr
ddev composer clear-cache
ddev restart

SSL Certificate Issues

# Trust DDEV certificate
mkcert -install

# Regenerate certificate
ddev restart

DDEV Addons

Installed Addons

# Platform CLI addon
ddev platform --help

# AI integration addon
ddev ai --help

# TDD enforcement addon
ddev tddai --help

# Git safety addon
ddev git-safe --help

# Qdrant addon
ddev qdrant --help

Install Additional Addons

# Get addon from DDEV registry
ddev get ddev/ddev-addon-name

# Or install custom addon
ddev get ./infrastructure/ddev-addons/my-addon

Best Practices

1. Always Use DDEV Commands

# Good
ddev composer install
ddev drush cr
ddev exec phpunit

# Avoid
composer install  # Runs on host, not container
drush cr          # Requires local Drush
phpunit           # Requires local PHP

2. Commit Configuration Changes

# After configuration changes
ddev drush cex -y
git add config/
git commit -m "config: update module settings"

3. Use Snapshots

# Before risky operations
ddev snapshot

# If something breaks
ddev snapshot restore

4. Keep DDEV Updated

# Update DDEV
brew upgrade ddev

# Update project configuration
ddev config --update
ddev restart

5. Stop When Not Using

# Stop to free resources
ddev stop

# Or stop all projects
ddev poweroff

Integration with BuildKit

# BuildKit works seamlessly with DDEV
buildkit golden test                    # Runs in DDEV context
buildkit drupal sync                   # Syncs to DDEV platform
buildkit golden deploy --env dev       # Deploys to DDEV

Performance Optimization

macOS (Mutagen)

# Enable Mutagen for faster file sync
ddev config --mutagen-enabled
ddev restart

# Check Mutagen status
ddev mutagen status

Docker Desktop Settings

  • CPU: 4+ cores recommended
  • Memory: 8GB+ recommended
  • Disk: Use VirtioFS (faster than gRPC)
  • Swap: 2GB+

Composer Optimization

# Use Composer cache
ddev composer install --prefer-dist --optimize-autoloader

# Clear composer cache if needed
ddev composer clear-cache

Related Documentation