gh-netresearch-claude-code-marketplace-skills-typo3-ddev/SKILL.md

name, description, license, metadata

name	description	license	metadata
typo3-ddev	Automate DDEV environment setup for TYPO3 extension development. Use when setting up local development environment, configuring DDEV for TYPO3 extensions, or creating multi-version TYPO3 testing environments. Covers: DDEV configuration generation, TYPO3 11.5/12.4/13.4 LTS installation, custom DDEV commands, Apache vhost setup, Docker volume management, and .gitignore best practices (avoid double-ignore anti-pattern). Provides complete automation from metadata detection to ready-to-use TYPO3 backend access.	MIT License - see LICENSE file	author repository version tags platforms typo3-versions Netresearch https://github.com/netresearch/typo3-ddev-skill 1.6.0 typo3 ddev docker development testing devops linux macos windows 11.5-lts 12.4-lts 13.4-lts

TYPO3 DDEV Setup Skill

This skill automates DDEV environment setup for TYPO3 extension development projects. It creates a complete TYPO3 development environment for testing and developing extensions across multiple TYPO3 versions.

Purpose

This skill automates the setup of DDEV for TYPO3 extension development projects. It creates a multi-version TYPO3 testing environment where the extension can be developed and tested across TYPO3 11.5 LTS, 12.4 LTS, and 13.4 LTS simultaneously.

When to Use This Skill

Use this skill when:

• Developer has a TYPO3 extension project and wants to set up DDEV
• Project contains ext_emconf.php or is identified as a TYPO3 extension in composer.json
• Developer needs to test extension across multiple TYPO3 versions
• Quick development environment spin-up is needed

Prerequisites Validation

Before executing ANY DDEV commands, perform comprehensive prerequisite validation:

1. Run validation script: Execute scripts/validate-prerequisites.sh to check:

   • Docker daemon status (must be running)
   • Docker CLI version (requires >= 20.10)
   • Docker Compose version (requires >= 2.0)
   • DDEV installation (must be present)
   • TYPO3 extension project structure (must be valid)

2. If validation fails: Consult references/prerequisites-validation.md for platform-specific installation instructions (Linux/WSL2, macOS, Windows), version requirements, manual validation steps, and troubleshooting

3. Report results: Display validation status to user with specific instructions for any missing prerequisites

Always validate on the FIRST DDEV command in a session to catch environment issues early.

Step-by-Step Workflow

Step 1: Extract Extension Metadata

Scan the project to extract:

1. Extension Key (e.g., my_ext):

   • From ext_emconf.php: Look for the array key or filename pattern
   • From composer.json: Look for extra.typo3/cms.extension-key
   • Fallback: Ask user to provide

2. Composer Package Name (e.g., vendor/my-ext):

   • From composer.json: Look for name field
   • Fallback: Construct from extension key or ask user

3. Vendor Namespace (e.g., Vendor\MyExt):

   • From composer.json: Look for autoload.psr-4 keys
   • Fallback: Ask user to provide

4. Extension Name (PascalCase, e.g., MyExt):

   • Convert extension key to PascalCase
   • Or extract from namespace

Step 2: Confirm Configuration

Present extracted values to user and confirm:

Detected TYPO3 Extension Configuration:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Extension Key:     my_ext
Package Name:      vendor/my-ext
DDEV Sitename:     my-ext
Vendor Namespace:  Vendor\MyExt
TYPO3 Versions:    11.5, 12.4, 13.4
PHP Version:       8.2

Is this correct? (y/n)

Allow user to adjust any values if needed.

Step 3: Generate DDEV Configuration

Create the following directory structure and files:

.ddev/
├── config.yaml
├── docker-compose.web.yaml
├── apache/
│   └── apache-site.conf
├── web-build/
│   └── Dockerfile
└── commands/
    └── web/
        ├── install-v11
        ├── install-v12
        ├── install-v13
        └── install-all
.envrc

3.1: .ddev/config.yaml

Replace these variables:

• {{DDEV_SITENAME}} → DDEV sitename (e.g., my-ext)

name: {{DDEV_SITENAME}}
type: php
docroot: ""
no_project_mount: true
php_version: "8.2"
composer_version: "2"
webserver_type: apache-fpm
router_http_port: "80"
router_https_port: "443"
xdebug_enabled: false
additional_hostnames:
    - docs.{{DDEV_SITENAME}}
    - v11.{{DDEV_SITENAME}}
    - v12.{{DDEV_SITENAME}}
    - v13.{{DDEV_SITENAME}}
