README

A Claude Code skill for automating DDEV environment setup in TYPO3 extension projects

Overview

This skill helps TYPO3 extension developers quickly set up a complete DDEV development environment with multiple TYPO3 versions. Instead of manually configuring DDEV, this skill automates the entire process - from detecting your extension metadata to generating all configuration files and installing TYPO3.

What It Does

✅ Detects TYPO3 extension projects automatically
✅ Extracts extension metadata (key, package name, namespace)
✅ Generates complete DDEV configuration
✅ Creates multi-version TYPO3 testing environment (11.5, 12.4, 13.4 LTS)
✅ Provides backend and frontend access with preconfigured credentials
✅ Includes custom DDEV commands for easy TYPO3 installation

Who It's For

TYPO3 extension developers
Teams working on TYPO3 extensions
Developers needing to test extensions across multiple TYPO3 versions
Anyone wanting a quick, reproducible TYPO3 development environment

Prerequisites

Before using this skill, ensure you have:

DDEV installed
Docker running
A TYPO3 extension project (with ext_emconf.php or composer.json)
Claude Code installed

Installation

Option 1: Via Netresearch Marketplace (Recommended)

/plugin marketplace add netresearch/claude-code-marketplace

Then browse skills with /plugin.

Option 2: Download Release

Download the latest release and extract to ~/.claude/skills/typo3-ddev/

Option 3: Manual Installation

# Clone this repository into your Claude Code skills directory
cd ~/.claude/skills/
git clone https://github.com/netresearch/typo3-ddev-skill.git

# The skill is now available in Claude Code

Usage

In Claude Code

Once installed, simply invoke the skill in your TYPO3 extension project:

/typo3-ddev

Or ask Claude:

Set up DDEV for my TYPO3 extension

The skill will:

Validate prerequisites (DDEV, Docker, TYPO3 extension structure)
Extract your extension metadata
Confirm configuration with you
Generate all .ddev/ files with proper values
Guide you through starting DDEV and installing TYPO3

What You'll Get

After setup, you'll have:

project-root/
├── .ddev/
│   ├── config.yaml
│   ├── docker-compose.web.yaml
│   ├── apache/
│   │   └── apache-site.conf
│   ├── web-build/
│   │   └── Dockerfile
│   └── commands/
│       └── web/
│           ├── install-v11
│           ├── install-v12
│           ├── install-v13
│           └── install-all
├── Classes/
├── Configuration/
├── ext_emconf.php
└── composer.json

Accessing Your Environment

Once installed, access TYPO3 at:

Overview Dashboard:

https://your-ext.ddev.site/

TYPO3 11.5 LTS:

Frontend: https://v11.your-ext.ddev.site/
Backend: https://v11.your-ext.ddev.site/typo3/

TYPO3 12.4 LTS:

Frontend: https://v12.your-ext.ddev.site/
Backend: https://v12.your-ext.ddev.site/typo3/

TYPO3 13.4 LTS:

Frontend: https://v13.your-ext.ddev.site/
Backend: https://v13.your-ext.ddev.site/typo3/

Backend Credentials

Username: admin
Password: Joh316!

Custom DDEV Commands

The skill creates these custom commands:

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

# Install all versions at once
ddev install-all

# Install Introduction Package (demo content)
ddev install-introduction v13

Adding Demo Content

Test your extension with realistic content using the TYPO3 Introduction Package:

# Install Introduction Package
ddev install-introduction v13

Includes:

86+ pages with example content
226+ content elements (text, images, forms, tables)
Multi-language support (EN, DE, DA)
Bootstrap Package responsive theme
Perfect for testing RTE features

Extension Auto-Configuration

For extensions needing additional setup (RTE config, TSconfig, TypoScript), create a custom configuration command:

# Copy template
cp .ddev/templates/commands/web/configure-extension.optional \
   .ddev/commands/web/configure-myext

# Customize for your extension's needs
# Add: RTE YAML, Page TSConfig, TypoScript, site package setup

# Run after TYPO3 installation
ddev configure-myext v13

Use Cases:

RTE/CKEditor plugins - Configure toolbar, import plugin YAML
Backend modules - Set up TSconfig, permissions
Frontend plugins - TypoScript configuration, example content

Pattern Benefits:

One-command post-install setup
Consistent team configuration
Includes demo content automatically
Reduces manual configuration errors

See SKILL.md for detailed examples and template structure.

Troubleshooting

Database Already Exists

If reinstalling TYPO3:

ddev mysql -e "DROP DATABASE IF EXISTS v13; CREATE DATABASE v13;"
ddev install-v13

Services Not Starting

Check and restart services:

docker ps --filter "name=ddev-your-ext"
ddev restart

Extension Not Visible

Flush caches:

ddev exec -d /var/www/html/v13 vendor/bin/typo3 cache:flush

Architecture

The setup creates a unique multi-version environment:

