DDEV Kanopi Pantheon Drupal Add-on

A comprehensive DDEV add-on that provides Kanopi’s battle-tested workflow for Drupal development with Pantheon hosting. This add-on includes 17 custom commands, enhanced Pantheon provider, and complete tooling for modern Drupal development.

Features

• 🚀 Complete Development Workflow: From project init to deployment
• 🏛️ Enhanced Pantheon Integration: Smart backup management and seamless database/file syncing
• 🧪 Cypress Testing Support: E2E testing with user management
• 🎨 Theme Development Tools: Node.js/NPM integration with build tools
• 📦 Drupal Recipe Support: Apply Drupal 11 recipes with cache management
• 🔄 Migration Utilities: Tools for site migrations and database management
• ⚡ Performance Tools: Critical CSS generation and asset optimization

Installation

For Existing DDEV Projects

If you already have DDEV set up in your project:

# Install the add-on
ddev add-on get kanopi/ddev-kanopi-pantheon-drupal

# Configure your Pantheon machine token globally
ddev config global --web-environment-add=TERMINUS_MACHINE_TOKEN=your_token_here

# Restart DDEV to apply changes
ddev restart

For Projects Without DDEV

If your project doesn’t have DDEV yet, follow these steps:

Step 1: Install DDEV (if not already installed)

macOS:

# Using Homebrew (recommended)
brew install ddev

# Or using the installer script
curl -fsSL https://ddev.com/install.sh | bash

Linux/Windows: Follow instructions at ddev.readthedocs.io

Step 2: Initialize DDEV in Your Project

Navigate to your existing project directory and configure DDEV:

cd /path/to/your-drupal-project

# Initialize DDEV configuration
ddev config --project-type=drupal --docroot=web --php-version=8.3

# Add Pantheon machine token
ddev config global --web-environment-add=TERMINUS_MACHINE_TOKEN=your_pantheon_token

# Start DDEV
ddev start

Step 3: Install This Add-on

# Install the Kanopi Pantheon Drupal add-on
ddev add-on get kanopi/ddev-kanopi-pantheon-drupal

# Restart DDEV
ddev restart

Step 4: Configuration

Configure the add-on for your project:

1. Configure your Pantheon project in .ddev/providers/pantheon.yaml:

   environment_variables:
     project: your-site-name.env
   

2. Configure Pantheon and Migration variables in .ddev/env.web:

   THEME=themes/custom/your-theme
   THEMENAME=your-theme
   hostingsite=your-pantheon-site
   hostingenv=dev
   MIGRATE_DB_SOURCE=pantheon_source_project
   MIGRATE_DB_ENV=live
   

3. Restart DDEV to apply changes:

   ddev restart
   

Step 5: Complete Setup

# Run complete initialization (installs all dependencies and tools)
ddev init

# Open your site
ddev open

Quick Start Summary

For the performant developer:

# 1. Navigate to your Drupal project
cd your-drupal-project

# 2. Configure DDEV
ddev config --project-type=drupal --docroot=web --php-version=8.3

# 3. Add Pantheon token
ddev config global --web-environment-add=TERMINUS_MACHINE_TOKEN=your_token

# 4. Start DDEV and add add-on
ddev start
ddev add-on get kanopi/ddev-kanopi-pantheon-drupal

# 5. Update variables in .ddev/env.web and .ddev/providers/pantheon.yaml

# 6. Restart and initialize
ddev restart
ddev init

# 7. You're ready to develop!
ddev open

Available Commands

This add-on provides 17 custom commands organized by where they execute (host system vs. web container):

Smart Database Refresh

The enhanced ddev refresh command includes intelligent backup management:

• Automatic Backup Age Detection: Checks if backups are older than 12 hours
• Force Flag Support: Use -f to create new backup regardless of age
• Environment Support: Refresh from any Pantheon environment (dev, test, live, multidev)
• Integrated User Creation: Automatically creates Cypress test users after refresh

# Refresh from dev (default)
ddev refresh

# Refresh from live environment  
ddev refresh live

# Force new backup creation
ddev refresh -f

# Refresh from multidev environment
ddev refresh pr-123

Theme Development Workflow

1. Setup: ddev install-theme-tools
2. Development: ddev npm run watch
3. Build: ddev npm run build
4. Critical CSS: ddev install-critical-tools

Recipe Development Workflow

1. Apply Recipe: ddev recipe-apply ../recipes/my-recipe
2. Clean Config: ddev uuid-rm config/sync
3. Export Config: ddev drush config:export

Environment Variables

The add-on automatically configures these environment variables:

• THEME: Path to custom theme directory
• THEMENAME: Theme name for development tools
• hostingsite: Pantheon site identifier
• hostingenv: Current environment (dev, test, live)
• MIGRATE_DB_SOURCE: Source database for migrations
• MIGRATE_DB_ENV: Source environment for migrations

Managing This Add-on

View Installed Add-ons

# List all installed add-ons
ddev add-on list --installed

Update the Add-on

# Update to the latest version
ddev add-on get kanopi/ddev-kanopi-pantheon-drupal

Remove the Add-on

# Remove the add-on completely
ddev add-on remove kanopi-pantheon-drupal

Troubleshooting

Pantheon Authentication Issues

# Check if token is set
ddev exec printenv TERMINUS_MACHINE_TOKEN

# Re-authenticate manually
ddev exec terminus auth:login --machine-token="your_token"

Theme Build Issues

# Check Node.js version
ddev exec node --version

# Reinstall dependencies
ddev install-theme-tools

Database Refresh Issues

# Check Pantheon connection
ddev exec terminus site:list

# Force new backup
ddev refresh -f

Contributing

This add-on is maintained by Kanopi Studios. For issues, feature requests, or contributions, please visit our GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.