additional_fqdns: []
use_dns_when_possible: true

3.2: .ddev/docker-compose.web.yaml

Replace these variables:

• {{EXTENSION_KEY}} → Extension key with underscores (e.g., my_ext)
• {{PACKAGE_NAME}} → Composer package name (e.g., vendor/my-ext)
• {{DDEV_SITENAME}} → DDEV sitename for volumes

services:
    web:
        environment:
            - EXTENSION_KEY={{EXTENSION_KEY}}
            - PACKAGE_NAME={{PACKAGE_NAME}}

            # TYPO3 v11 and v12 config
            - TYPO3_INSTALL_DB_DRIVER=mysqli
            - TYPO3_INSTALL_DB_USER=root
            - TYPO3_INSTALL_DB_PASSWORD=root
            - TYPO3_INSTALL_DB_HOST=db
            - TYPO3_INSTALL_DB_UNIX_SOCKET=
            - TYPO3_INSTALL_DB_USE_EXISTING=0
            - TYPO3_INSTALL_ADMIN_USER=admin
            - TYPO3_INSTALL_ADMIN_PASSWORD=Password:joh316
            - TYPO3_INSTALL_SITE_NAME=EXT:{{EXTENSION_KEY}} Dev Environment
            - TYPO3_INSTALL_SITE_SETUP_TYPE=site
            - TYPO3_INSTALL_WEB_SERVER_CONFIG=apache

            # TYPO3 v13 config
            - TYPO3_DB_DRIVER=mysqli
            - TYPO3_DB_USERNAME=root
            - TYPO3_DB_PASSWORD=root
            - TYPO3_DB_HOST=db
            - TYPO3_SETUP_ADMIN_EMAIL=admin@example.com
            - TYPO3_SETUP_ADMIN_USERNAME=admin
            - TYPO3_SETUP_ADMIN_PASSWORD=Password:joh316
            - TYPO3_PROJECT_NAME=EXT:{{EXTENSION_KEY}} Dev Environment
            - TYPO3_SERVER_TYPE=apache
        volumes:
            - type: bind
              source: ../
              target: /var/www/{{EXTENSION_KEY}}
              consistency: cached
            - v11-data:/var/www/html/v11
            - v12-data:/var/www/html/v12
            - v13-data:/var/www/html/v13
volumes:
    v11-data:
        name: "${DDEV_SITENAME}-v11-data"
    v12-data:
        name: "${DDEV_SITENAME}-v12-data"
    v13-data:
        name: "${DDEV_SITENAME}-v13-data"

3.3-3.7: Additional Configuration Files

Generate the following files using the templates from this skill repository:

• .ddev/apache/apache-site.conf (replace {{EXTENSION_KEY}} and {{DDEV_SITENAME}})
• .ddev/web-build/Dockerfile (replace {{EXTENSION_KEY}} and {{DDEV_SITENAME}})
• .ddev/commands/web/install-v11 (make executable)
• .ddev/commands/web/install-v12 (make executable)
• .ddev/commands/web/install-v13 (make executable)
• .ddev/commands/web/install-all (make executable)
• .ddev/commands/host/docs (make executable) - for rendering documentation

3.8: .envrc (direnv Configuration)

Generate .envrc in the project root for direnv integration:

Replace these variables:

• {{EXTENSION_KEY}} → Extension key with underscores (e.g., my_ext)
• {{DDEV_SITENAME}} → DDEV sitename (e.g., my-ext)

# direnv configuration for {{EXTENSION_KEY}}
# Auto-generated by typo3-ddev-skill

# Add composer bin directory to PATH
PATH_add vendor/bin

# Composer configuration
export COMPOSER_PROCESS_TIMEOUT=600

# DDEV environment variables
export DDEV_PROJECT={{DDEV_SITENAME}}
export DDEV_PRIMARY_URL=https://{{DDEV_SITENAME}}.ddev.site
export DDEV_DOCROOT_URL=https://docs.{{DDEV_SITENAME}}.ddev.site

# Load local environment overrides if present
dotenv_if_exists .env.local

