bluefly / alternative_services
Discover, configure, and monitor external services and containers from Drupal
Requires
- php: >=8.1
- drupal/core: ^10.0 || ^11.0
Suggests
- ext-yaml: For YAML configuration parsing
- symfony/process: For executing system commands
This package is auto-updated.
Last update: 2025-08-25 12:21:32 UTC
README
What it actually does: A comprehensive service discovery and orchestration platform centered around the DDEV Addon Browser system. It transforms container management into an intuitive, AI-powered experience with visual composition, unified CLI/UI wizard, and Tour module integration across Docker, Kubernetes, and DDEV environments.
π Table of Contents
- Overview
- Core Features
- DDEV Addon Browser
- Installation
- Quick Start
- API Reference
- Architecture
- Configuration
- Development
- Testing
- Troubleshooting
- Contributing
- License
π― Overview
The Alternative Services module is the central hub for service discovery and orchestration in the LLM Platform ecosystem. It provides a comprehensive DDEV Addon Browser that allows developers to discover, install, and manage development environment addons through both web interfaces and CLI commands.
Key Capabilities
- π Service Discovery: Automatic detection of services across Docker, Kubernetes, and DDEV environments
- π¦ DDEV Addon Management: Browse, install, and configure DDEV addons with Node.js enhancements
- π¨ Visual Orchestration: Drag-and-drop interface for composing service workflows
- π€ AI Integration: Smart recommendations and automated configuration generation
- π§ CLI Tools: Comprehensive Drush command suite with Tour integration
- π Health Monitoring: Real-time service status and performance tracking
β¨ Core Features
π― DDEV Addon Browser
- Comprehensive addon registry with search, filtering, and categorization
- One-click installation with dependency resolution and validation
- Node.js enhancements for CLI tools with interactive interfaces
- Real-time status monitoring and health checks for installed addons
- Bulk operations for managing multiple addons simultaneously
- Integration testing to verify addon compatibility and functionality
π οΈ Service Discovery Dashboard
- AI-powered environment detection with automatic service discovery across Docker, Kubernetes, and DDEV
- Smart categorization with real-time filtering (Web Services, Databases, Caching, Monitoring)
- Multi-environment discovery from local containers, Kubernetes clusters, and DDEV projects
- Service health monitoring with dependency analysis and real-time status updates
- AI recommendations based on automated infrastructure analysis
π¨ Visual Orchestration Builder
- Drag-and-drop interface for composing service workflows from containers, configs, and networking
- Real-time validation with dependency checking and conflict detection
- AI assistance for suggesting optimal service configurations and connections
- Multiple export formats (Docker Compose, Kubernetes YAML, DDEV Config, Terraform)
- Auto-save with progress tracking and session management
π§ββοΈ Unified Setup Wizard (CLI + UI + Tour)
- Tour module integration for interactive guided service deployment experiences
- CLI support (
drush service:wizard
) with full ASCII interface and interactive prompts - Real-time progress via WebSocket for live updates during service deployment
- Smart rollback capabilities on deployment failure
- Automatic tour generation from deployed service configurations
π€ AI Integration Points
- Smart service suggestions based on infrastructure configuration analysis
- Natural language search for finding relevant services ("I need a web app with database")
- Automated configuration generation for optimal service settings
- Intelligent dependency resolution and conflict detection
- Context-aware help system with troubleshooting for container environments
π Smart Integrations
- Docker Engine: Native container discovery and management
- Kubernetes: Cluster service orchestration and deployment
- DDEV: Local development environment integration with addon management
- SSL Certificate Manager: Automated certificate generation and management
- Tour Module: Interactive onboarding experiences
π§ DDEV Addon Browser
The DDEV Addon Browser is the cornerstone feature of the Alternative Services module, providing a comprehensive interface for discovering, installing, and managing DDEV addons within the Drupal environment.
π¦ Addon Management Features
Browser Interface
- Visual addon gallery with detailed descriptions, screenshots, and feature lists
- Search and filtering by category, functionality, and installation status
- Dependency visualization showing addon relationships and requirements
- Installation progress tracking with real-time status updates
- Bulk operations for installing, updating, or removing multiple addons
Available Addons Registry
The system includes support for these core DDEV addons:
Addon | Description | Features | Node.js Enhanced |
---|---|---|---|
ddev-llmcli | LLM Platform CLI | Service monitoring, Gateway management, Model operations | β |
ddev-tddai | AI-Enhanced TDD | Standards checking, Automated fixing, Policy validation | β |
ddev-git-tools | Git Workflow Tools | Safe commit workflows, Branch management | β |
ddev-platform-tools | Platform Management | Environment orchestration, Service coordination | β |
ddev-qdrant | Vector Database | Qdrant management, Vector operations | β |
ddev-monitoring | System Monitoring | Prometheus metrics, Health dashboards | π§ |
ddev-ai-tools | AI Development Tools | Model testing, Training workflows | π§ |
Node.js Enhancements
- Interactive CLI interfaces with rich ASCII art and progress indicators
- Real-time command feedback with colored output and status updates
- Command autocompletion and contextual help systems
- Configuration wizards for complex setup procedures
- Integration testing suites for validating addon functionality
π Installation Methods
Web Interface Installation
- Navigate to Configuration > Services > Alternative Services > DDEV Addons
- Browse available addons or use search/filter
- Click "Install" on desired addon
- Monitor installation progress in real-time
- Verify installation success and test functionality
CLI Installation
# List available addons
drush alternative-services:addon-list
# Install specific addon
drush as:addon-install ddev-llmcli
# Install multiple addons
drush as:addon-install ddev-llmcli,ddev-tddai,ddev-git-tools
# Install all recommended addons
drush as:addon-install-all
# Install with dependency resolution
drush as:addon-install ddev-platform-tools --with-deps
Bulk Installation
# Install from configuration file
drush as:addon-install --from-config=addon-config.json
# Install development addon suite
drush as:addon-install --suite=development
# Install AI development stack
drush as:addon-install --suite=ai-development
π Addon Discovery and Search
Smart Search Features
- Semantic search: Find addons by functionality ("monitoring tools", "git workflow")
- Tag-based filtering: Filter by categories like "ai", "development", "monitoring"
- Status filtering: Show installed, available, or updatable addons
- Dependency search: Find addons that depend on or enhance existing installations
Discovery Mechanisms
# Discover addons from filesystem
drush as:addon-discover
# Refresh addon registry
drush as:addon-refresh
# Scan for new addon versions
drush as:addon-check-updates
# Validate addon installations
drush as:addon-validate
βοΈ Configuration Management
Addon Configuration
# Configuration for individual addons
ddev_addons:
ddev-llmcli:
enabled: true
auto_update: false
config:
gateway_endpoint: "http://localhost:4000"
debug_mode: true
ddev-tddai:
enabled: true
auto_update: true
config:
standards_level: "strict"
auto_fix: true
Global Settings
# Global addon system settings
addon_browser:
auto_install_dependencies: true
parallel_installations: 3
health_check_interval: 300
registry_cache_ttl: 3600
enable_notifications: true
π Monitoring and Health Checks
Real-time Status Monitoring
- Installation status: Track progress of addon installations
- Health monitoring: Continuous monitoring of addon functionality
- Dependency tracking: Monitor addon interdependencies and conflicts
- Performance metrics: Track resource usage and performance impact
Health Check Commands
# Check all addon health
drush as:addon-health
# Check specific addon
drush as:addon-health ddev-llmcli
# Run comprehensive addon validation
drush as:addon-validate --comprehensive
# Generate health report
drush as:addon-health-report --output=json
π§ Advanced Features
Custom Addon Development
- Addon scaffolding: Generate boilerplate code for new addons
- Template system: Use predefined templates for common addon types
- Testing framework: Built-in testing tools for addon validation
- Documentation generation: Automatic documentation from addon metadata
Integration Points
- Tour module integration: Interactive tutorials for addon usage
- GraphQL API: Query addon status and metadata via GraphQL
- WebSocket updates: Real-time notifications for addon events
- Event system: Hook into addon lifecycle events
π οΈ Legacy Features
Discovery Dashboard
- Real-time service discovery across multiple environments
- Health monitoring and status tracking
- SSL certificate management integration
- AI-powered recommendations
- Export/import configuration capabilities
Orchestration Builder
- Visual workflow designer with drag-and-drop interface
- Node-based service configuration
- Real-time validation with error reporting
- Template system for common configurations
- AI suggestions for optimization
Setup Wizard
- Multi-step configuration process
- Environment detection and selection
- Service discovery and configuration
- SSL certificate setup
- Tour mode for guided learning
CLI Integration
- Interactive Drush commands with ASCII art interfaces
- Tour-guided CLI workflows
- Health monitoring and management
- SSL certificate operations
- Configuration export/import
π₯ Installation
System Requirements
- Drupal: 10.1+
- PHP: 8.2+
- DDEV: 1.22+ (recommended)
- Docker: 20.10+ or compatible container runtime
- Node.js: 18+ (for enhanced CLI features)
- Composer: 2.0+
Installation Methods
Standard Installation
Enable the module:
# Via Drush drush en alternative_services -y # Or via Drupal Admin UI # Navigate to Extend > Alternative Services > Install
Install dependencies:
# Install Node.js dependencies for enhanced features cd web/modules/custom/alternative_services npm install # Or use the automated installer drush alternative-services:install-deps
Run initial setup:
# Interactive setup wizard drush alternative-services:setup # Quick setup with defaults drush alternative-services:setup --quick # Tour-guided setup for first-time users drush alternative-services:setup --tour
Development Installation
# Clone or ensure module is in custom modules directory
cd web/modules/custom/alternative_services
# Install development dependencies
npm install --dev
composer install --dev
# Run development setup
drush alternative-services:setup --environment=development
# Enable debug mode
drush config:set alternative_services.settings debug_mode true
Production Installation
# Production-optimized installation
drush alternative-services:setup --environment=production
# Configure caching and performance
drush config:set alternative_services.settings cache_enabled true
drush config:set alternative_services.settings parallel_discovery true
# Set up monitoring
drush alternative-services:monitoring:enable
Post-Installation Configuration
Environment Variables
# Add to .env or settings.php
export LLM_PLATFORM_ROOT="/var/www/html"
export ALTERNATIVE_SERVICES_CONFIG_DIR="/var/www/html/config/alternative_services"
export ALTERNATIVE_SERVICES_WS_HOST="localhost"
export ALTERNATIVE_SERVICES_WS_PORT="8080"
Directory Permissions
# Ensure proper permissions for addon management
chmod -R 755 infrastructure/ddev-addons/
chown -R www-data:www-data web/modules/custom/alternative_services/ssl/
π Quick Start
Getting Started in 5 Minutes
1. Access the DDEV Addon Browser
# Navigate to addon browser
drush alternative-services:addon-browser
# Or via web interface
# Go to: /admin/config/services/alternative-services/ddev-addons
2. Install Essential Addons
# Install core development stack
drush as:addon-install ddev-llmcli,ddev-tddai
# Or install via web interface
# Click "Install All Recommended" in the addon browser
3. Verify Installation
# Check addon status
drush as:addon-health
# Test installed addons
ddev llm health
ddev tddai check
4. Explore Features
# Launch service discovery
drush alternative-services:discovery --tour
# Try the orchestration builder
drush alternative-services:orchestrate --template=basic
# Access web dashboard
# Navigate to: /admin/config/services/alternative-services
First-Time Setup Wizard
The setup wizard provides an interactive experience for configuring the system:
# Start the comprehensive setup wizard
drush alternative-services:setup --interactive
# The wizard will guide you through:
# 1. Environment detection
# 2. Service discovery configuration
# 3. DDEV addon selection
# 4. SSL certificate setup
# 5. Integration testing
Common First Tasks
Browse and Install Addons
# List all available addons
drush as:addon-list --format=table
# Search for specific functionality
drush as:addon-search "monitoring"
# Install addon with dependencies
drush as:addon-install ddev-monitoring --with-deps
Configure Service Discovery
# Discover services in current environment
drush as:discover --environment=auto
# Configure custom service endpoints
drush as:service-add --name="Custom API" --endpoint="http://api.local"
# Export discovered configuration
drush as:export --output=services.json
Health Monitoring Setup
# Enable health monitoring
drush as:health-monitoring:enable
# Configure monitoring intervals
drush config:set alternative_services.settings health_check_interval 300
# Set up alerts
drush as:alerts:configure --email=admin@example.com
π Usage Guide
Web Interface Navigation
Navigate to Configuration > Services > Alternative Services to access:
- DDEV Addon Browser:
/admin/config/services/alternative-services/ddev-addons
- Discovery Dashboard:
/admin/config/services/alternative-services/discovery
- Orchestration Builder:
/admin/config/services/alternative-services/orchestration
- Setup Wizard:
/admin/config/services/alternative-services/setup
- Health Monitoring:
/admin/config/services/alternative-services/health
Core Workflows
1. Managing DDEV Addons
Browse Available Addons:
- Visit the DDEV Addon Browser at
/admin/config/services/alternative-services/ddev-addons
- Use search and filters to find relevant addons
- View detailed addon information, dependencies, and screenshots
- Check compatibility and system requirements
Install Addons:
- Click "Install" on any addon card
- Monitor real-time installation progress
- Verify successful installation with automatic health checks
- Access newly installed addon commands via
ddev [addon-name]
Manage Installed Addons:
- View installation status and health indicators
- Update addons to latest versions
- Configure addon-specific settings
- Uninstall unused addons with dependency cleanup
2. Service Discovery and Health Monitoring
Automatic Discovery:
- Navigate to Discovery Dashboard
- Click "Start Discovery" to scan environments
- Review discovered services and their health status
- Add custom services not automatically detected
Health Monitoring:
- Access real-time health dashboards
- Set up monitoring alerts and notifications
- View historical health data and trends
- Export health reports for analysis
3. Visual Service Orchestration
Using the Orchestration Builder:
- Open the Visual Orchestration Builder
- Drag and drop services to create workflows
- Configure service connections and dependencies
- Validate configuration in real-time
- Export to Docker Compose, Kubernetes YAML, or other formats
Drush Commands
Service Discovery
# Interactive discovery dashboard
drush alternative-services:discovery
# Discover services in specific environment
drush as:discover --environment=ddev
# Export discovered services
drush as:discover --export=/path/config.json
# Start with interactive tour
drush as:discover --tour
Orchestration Builder
# Interactive orchestration builder
drush alternative-services:orchestrate
# Load pre-built template
drush as:orchestrate --load-template=basic
# Validate configuration only
drush as:orchestrate --validate-only
# Tour-guided orchestration
drush as:orchestrate --tour
Setup Wizard
# Full interactive setup
drush alternative-services:setup
# Quick setup with defaults
drush as:setup --quick
# Setup for specific environment
drush as:setup --environment=ddev
# Tour-guided setup
drush as:setup --tour
Health Monitoring
# Check all services health
drush alternative-services:health
# Continuous monitoring
drush as:health --watch
# Check specific service
drush as:health --service=ollama
SSL Management
# Generate SSL certificates
drush alternative-services:ssl generate
# Check certificate status
drush as:ssl status
# Renew certificates
drush as:ssl renew
Tour Generation
# Generate tour from current configuration
drush alternative-services:generate-tour
# Export tour configuration
drush as:tour-gen --output=tour.json
Configuration
Environment Variables
The module supports the following environment variables:
# LLM Platform root directory
export LLM_PLATFORM_ROOT="$HOME$LLM_WORKSPACE_PATH"
# Alternative Services configuration
export ALTERNATIVE_SERVICES_CONFIG_DIR="$HOME/.alternative-services"
# WebSocket configuration
export ALTERNATIVE_SERVICES_WS_HOST="localhost"
export ALTERNATIVE_SERVICES_WS_PORT="8080"
Service Configuration
Configure services via the web interface or by editing configuration files:
# Example service configuration
services:
ollama:
name: "Ollama AI Service"
type: "AI"
endpoint: "http://localhost:11434"
enabled: true
health_check_interval: 30
ssl_enabled: false
qdrant:
name: "Qdrant Vector Database"
type: "DATABASE"
endpoint: "http://localhost:6333"
enabled: true
health_check_interval: 60
ssl_enabled: true
SSL Configuration
SSL certificates are managed automatically or can be configured manually:
ssl:
mode: "auto" # auto, manual, none
domain: "local.bluefly.io"
wildcard: true
auto_renewal: true
certificates_path: "/path/to/certificates"
π API Reference
The Alternative Services module provides comprehensive APIs for programmatic access to all functionality. See docs/api-reference.md for complete documentation.
REST API Overview
DDEV Addon Management
# Addon discovery and management
GET /api/v1/ddev-addons # List available addons
POST /api/v1/ddev-addons/{id}/install # Install specific addon
DELETE /api/v1/ddev-addons/{id}/uninstall # Uninstall addon
GET /api/v1/ddev-addons/{id}/health # Check addon health
POST /api/v1/ddev-addons/install-all # Bulk install addons
Service Discovery
# Service discovery and monitoring
GET /api/v1/services # List discovered services
POST /api/v1/services/discover # Trigger service discovery
GET /api/v1/services/{id}/health # Check service health
POST /api/v1/services/{id}/start # Start service
POST /api/v1/services/{id}/stop # Stop service
Orchestration
# Service orchestration
POST /api/v1/orchestration/deploy # Deploy service stack
GET /api/v1/orchestration/templates # List available templates
POST /api/v1/orchestration/validate # Validate configuration
GET /api/v1/orchestration/status # Get deployment status
GraphQL API Overview
type Query {
# DDEV Addon queries
ddevAddons: [DdevAddon]
ddevAddon(id: String!): DdevAddon
addonHealth(id: String!): AddonHealth
# Service queries
alternativeServices: [AlternativeService]
alternativeService(id: String!): AlternativeService
serviceHealth(id: String!): ServiceHealth
discoverServices(environment: String!): [DiscoveredService]
}
type Mutation {
# Addon management
installAddon(id: String!, config: AddonConfigInput): AddonInstallResult
uninstallAddon(id: String!): Boolean
# Service management
createAlternativeService(input: AlternativeServiceInput!): AlternativeService
updateAlternativeService(id: String!, input: AlternativeServiceInput!): AlternativeService
deleteAlternativeService(id: String!): Boolean
executeWorkflow(input: WorkflowInput!): WorkflowResult
}
WebSocket Events
Real-time updates are provided via WebSocket connections:
// Addon installation events
{
"type": "addon_install_progress",
"addon_id": "ddev-llmcli",
"progress": 75,
"status": "installing_dependencies"
}
// Health monitoring events
{
"type": "health_update",
"service_id": "ollama",
"status": "healthy",
"metrics": { "cpu": 12.5, "memory": "512MB" }
}
// Discovery events
{
"type": "service_discovered",
"service": {
"id": "new-api-service",
"name": "Custom API",
"endpoint": "http://api.local:3000"
}
}
ποΈ Architecture
The Alternative Services module follows a layered service-oriented architecture designed for scalability and extensibility.
System Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Presentation Layer β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Web UI (Twig) β REST API β GraphQL API β CLI Tools β
β - Addon Browser β - JSON responses β - Schema β - Drush β
β - Dashboards β - OpenAPI docs β - Mutations β - Tour β
β - Wizards β - Rate limiting β - Queries β - ASCII β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Business Logic Layer β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Controllers β Services β Managers β
β - DdevAddonController β - AddonRegistryService β - Health β
β - ApiController β - AddonSearchService β - Config β
β - DashboardController β - HealthMonitor β - SSL β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Integration Layer β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Adapters β External APIs β Event System β
β - DdevAdapter β - Docker Engine β - Hooks β
β - OrbStackAdapter β - Kubernetes API β - WebSockets β
β - ContainerRuntime β - LLM Gateway β - Queue Jobs β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Data Access Layer β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Entities β Storage β Cache Layer β
β - DdevAddon β - Config system β - Redis/Memcacheβ
β - AlternativeService β - State API β - File cache β
β - ServiceHealth β - JSON storage β - Database cacheβ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Core Components
Service Layer Architecture
- DdevAddonManager: Core service for addon lifecycle management
- AddonRegistryService: Manages addon discovery and metadata
- AddonSearchService: Provides search and filtering capabilities
- HealthMonitor: Continuous health monitoring and alerting
- ServiceOrchestrator: Manages service deployment and coordination
Entity System
- DdevAddon: Represents DDEV addon configuration and state
- AlternativeService: General service configuration entity
- ServiceHealth: Health monitoring data and metrics
- DashboardMetric: Performance and usage metrics
Integration Points
- Container Runtime Adapters: Support for Docker, OrbStack, Podman
- GraphQL Schema Extensions: Extensible API schema
- Event Dispatcher: Hook system for custom extensions
- Queue Workers: Background processing for long-running operations
Design Patterns
Dependency Injection
public function __construct(
DdevAddonManager $addon_manager,
AddonRegistryService $addon_registry,
AddonSearchService $addon_search,
HealthMonitor $health_monitor
) {
// Services injected via Drupal DI container
}
Factory Pattern
// Adapter factory for different container runtimes
class ContainerRuntimeFactory {
public static function create(string $runtime): ContainerRuntimeInterface {
return match($runtime) {
'ddev' => new DdevAdapter(),
'orbstack' => new OrbStackAdapter(),
'docker' => new DockerAdapter(),
};
}
}
Observer Pattern
// Event-driven health monitoring
class AddonHealthMonitor implements EventSubscriberInterface {
public static function getSubscribedEvents(): array {
return [
'addon.installed' => 'onAddonInstalled',
'addon.health_check' => 'onHealthCheck',
];
}
}
AI Integration
The module integrates with AI services for:
- Smart Service Discovery: AI-powered service detection and recommendation
- Configuration Assistance: Intelligent configuration suggestions
- Health Prediction: Predictive health monitoring and alerting
- Workflow Optimization: AI-suggested improvements for orchestration workflows
WebSocket Support
Real-time updates are provided via WebSocket connections:
// Connect to WebSocket for real-time updates
const ws = new WebSocket('ws://localhost:8080/alternative-services');
ws.onmessage = function(event) {
const data = JSON.parse(event.data);
switch(data.type) {
case 'service_discovered':
// Handle new service discovery
break;
case 'health_update':
// Handle health status change
break;
case 'configuration_change':
// Handle configuration update
break;
}
};
Tour Integration
The module integrates with Drupal's Tour module to provide guided experiences:
- Interactive step-by-step tutorials
- Context-aware help and hints
- CLI command demonstrations
- Best practice guidance
Tours can be customized and extended through the configuration interface.
Troubleshooting
Common Issues
Service Discovery Not Working
# Check environment detection
drush as:health
# Verify network connectivity
drush as:discover --environment=manual
# Check logs
drush watchdog:show --filter=alternative_services
SSL Certificate Issues
# Regenerate certificates
drush as:ssl generate --force
# Check certificate status
drush as:ssl status
# Verify domain configuration
drush as:ssl status --domain=your-domain.com
WebSocket Connection Errors
- Ensure WebSocket server is running
- Check firewall settings
- Verify port availability
- Review browser console for errors
Debug Mode
Enable debug mode for additional logging:
# In settings.local.php
$config['alternative_services.settings']['debug'] = TRUE;
Development
Extending the Module
The module follows Drupal best practices and provides extension points:
- Custom Service Types: Add new service types via plugins
- Discovery Adapters: Implement custom environment adapters
- Orchestration Templates: Create reusable workflow templates
- AI Integrations: Add custom AI service providers
- Tour Customization: Create custom tour configurations
Testing
Run the test suite:
# Unit tests
phpunit --group alternative_services
# Functional tests
phpunit --group alternative_services_functional
# JavaScript tests
npm test
Support
For support and documentation:
License
This module is part of the LLM Platform ecosystem and follows the same licensing terms.