Extension Source: Mounted at /var/www/{{EXTENSION_KEY}} (your project root)
TYPO3 Installations: Separate directories for each version (/var/www/html/v11, v12, v13)
Extension Installation: Installed via Composer path repository in each TYPO3 version
Persistent Data: Docker volumes for each TYPO3 version database and files

This architecture allows you to:

Develop extension code in your project root
Test immediately across all TYPO3 versions
Keep TYPO3 installations separate and clean
Avoid committing TYPO3 core files to your extension repository

Configuration

Supported TYPO3 Versions

By default, the skill supports:

TYPO3 11.5 LTS (PHP 8.0+)
TYPO3 12.4 LTS (PHP 8.1+)
TYPO3 13.4 LTS (PHP 8.2+)

PHP version is set to 8.2 for maximum compatibility.

Customization

After generation, you can customize:

PHP Version (.ddev/config.yaml):

php_version: "8.3"  # Change to 8.1 or 8.3 if needed

XDebug (enable/disable):

ddev xdebug on   # Enable
ddev xdebug off  # Disable

Database (Tiered Selection: SQLite/MariaDB/PostgreSQL/MySQL):

The skill uses intelligent tiered database selection based on extension complexity:

🎯 Tier 1: SQLite (Simple Extensions - Development Optimized)

For extensions using only TYPO3 Core APIs (no custom tables, no raw SQL):

# No .ddev/config.yaml database config needed
# TYPO3 installation automatically uses SQLite

Benefits:

⚡ Startup: 5-10 seconds faster per ddev start
💾 RAM: 900 MB saved (no container)
💿 Disk: 744 MB saved
🔒 Perfect v11/v12/v13 isolation

⚠️ Development ONLY - Never use SQLite in production. Switch to MariaDB for final testing.

🔧 Tier 2: MariaDB 10.11 (Complex Extensions - Production Parity)

For extensions with custom tables, raw SQL, or unknown complexity:

# Default for complex extensions (.ddev/config.yaml)
database:
  type: mariadb
  version: "10.11"

Why MariaDB 10.11? Production standard (95% hosting), extension compatibility, 13-36% faster than MySQL 8.

🌐 Tier 3 & 4: Specialized Databases

# PostgreSQL 16 (for GIS, analytics, full-text search)
database:
  type: postgres
  version: "16"

# MariaDB 11 (forward-looking performance)
database:
  type: mariadb
  version: "11.4"

# MySQL 8.0 (corporate/Oracle ecosystem)
database:
  type: mysql
  version: "8.0"

For detailed rationale, see docs/adr/0002-mariadb-default-with-database-alternatives.md.

Caching Service (Valkey or Redis):

The skill provides Valkey 8 as the default caching service (open source, future-proof):

# Default: Valkey 8
cp .ddev/templates/docker-compose.services.yaml.optional .ddev/docker-compose.services.yaml

# Alternative: Redis 7 (for legacy production parity)
cp .ddev/templates/docker-compose.services-redis.yaml.optional .ddev/docker-compose.services.yaml

# Restart DDEV
ddev restart

Why Valkey? True open source (BSD-3), AWS/Google/Oracle backing, 30% smaller than Redis 8, cost-effective. See docs/adr/0001-valkey-default-with-redis-alternative.md for details.

Additional Services (add to .ddev/docker-compose.services.yaml):

# The services template includes: Valkey/Redis, MailPit, Ofelia
# See SKILL.md for complete documentation

Troubleshooting

DDEV Won't Start

Port Conflicts:

# Check what's using ports 80/443
sudo lsof -i :80
sudo lsof -i :443

# Option 1: Stop conflicting services
# Option 2: Change ports in .ddev/config.yaml
router_http_port: "8080"
router_https_port: "8443"

Installation Fails

Check Composer Issues:

ddev ssh
composer diagnose

View Installation Logs:

ddev logs

Retry Installation:

# For specific version
ddev ssh
rm -rf /var/www/html/v13/*
exit
ddev install-v13

Extension Not Appearing

Verify Extension Key:

ddev ssh
echo $EXTENSION_KEY  # Should match your ext_emconf.php

Check Composer Repository:

ddev ssh
cd /var/www/html/v13
composer config repositories

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Credits

This skill is based on the excellent work by Armin Vieweg in ddev-for-typo3-extensions.

Additional Resources

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
TYPO3 Slack: #ddev channel

Made with ❤️ for the TYPO3 Community by Netresearch DTT GmbH

netresearch / agent-typo3-ddev

Maintainers

Details

README

Overview

What It Does

Who It's For

Prerequisites

Installation

Option 1: Via Netresearch Marketplace (Recommended)

Option 2: Download Release

Option 3: Manual Installation

Usage

In Claude Code

What You'll Get

Accessing Your Environment

Backend Credentials

Custom DDEV Commands

Adding Demo Content

Extension Auto-Configuration

Troubleshooting

Database Already Exists

Services Not Starting

Extension Not Visible

Architecture

Configuration

Supported TYPO3 Versions

Customization

Troubleshooting

DDEV Won't Start

Installation Fails

Extension Not Appearing

Contributing

Credits

Additional Resources

License

Support