# Display activation message
echo "✅ {{EXTENSION_KEY}} development environment activated"
echo ""
echo "🌐 DDEV Environment:"
echo "   Primary:   https://{{DDEV_SITENAME}}.ddev.site"
echo "   Docs:      https://docs.{{DDEV_SITENAME}}.ddev.site"
echo "   TYPO3 v11: https://v11.{{DDEV_SITENAME}}.ddev.site"
echo "   TYPO3 v12: https://v12.{{DDEV_SITENAME}}.ddev.site"
echo "   TYPO3 v13: https://v13.{{DDEV_SITENAME}}.ddev.site"
echo ""
echo "🚀 DDEV Commands:"
echo "   ddev start           Start DDEV environment"
echo "   ddev stop            Stop DDEV environment"
echo "   ddev restart         Restart DDEV environment"
echo "   ddev install-v11     Install TYPO3 11.5 LTS"
echo "   ddev install-v12     Install TYPO3 12.4 LTS"
echo "   ddev install-v13     Install TYPO3 13.4 LTS"
echo "   ddev install-all     Install all TYPO3 versions"

What it does:

• Adds vendor/bin to PATH for Composer tools
• Exports DDEV environment variables for easy access
• Displays helpful information when entering the project directory
• Lists available DDEV URLs and commands

User action required: Run direnv allow to activate the configuration.

Optional: If direnv is not installed, the file can be safely ignored.

Step 4: Initialize DDEV

After generating all files, guide the user through starting DDEV:

# Start DDEV containers
ddev start

Wait for DDEV to start successfully.

Step 5: Install TYPO3 Environments

Provide options to user:

Option A: Install All Versions (Recommended for compatibility testing)

ddev install-all

Option B: Install Specific Version (Faster for targeted development)

ddev install-v11    # TYPO3 11.5 LTS
ddev install-v12    # TYPO3 12.4 LTS
ddev install-v13    # TYPO3 13.4 LTS

Installation time: ~2-5 minutes per version (depending on network speed)

What gets installed automatically:

• ✅ TYPO3 Core (specified version)
• ✅ Your extension (activated and ready to use)
• ✅ TYPO3 Backend Styleguide (for UI pattern reference)
• ✅ Extension Manager
• ✅ Introduction Package (86+ pages with demo content for testing)

Step 6: Provide Access Information

After successful installation, display:

✅ DDEV Environment Ready!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Overview Dashboard:
   https://{{DDEV_SITENAME}}.ddev.site/

🌐 TYPO3 Installations:

   TYPO3 11.5 LTS
   Frontend: https://v11.{{DDEV_SITENAME}}.ddev.site/
   Backend:  https://v11.{{DDEV_SITENAME}}.ddev.site/typo3/

   TYPO3 12.4 LTS
   Frontend: https://v12.{{DDEV_SITENAME}}.ddev.site/
   Backend:  https://v12.{{DDEV_SITENAME}}.ddev.site/typo3/

   TYPO3 13.4 LTS
   Frontend: https://v13.{{DDEV_SITENAME}}.ddev.site/
   Backend:  https://v13.{{DDEV_SITENAME}}.ddev.site/typo3/

🔑 Backend Credentials:
   Username: admin
   Password: Password:joh316

📦 Your Extension:
   Installed in all TYPO3 versions
   Source: /var/www/{{EXTENSION_KEY}}/ (bind-mounted from project root)

⚙️  Useful Commands:
   ddev restart          # Restart containers
   ddev ssh              # SSH into web container
   ddev logs             # View container logs
   ddev describe         # Show project details
   ddev stop             # Stop containers
   ddev delete           # Remove containers (keeps volumes)

Step 7: Generate Makefile (Optional but Recommended)

After DDEV setup, generate a standardized Makefile following Netresearch's pattern for convenient command access:

ddev generate-makefile

Makefile Features

The generated Makefile provides a unified interface with 30+ targets:

DDEV Management:

make up              # Complete startup (start DDEV + install all TYPO3 versions)
make start           # Start DDEV environment
make stop            # Stop DDEV environment
make install-v11     # Install TYPO3 11.5 LTS
make install-v12     # Install TYPO3 12.4 LTS
make install-v13     # Install TYPO3 13.4 LTS
make install-all     # Install all TYPO3 versions
make urls            # Show all access URLs

Testing & Quality:

make test            # Run all tests (unit + functional)
make test-unit       # Run unit tests only
make test-functional # Run functional tests
make lint            # Run all linters (PHP syntax + PHPStan + code style)
make format          # Auto-fix code style issues
make typecheck       # Run PHPStan static analysis
make ci              # Complete CI pipeline (pre-commit checks)

Developer Convenience:

make help            # Show all available commands (default target)
make ssh             # SSH into DDEV web container
make clean           # Clean temporary files and caches

Extension-Specific Commands:

The Makefile includes a customizable section for extension-specific commands. Developers can add their own targets following the pattern:

.PHONY: my-command
my-command: ## Description of my command
	ddev ssh -d v12 "vendor/bin/typo3 extension:command"

Why Use the Makefile?

1. Consistency - Follows Netresearch's established pattern across TYPO3 extensions
2. Single Command Setup - make up does everything (DDEV start + install all versions)
3. Discoverability - make help shows all available commands with descriptions
4. CI Integration - Standardized make ci, make test, make lint for pipelines
5. Developer Experience - Familiar interface, shorter commands than ddev equivalents
6. Documentation - Self-documenting with auto-generated help

Example Workflow

# Initial setup
make up              # Start DDEV + install all TYPO3 versions

# Development
make lint            # Check code quality
make test            # Run tests
make format          # Fix code style

# Check URLs
make urls            # Show all access URLs

# Complete CI check before commit
make ci              # Run full quality pipeline

Customization

After generation, edit the Makefile to add project-specific commands while keeping core targets (up, start, test, lint, ci) unchanged for consistency across projects.

The Makefile is optional but highly recommended for improved developer experience.

Step 8: Generate Project Index Page (Optional but Recommended)

After DDEV setup, generate a beautiful overview page for easy access to all TYPO3 versions and development tools:

ddev generate-index

Index Page Features

The generated index.html provides a centralized dashboard with:

Visual Overview:

• Modern, responsive design with gradient background
• Card-based layout for each TYPO3 version
• Clear visual hierarchy and hover effects
• Mobile-friendly responsive grid

Quick Access Links:

TYPO3 v12 LTS:
  - Frontend: https://v12.{project}.ddev.site/
  - Backend:  https://v12.{project}.ddev.site/typo3/

TYPO3 v13 LTS:
  - Frontend: https://v13.{project}.ddev.site/
  - Backend:  https://v13.{project}.ddev.site/typo3/

Development Tools:

• Backend credentials display (admin / Password:joh316)
• Mailpit access link
• Documentation link (if available)

Why Use the Index Page?

1. Single Entry Point - Access all TYPO3 versions from one beautiful page
2. Eliminates URL Guessing - No need to remember subdomain patterns
3. Professional Presentation - Polished interface for the development environment
4. Credential Reference - Backend login info always visible
5. Tool Discovery - Links to Mailpit and other development tools
6. Multi-Version Testing - Easy switching between TYPO3 12 and 13

Example Usage

# After DDEV setup
ddev generate-index

# Access the overview page
open https://{project}.ddev.site/
# or
open http://{project}.ddev.site/

The index page is accessible at both the main domain (e.g., temporal-cache.ddev.site) and serves as the landing page for the entire development environment.

Customization

After generation, you can edit index.html to:

• Add extension-specific documentation links
• Include CI/CD status badges
• Add custom tool links (PHPMyAdmin, Redis Commander, etc.)
• Customize colors, branding, or layout
• Add project-specific information or notes

The index page is optional but highly recommended for improved developer experience, especially in multi-version testing environments.

For advanced branding and customization details including:

• Automatic branding detection (Netresearch/TYPO3/generic)
• Brand-specific color schemes and typography
• Design specifications

See: references/index-page-generation.md

Error Handling

When encountering errors during setup or installation:

1. Check error category: Identify if the error relates to prerequisites, database setup, extension detection, or service configuration
2. Consult troubleshooting guide: Read references/troubleshooting.md and locate the relevant error category
3. Apply recommended solution: Follow the step-by-step resolution guide for the specific error
4. For Windows/WSL2 environments: If error persists on Windows, consult references/windows-fixes.md for platform-specific solutions (CRLF issues, health check failures, Apache config problems)
5. Performance issues on Windows: Consult references/windows-optimizations.md for performance tuning

Report the error to the user with the specific solution being applied, then re-attempt the failed operation.

Advanced Configuration

When user requests customizations beyond the standard setup:

1. Identify customization type: Determine if request involves PHP version, database engine, debugging tools, TYPO3 versions, or additional services
2. Consult advanced options guide: Read references/advanced-options.md for the relevant configuration section
3. Present options to user: Show available choices (e.g., PHP 8.1/8.2/8.3, database engines with tiered selection logic)
4. Apply configuration: Follow the templates and instructions in references/advanced-options.md to implement the requested customization
5. Configure optional services: If user needs Valkey/Redis caching, MailPit, Ofelia scheduler, or other services, follow the service configuration templates in the advanced guide

Offer customization options proactively when user mentions performance requirements, specific PHP versions, or debugging needs.

Documentation Rendering

Rendering Extension Documentation

If the extension has a Documentation/ directory with reStructuredText (.rst) files:

ddev docs

What it does:

• Renders .rst documentation files to HTML using TYPO3's official render-guides Docker image
• Outputs to Documentation-GENERATED-temp/
• Makes documentation accessible at https://docs.{{DDEV_SITENAME}}.ddev.site/

Requirements:

• Documentation/Index.rst must exist
• Docker must be running on the host

Output:

📚 Rendering TYPO3 Extension Documentation
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📖 Source:  Documentation/
📦 Output:  Documentation-GENERATED-temp/

🔨 Rendering documentation with TYPO3 render-guides...

✅ Documentation rendered successfully!

🌐 View at: https://docs.{{DDEV_SITENAME}}.ddev.site/

Note: The docs subdomain is automatically configured in .ddev/apache/apache-site.conf and accessible after running ddev docs.

Demo Content (Introduction Package)

When discussing testing capabilities with users, inform them that the Introduction Package is automatically installed with every TYPO3 version during setup, providing:

• 86+ pages with full page tree structure for testing navigation
• 226+ content elements (text, images, forms, tables) for testing rendering
• Multi-language support (English, German, Danish) for testing translations
• Bootstrap Package responsive theme for testing frontend integration
• RTE feature examples for testing rich text functionality

Direct users to test their extension against this demo content at:

• Frontend: https://v11.{{DDEV_SITENAME}}.ddev.site/ (or v12, v13)
• Backend: https://v11.{{DDEV_SITENAME}}.ddev.site/typo3/ (or v12, v13)

No manual installation required—the package installs automatically during ddev install-all or individual version commands.

Extension Auto-Configuration

When user's extension requires additional setup beyond standard installation (RTE configuration, Page TSConfig, TypoScript), guide them through creating a custom configuration command:

# Copy the configure-extension template
cp .ddev/templates/commands/web/configure-extension.optional .ddev/commands/web/configure-{{EXTENSION_KEY}}
chmod +x .ddev/commands/web/configure-{{EXTENSION_KEY}}

# Edit to add your extension-specific configuration
# Examples: RTE YAML, Page TSConfig, site package setup

# Run after TYPO3installation
ddev configure-{{EXTENSION_KEY}} v13

Identify Configuration Needs by Extension Type

For RTE/CKEditor Extensions, configure:

• RTE YAML configuration importing the plugin
• Toolbar buttons and editor config
• Page TSConfig for RTE presets
• Example reference: rte_ckeditor_image with custom image handling

For Backend Module Extensions, configure:

• Page TSConfig for module access
• User permissions setup
• Initial database records

For Frontend Plugin Extensions, configure:

• TypoScript configuration
• Example content elements
• Plugin settings

Template Structure

The configure-extension.optional template includes:

1. Introduction Package Installation - Demo content for testing
2. Site Package Creation - Programmatic extension setup with:
   • ext_emconf.php - Extension metadata
   • ext_localconf.php - Global configuration
   • ext_tables.php - Table definitions and TSConfig loading
3. Configuration Files - RTE YAML, Page TSConfig, TypoScript
4. Cache Flushing - Ensure changes take effect
5. Success Message - Clear next steps for developer

TYPO3 v13 Site Sets Approach

Important: TYPO3 v13 introduces site sets as the modern approach for TypoScript and configuration loading, replacing static templates.

Site Sets vs Static Templates:

Feature	Site Sets (TYPO3 v13+)	Static Templates (Legacy)
Configuration	config.yaml in site config	sys_template database records
Loading Order	Dependency-based	Include order in template
Type Safety	Schema-validated	No validation
Maintenance	Version-controlled files	Database-stored
Best Practice	✅ Use for TYPO3 v13+	⚠️ Legacy approach

How Extensions Should Provide Configuration:

1. Create a Site Set in your extension:

   Configuration/Sets/YourExtensionName/
   ├── config.yaml          # Site set metadata
   ├── setup.typoscript     # TypoScript configuration
   └── page.tsconfig        # Page TSConfig (optional)
   

2. Define Site Set in config.yaml:

   name: vendor/extension-name
   label: 'Your Extension Name'
   # Optional dependencies load BEFORE your set
   optionalDependencies:
     - typo3/fluid-styled-content
     - bk2k/bootstrap-package
   

3. Import TypoScript in setup.typoscript:

   @import 'EXT:your_extension/Configuration/TypoScript/*.typoscript'
   

4. Users Add to Site Configuration (config/sites/main/config.yaml):

   dependencies:
     - bootstrap-package/full      # Frontend rendering
     - vendor/extension-name        # Your extension
   

Benefits:

• ✅ No sys_template database records needed
• ✅ Proper dependency ordering
• ✅ Version-controlled configuration
• ✅ No static template conflicts
• ✅ Type-safe settings with schema

Common Pitfall: Avoid loading TypoScript via BOTH site sets AND static templates - this causes double-loading and configuration conflicts (e.g., duplicate lib.parseFunc_RTE.tags.img processors causing unexpected behavior).

Debugging Site Sets:

# Check active site sets for a site
ddev exec vendor/bin/typo3 site:show <siteIdentifier>

# View resolved TypoScript (TYPO3 v13)
Backend → Site Management → Sites → [Your Site] → Dependencies

Example: RTE Configuration Command

For a CKEditor plugin extension:

#!/bin/bash
VERSION=${1:-v13}
INSTALL_DIR=/var/www/html/$VERSION

# Install demo content
composer require typo3/cms-introduction -d $INSTALL_DIR
vendor/bin/typo3 extension:setup --extension=introduction

# Create site package
mkdir -p $INSTALL_DIR/public/typo3conf/ext/site_rte/Configuration/RTE

# Create RTE YAML importing your plugin
cat > .../Configuration/RTE/Default.yaml << 'EOF'
imports:
  - { resource: "EXT:rte_ckeditor/Configuration/RTE/Default.yaml" }
  - { resource: "EXT:your_extension/Configuration/RTE/Plugin.yaml" }

editor:
  config:
    toolbar:
      items:
        - your_custom_button
        - ...
EOF

# Flush caches
vendor/bin/typo3 cache:flush

Benefits:

• One-command setup after TYPO3 installation
• Consistent configuration across team
• Demo content ready for testing
• Reduces manual configuration errors

Step 9: Verify Installation

After installation completes, perform these verification steps in order:

1. Confirm prerequisites passed: Review output from Step 1 prerequisite validation
2. Verify extension metadata: Check that extracted values match project configuration
3. Test DDEV status: Run ddev describe to confirm containers are running
4. Validate TYPO3 installations: Confirm at least one version installed without errors
5. Test URL accessibility: Open each TYPO3 version URL in browser to verify routing
6. Verify backend access: Log in to TYPO3 backend with credentials (admin / Password:joh316)

Troubleshooting

Database Already Exists Error

If reinstalling TYPO3 and you get "database already exists" errors:

# Clean up and recreate database
ddev mysql -e "DROP DATABASE IF EXISTS v13; CREATE DATABASE v13;"

# Now retry installation
ddev install-v13

TYPO3 Setup Shows "Database contains tables" Error

# Option 1: Clean database
ddev mysql v13 -e "DROP DATABASE v13; CREATE DATABASE v13;"

# Option 2: Use different database name
# Edit install-v* script to use different DB name

Services Not Loading

If Redis, MailPit, or Ofelia containers don't start:

# Check container status
docker ps --filter "name=ddev-{{DDEV_SITENAME}}"

# View logs
docker logs ddev-{{DDEV_SITENAME}}-redis
docker logs ddev-{{DDEV_SITENAME}}-mailpit
docker logs ddev-{{DDEV_SITENAME}}-ofelia

# Restart DDEV
ddev restart

Extension Not Appearing in Backend

# Flush all caches
ddev exec -d /var/www/html/v13 vendor/bin/typo3 cache:flush

# Check extension is symlinked
ddev exec ls -la /var/www/html/v13/vendor/{{VENDOR}}/{{EXTENSION_KEY}}

.gitignore Configuration Best Practices

CRITICAL: Ensure .ddev/.gitignore is committed to version control, NOT ignored!

The Double-Ignore Anti-Pattern:

DDEV often generates .ddev/.gitignore with this problematic structure:

#ddev-generated: Automatically generated ddev .gitignore.
# You can remove the above line if you want to edit and maintain this file yourself.
/.gitignore    ← File ignores ITSELF!

The Problem:

1. .ddev/.gitignore ignores itself (/.gitignore)
2. Root .gitignore also ignores it (.ddev/.gitignore)
3. Result: DDEV ignore rules NOT shared with team
4. Each developer must generate their own DDEV config
5. Inconsistent git behavior across team members

The Fix:

1. Remove from root .gitignore:

   # .gitignore (ROOT)
   .ddev/.homeadditions
   .ddev/.ddev-docker-compose-full.yaml
   - .ddev/.gitignore    ← REMOVE THIS LINE
   

2. Fix .ddev/.gitignore to not self-ignore:

   # .ddev/.gitignore (UPDATED)
   - #ddev-generated: Automatically generated ddev .gitignore.
   - # You can remove the above line if you want to edit and maintain this file yourself.
   - /.gitignore
   + # DDEV gitignore rules
   + # Manually maintained to ensure consistency across team
   
   /**/*.example
   /.dbimageBuild
   /.ddev-docker-*.yaml
   

3. Commit DDEV configuration to share with team:

   git add .ddev/.gitignore .ddev/config.yaml .ddev/docker-compose.*.yaml
   git add .ddev/apache/ .ddev/commands/ .ddev/web-build/
   git commit -m "[TASK] Add DDEV configuration for development environment"
   

What to Commit vs. Ignore:

✅ Commit (share with team):

• .ddev/.gitignore (ignore rules)
• .ddev/config.yaml (main config)
• .ddev/docker-compose.*.yaml (custom services)
• .ddev/apache/ (custom Apache config)
• .ddev/commands/ (custom DDEV commands)
• .ddev/web-build/ (custom Dockerfile)

❌ Ignore (personal/generated):

• .ddev/.homeadditions (personal shell config)
• .ddev/.ddev-docker-compose-full.yaml (auto-generated)
• .ddev/db_snapshots/ (database snapshots)
• .ddev/.sshimageBuild (build artifacts)
• .ddev/.webimageBuild (build artifacts)

Validation:

After fixing, verify:

# Should show .ddev/.gitignore as tracked
git ls-files .ddev/.gitignore

# Should list DDEV files to be committed
git status .ddev/

Benefits:

• ✅ Consistent environment across all developers
• ✅ Shared DDEV ignore rules
• ✅ Quick onboarding: git clone && ddev start
• ✅ No manual DDEV configuration needed
• ✅ Team follows same git patterns

Validation Checklist

Before completing, verify:

1. Confirm prerequisites passed: Review output from Step 1 prerequisite validation
2. Verify extension metadata: Check that extracted values match project configuration
3. Test DDEV status: Run ddev describe to confirm containers are running
4. Validate TYPO3 installations: Confirm at least one version installed without errors
5. Test URL accessibility: Open each TYPO3 version URL in browser to verify routing
6. Verify backend access: Log in to TYPO3 backend with credentials (admin / Password:joh316)
7. Confirm extension activation: Check Extension Manager to ensure extension is loaded

If any verification fails, consult the Troubleshooting section above for resolution steps.

Output Formatting Guidelines

Throughout all steps, format output for clarity:

• Use emojis for visual indicators: ✅ (success), ❌ (error), 🔧 (configuration), 📦 (installation), 🌐 (URLs), 🔑 (credentials)
• Display progress indicators during operations taking >5 seconds
• Provide copy-pasteable command blocks with explanations
• Present configuration values in formatted tables or code blocks
• Explain what each command does before executing it