zhongwei/gh-netresearch-claude-code-marketplace-skills-typo3-ddev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:43:27 +08:00
commit e082963336
43 changed files with 6129 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

414
references/0001-valkey-default-with-redis-alternative.md Normal file
View File

@@ -0,0 +1,414 @@
# ADR 0001: Default to Valkey with Redis Alternative
**Status:** Accepted
**Date:** 2025-10-22
**Decision Makers:** TYPO3 DDEV Skill Maintainers
**Tags:** #caching #infrastructure #licensing #future-proofing
---
## Context
### The Redis Licensing Change (March 2024)
Redis changed its license from BSD-3-Clause (open source) to a dual RSALv2/SSPLv1 license, which is NOT OSI-approved open source. This change:
- Restricts commercial use of Redis as a managed service
- Creates legal compliance concerns for cloud providers and hosting companies
- Prevents offering Redis-as-a-service without Redis Ltd licensing agreements
### The Valkey Fork (March 2024)
In response, the Linux Foundation launched Valkey, a fork of Redis 7.2.4, with backing from:
- Amazon Web Services (AWS)
- Google Cloud
- Oracle Cloud
- Ericsson
- Snap Inc.
- 40+ additional companies
Valkey maintains BSD-3-Clause licensing (true open source) and wire-protocol compatibility with Redis.
### Cloud Provider Adoption
**AWS ElastiCache** (October 2024):
- Added Valkey 7.2 support
- Added Valkey 8.0 support (November 2024)
- Pricing: 20% lower for node-based, 33% lower for serverless vs Redis
- Performance: Claims 230% higher throughput, 70% better latency (Valkey 8.0 vs 7.2)
**Industry Trajectory:**
- AWS MemoryDB supports Valkey
- Google Cloud and Oracle are Valkey project sponsors
- Economic pressure (20-33% cost savings) will drive hosting provider migration
### TYPO3 Caching Requirements
TYPO3's Redis cache backend uses basic operations:
- `GET`, `SET`, `DEL`, `EXPIRE` - Key-value operations
- `FLUSHDB` - Cache clearing
- `KEYS` pattern matching - Cache inspection
These operations are **identical** in Redis and Valkey (wire-protocol compatible). TYPO3 does not use advanced Redis features (Streams, JSON, Search, etc.).
### DDEV Development Environment Context
The TYPO3 DDEV Skill provides a reference implementation for local development environments. Developers using this skill:
- Test TYPO3 extensions locally before production deployment
- Do not control production infrastructure (clients/hosting providers do)
- Need development environments that match future production reality
- Benefit from faster Docker image pulls (smaller images = faster `ddev start`)
---
## Decision
**Default to Valkey 8-alpine for new TYPO3 DDEV projects, with Redis 7-alpine as a documented alternative.**
### Implementation Details
#### Default Configuration
```yaml
# .ddev/docker-compose.services.yaml (new projects)
services:
valkey:
container_name: ddev-${DDEV_SITENAME}-valkey
image: valkey/valkey:8-alpine
restart: unless-stopped
ports:
- "6379"
volumes:
- valkey-data:/data
environment:
- VALKEY_MAXMEMORY=256mb
- VALKEY_MAXMEMORY_POLICY=allkeys-lru
command: valkey-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
volumes:
valkey-data:
name: "${DDEV_SITENAME}-valkey-data"
```
#### Alternative: Redis 7-alpine
```yaml
# Alternative for legacy production parity
services:
redis:
container_name: ddev-${DDEV_SITENAME}-redis
image: redis:7-alpine
# ... same configuration structure
```
#### Auto-Detection Logic
For existing projects with `.ddev/docker-compose.services.yaml`:
- **Preserve existing choice**: If Redis is detected, keep Redis
- **Preserve existing choice**: If Valkey is detected, keep Valkey
- **Inform user**: Log which cache service was detected and preserved
For new projects:
- **Default to Valkey 8-alpine**
- **Document Redis alternative**: Show how to switch in generated README
- **Provide rationale**: Explain why Valkey is the forward-looking choice
---
## Consequences
### Positive
✅ **Future-Proof Development Environments**
- Matches the production trajectory (AWS/Google/Oracle adoption)
- Prepares developers for 2025-2027 hosting landscape
- Reduces future migration friction when hosting providers switch
✅ **Cost Awareness**
- Educates developers about cost-effective infrastructure choices
- Aligns with hosting provider economic incentives (20-33% savings)
- Demonstrates modern cloud architecture patterns
✅ **True Open Source**
- BSD-3-Clause license with no commercial restrictions
- No legal compliance concerns for hosting providers
- Community-driven governance (Linux Foundation)
✅ **Smaller Docker Images**
- Valkey 8-alpine: **69.7 MB**
- Redis 8-alpine: 100 MB (30% larger)
- Redis 7-alpine: 60.6 MB
- Faster `ddev start` cycles during development
✅ **Drop-In Compatibility**
- Wire-protocol identical to Redis
- TYPO3's PHP redis extension works without modification
- Zero code changes required for TYPO3 extensions
- Easy rollback to Redis if needed (one-line change)
### Negative
⚠️ **Newer Codebase**
- Valkey fork is only 1 year old (since March 2024)
- Less Stack Overflow content compared to Redis
- Potential for undiscovered edge-case bugs
**Mitigation:**
- Based on Redis 7.2.4 (stable, battle-tested codebase)
- AWS/Google/Oracle using in production validates stability
- DDEV makes switching back to Redis trivial (one-line change)
- Redis documentation applies due to protocol compatibility
⚠️ **Learning Curve**
- Developers familiar with "Redis" terminology need to learn "Valkey"
- Some confusion about naming/branding
**Mitigation:**
- Comprehensive ADR and documentation explains context
- Clear instructions for both Valkey and Redis alternatives
- Educational opportunity to teach open source licensing issues
⚠️ **Current Production Mismatch**
- Some existing TYPO3 hosting environments still use Redis 7.x
- Development-production parity temporarily impacted
**Mitigation:**
- Redis 7-alpine documented as alternative for production parity
- Auto-detection preserves existing Redis choice in projects
- Easy to switch (one-line change in docker-compose)
- Trade-off: Match today's production vs prepare for tomorrow's
### Risks and Mitigations
| Risk | Severity | Likelihood | Mitigation |
|------|----------|------------|------------|
| Valkey compatibility issues with TYPO3 | Low | Very Low | Wire-protocol identical, PHP redis extension works transparently |
| Valkey bugs in production use | Medium | Low | AWS/Google production usage validates stability; easy rollback |
| Developer confusion/resistance | Low | Medium | Clear documentation, explain rationale, provide Redis alternative |
| Community backlash for being "too progressive" | Low | Low | Document decision thoroughly, auto-preserve existing choices |
---
## Alternatives Considered
### Alternative 1: Redis 7-alpine Default (Conservative)
**Reasoning:**
- Most existing TYPO3 hosting uses Redis 7.x
- Maximum development-production parity today
- Battle-tested, 15 years of production use
- Familiar to developers
**Rejected Because:**
- Optimizes for yesterday's production, not tomorrow's
- Ignores industry trajectory (AWS/Google/Oracle Valkey adoption)
- Creates educational debt (developers learn old patterns)
- Proprietary licensing creates compliance concerns
- Misses opportunity to lead the transition
### Alternative 2: Redis 8-alpine Default
**Reasoning:**
- Latest Redis version
- Performance improvements over Redis 7
**Rejected Because:**
- Proprietary licensing (same as Redis 7.4+)
- Larger image size (100 MB vs 69.7 MB Valkey)
- More expensive on cloud providers vs Valkey
- Not the strategic direction of major cloud platforms
### Alternative 3: No Caching Service by Default
**Reasoning:**
- Simpler default setup
- Developers add only if needed
**Rejected Because:**
- Redis/Valkey caching is common in TYPO3 production
- Reference implementation should include production-realistic services
- DDEV skill aims to provide complete development environment
- Adding later is more friction than having it by default
### Alternative 4: Offer Both Redis and Valkey as Equal Choices
**Reasoning:**
- Maximum flexibility
- No opinionated defaults
**Rejected Because:**
- Adds complexity to setup process
- Forces developers to make decision without context
- Reference implementations should have opinionated best practices
- Still need to pick ONE as default for generation
- Documentation burden increases (maintain two equal paths)
---
## References
### Technical Documentation
- [Valkey Official Site](https://valkey.io/)
- [Valkey GitHub Repository](https://github.com/valkey-io/valkey)
- [AWS ElastiCache for Valkey Announcement](https://aws.amazon.com/about-aws/whats-new/2024/10/amazon-elasticache-valkey/)
- [TYPO3 Redis Cache Backend Documentation](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/CachingFramework/Backends/Index.html)
### Benchmarks and Analysis
- AWS ElastiCache Valkey 8.0: 230% throughput improvement, 70% latency improvement vs Valkey 7.2
- AWS Cost Comparison: Valkey 20% cheaper (node-based), 33% cheaper (serverless) vs Redis
- Docker Image Sizes:
- `valkey/valkey:8-alpine` - 69.7 MB
- `redis:8-alpine` - 100 MB
- `redis:7-alpine` - 60.6 MB
### Licensing
- Redis License Change: [Redis Announcement (March 2024)](https://redis.io/blog/redis-adopts-dual-source-available-licensing/)
- Valkey License: BSD-3-Clause (OSI-approved open source)
- Linux Foundation Valkey Announcement: [TechCrunch Article](https://techcrunch.com/2024/03/31/why-aws-google-and-oracle-are-backing-the-valkey-redis-fork/)
---
## Decision Rationale Summary
This decision is **strategic and forward-looking** rather than purely technical:
1. **Technical Equivalence**: For TYPO3 use cases, Redis and Valkey are functionally identical
2. **Strategic Positioning**: Major cloud providers (AWS, Google, Oracle) are adopting Valkey
3. **Economic Reality**: 20-33% cost savings will drive hosting provider migration
4. **Licensing Safety**: True open source (BSD-3) vs proprietary licensing concerns
5. **Educational Leadership**: Skill should teach future patterns, not legacy patterns
6. **Risk Mitigation**: Easy rollback, auto-preservation of existing choices, clear documentation
**The default to Valkey is a bet on the industry trajectory being correct, backed by Linux Foundation + AWS + Google + Oracle. The risk is minimal (easy rollback), and the educational benefit is high (teaching developers about open source licensing, cost-effective infrastructure, and future-proof choices).**
---
## Valkey 9.0 Consideration (October 2025)
**Release Information:**
- **Valkey 9.0 GA:** Released October 21, 2025
- **Status:** Stable production release
- **Docker Image:** `valkey/valkey:9-alpine` available
### Performance Improvements
**Throughput:**
- **40% higher throughput** compared to Valkey 8.1
- Supports **over 1 billion requests per second** in cluster configurations
- Memory prefetching for pipelined commands
- Zero-copy responses for large requests
- SIMD optimizations (up to 200% faster BITCOUNT, hyperloglog)
- Multipath TCP support (up to 25% lower latency)
### Major New Features
**Hash Field Expiration:**
- TTL on individual fields within a hash
- Automatic expired data removal
- Improved memory efficiency
**Atomic Slot Migration:**
- Snapshot-based migration for horizontal scaling
- Zero-downtime scaling
- Source and target nodes remain active during transfer
**Multiple Databases in Cluster Mode:**
- Multiple logical namespaces on single cluster
- Better keyspace organization
- Reduced memory waste
### Production Adoption Status
**Cloud Provider Support (as of October 2025):**
- ❌ **AWS ElastiCache:** Not yet supported (latest: Valkey 8.1 - July 2025)
- ❌ **Google Cloud:** No announcement
- ❌ **Oracle Cloud:** No announcement
**Docker Hub:**
- ✅ Official images available: `valkey/valkey:9.0-alpine`
- ✅ Wire-protocol compatible with Valkey 8.x and Redis 7.x
### Decision: Stay with Valkey 8 for Now
**Rationale:**
This differs from the original Valkey vs Redis decision:
- **Valkey vs Redis (Original):** Industry was MIGRATING → Lead with Valkey 8
- **Valkey 8 vs 9 (Now):** Industry STABLE on 8 → Follow production
**Why wait for Valkey 9:**
1. **Production Parity:** AWS ElastiCache only supports up to Valkey 8.1
2. **Very New:** Released October 21, 2025 (1 day old at time of writing)
3. **Hosting Adoption:** No TYPO3 hosting providers using Valkey 9 yet
4. **Upgrade Urgency:** GitHub release notes state "LOW" urgency
5. **Battle-Testing:** Valkey 8.x more production-proven
**Benefits of Staying on Valkey 8:**
- ✅ Cloud provider support (AWS ElastiCache available)
- ✅ Production-aligned (matches hosting environments)
- ✅ Battle-tested (in production since November 2024)
- ✅ Conservative approach (let others find bugs first)
**When to Upgrade to Valkey 9:**
Monitor for these signals:
1. **AWS ElastiCache announces Valkey 9 support**
2. **3+ months of production stability reports**
3. **Major TYPO3 hosting providers adopt Valkey 9**
4. **Performance improvements become critical for use case**
### Upgrade Path
**Seamless Migration (when ready):**
Valkey 8 → 9 upgrade is simple (wire-compatible):
```yaml
# Change from:
image: valkey/valkey:8-alpine
# To:
image: valkey/valkey:9-alpine
```
No configuration changes required. No data migration needed. Restart container.
**Trade-offs:**
- **Wait:** Production parity, battle-tested, conservative (recommended)
- **Upgrade Now:** 40% faster, cutting-edge, slightly risky
**Recommendation:** Wait for AWS ElastiCache support before defaulting to Valkey 9 in skill templates.
---
## Review and Updates
**Next Review Date:** 2026-04-01 (6 months from October 2025)
**Trigger for Re-evaluation:**
- Major TYPO3 hosting providers publicly announce Redis-only support policies
- Valkey compatibility issues discovered affecting TYPO3
- Valkey project loses major sponsor backing
- Cloud provider pricing changes making Redis competitive again
**Success Metrics:**
- Developer feedback on Valkey default (GitHub issues, discussions)
- Number of projects switching from Valkey to Redis (indicates friction)
- Hosting provider announcements about Valkey adoption
- TYPO3 community discussion about cache backends
---
**Approved By:** TYPO3 DDEV Skill Project
**Implementation:** v2.0.0 (target release)

651
references/0002-mariadb-default-with-database-alternatives.md Normal file
View File

@@ -0,0 +1,651 @@
# ADR 0002: Tiered Database Selection for TYPO3 Extension Development
**Status:** Accepted (Revised 2025-01-22)
**Date:** 2024-12-22 (Original), 2025-01-22 (Revision 1)
**Decision Makers:** TYPO3 DDEV Skill Maintainers
**Tags:** #database #mariadb #postgresql #mysql #sqlite #tiered-selection #development-optimization
---
## Context
### Production vs Development Requirements
**Critical Distinction:** This ADR addresses **DDEV extension development environments**, NOT production hosting.
**Development Context (DDEV):**
- Single developer on localhost
- Fast iteration cycles (code → ddev restart → test → repeat)
- Resource efficiency matters (RAM, disk, startup time)
- Perfect isolation for multi-version testing (v11, v12, v13)
- No public internet exposure, no security concerns
- Human actions are sequential (seconds/minutes apart)
**Production Context (Hosting):**
- Multi-user concurrent access
- Public internet exposure with security requirements
- Uptime and reliability critical
- Performance under load matters
- 95%+ TYPO3 hosting uses MariaDB
**Key Insight:** Development and production have DIFFERENT requirements. Production-parity is important for complex extensions with custom SQL, but OVERKILL for simple extensions using only TYPO3 Core APIs.
### TYPO3 13 Database Support
TYPO3 13 officially supports four database systems:
- **MariaDB** >= 10.4.3 <= 11.0.0
- **MySQL** >= 8.0.17
- **PostgreSQL** >= 10.0
- **SQLite** >= 3.8.3
While all four are technically supported, production deployment patterns and ecosystem alignment vary significantly.
### Production Hosting Landscape
**Research Finding:** "Most TYPO3 customers prefer to use the MySQL/MariaDB database"
**European TYPO3 Hosting Providers:**
- **jweiland.net**: MariaDB 10.11, MariaDB 10.3 (MySQL 5.6 outdated)
- **mittwald**: MariaDB (primary offering)
- **TYPO3 Agency**: MariaDB (standard configuration)
- **platform.sh**: Supports all, but MariaDB most common for TYPO3
**Estimated Distribution:**
- MariaDB: **95%+** of TYPO3 production installations
- MySQL 8: <10% (mostly cloud providers, corporate environments)
- PostgreSQL: <5% (specialized use cases: GIS, analytics, full-text search)
- SQLite: 0% production (demo/testing only)
### SQLite for Development (Revision 1 Analysis)
**SQLite Capabilities for DDEV Development:**
TYPO3 13 officially supports SQLite >= 3.8.3, and modern PHP containers (Ubuntu/Debian) include SQLite 3.40+.
**Development Benefits:**
- **Startup Speed**: Instant (no container startup) vs 5-10 seconds for MariaDB
- **Resource Usage**: ~20 MB RAM vs ~200 MB RAM for MariaDB container
- **Disk Space**: 0 MB (PHP extension) vs 744 MB MariaDB container image
- **Isolation**: Perfect separation for v11/v12/v13 (separate .sqlite files)
- **Simplicity**: No container orchestration, no health checks
**SQLite WAL Mode (Write-Ahead Logging):**
- Available since SQLite 3.7.0 (TYPO3 requires >= 3.8.3)
- Enables concurrent READS during WRITES
- Multiple WRITES serialize but with better concurrency than default mode
- Addresses concurrent write concerns for single-developer localhost usage
**When SQLite is SUFFICIENT for Development:**
- Extension uses only TYPO3 Core APIs (Extbase, FAL, DataHandler)
- No custom raw SQL queries
- No custom database tables
- Human actions sequential (save → upload → clear cache) not truly concurrent
- Single developer localhost environment
**When SQLite is INSUFFICIENT:**
- Extension has custom database tables (ext_tables.sql)
- Extension uses raw SQL queries (database-specific syntax)
- Performance-critical operations requiring production-realistic testing
- Testing multi-user concurrent scenarios
**Developer Workflow Impact:**
```
Daily Workflow: 10x ddev restarts
- MariaDB: 10 × 10 seconds = 100 seconds waiting
- SQLite: 10 × 2 seconds = 20 seconds waiting
- Time saved: 80 seconds per day = 400 seconds per week
```
### Performance Benchmarks (2024)
**MariaDB vs MySQL 8:**
According to 2024 Sysbench benchmarks:
- MariaDB 11.4 performance is **13-36% faster** than MySQL 8.0
- Modern MySQL 8.0.36 gets only 66-84% throughput relative to older MySQL 5.6.51
- MySQL suffers from CPU overhead **1.38X larger** than MariaDB
- MariaDB maintains **stable performance** across 10 years and 14 releases
**PostgreSQL vs MariaDB:**
OLTP Benchmarks (HammerDB TPROC-C):
- PostgreSQL: **84% more orders** processed than MariaDB in payments-per-second tests
- PostgreSQL excels at **complex analytical queries** and parallel execution
- MariaDB shows **15-25% better performance** for transactional applications
- TYPO3 workload is primarily transactional (CRUD operations on content) → MariaDB advantage
**Key Insight:** PostgreSQL is technically superior for analytics, but TYPO3 is a CMS (transactional workload), not an analytics platform.
### Docker Image Sizes
Surprisingly, PostgreSQL has a **smaller image**:
| Database | Image | Size |
|----------|-------|------|
| PostgreSQL 16 | `postgres:16-alpine` | **394 MB** |
| MariaDB latest | `mariadb:latest` | 456 MB |
| MySQL 8 | `mysql:8` | ~500 MB |
| DDEV MariaDB 10.11 | `ddev/ddev-dbserver-mariadb-10.11` | 744 MB* |
*DDEV image includes TYPO3-specific tooling and optimizations
### Extension Compatibility Concerns
**Doctrine DBAL Abstraction:**
TYPO3 uses Doctrine DBAL to abstract database differences. In theory, extensions should work across all supported databases.
**Reality:**
1. **Raw SQL Bypass**: Extensions using raw SQL (not via Doctrine QueryBuilder) may assume MySQL/MariaDB syntax
2. **Testing Coverage**: Extension developers test primarily on MariaDB (95% hosting uses it)
3. **Syntax Differences**:
- MySQL/MariaDB: `DATE_FORMAT()`, `LIMIT offset, count`, `AUTO_INCREMENT`
- PostgreSQL: `TO_CHAR()`, `LIMIT count OFFSET offset`, `SERIAL`
**Risk:** Extensions with raw SQL may break on PostgreSQL but work fine on MariaDB.
### DDEV Database Support
DDEV provides native database configuration via `.ddev/config.yaml`:
```yaml
database:
type: mariadb # or: mysql, postgres
version: "10.11" # version string
```
**Migration Support:**
- **MySQL ↔ MariaDB**: `ddev debug migrate-database` (seamless migration)
- **MariaDB/MySQL → PostgreSQL**: Manual export/import (schema differences)
- **PostgreSQL → MariaDB/MySQL**: Manual export/import (schema differences)
**Implication:** Starting with MariaDB and needing PostgreSQL later is painful (data migration). Starting with PostgreSQL and needing MariaDB is equally painful. Must choose wisely upfront.
---
## Decision
**Use tiered database selection based on extension complexity for TYPO3 DDEV development environments.**
### Tier 1: SQLite (Default for Simple Extensions)
**Recommended for extensions that:**
- ✅ Have no custom database tables (ext_tables.sql absent or empty)
- ✅ Use only TYPO3 Core APIs (Extbase, FAL, DataHandler, Doctrine DBAL)
- ✅ Have no raw SQL queries
- ✅ Category: plugin, fe, be, misc
- ✅ File size < 1 MB
**Benefits:**
- ⚡ **Startup**: 5-10 seconds faster per ddev start
- 💾 **RAM**: 900 MB saved (no MariaDB container)
- 💿 **Disk**: 744 MB saved (no container image)
- 🔒 **Isolation**: Perfect separation for v11/v12/v13 databases
- 🎯 **Simplicity**: No container orchestration needed
**Critical Warnings:**
- ⚠️ **Development ONLY** - Never use SQLite in production
- ⚠️ **Switch to MariaDB** if you add custom SQL queries or tables
- ⚠️ **Final Testing** - Run compatibility tests on MariaDB before extension release
### Tier 2: MariaDB 10.11 (Default for Complex Extensions)
**Recommended for extensions that:**
- ❌ Have custom database tables (ext_tables.sql present)
- ❌ Use raw SQL queries (database-specific syntax)
- ❌ Performance-critical operations
- ❌ Category: services, module
- ❌ File size > 1 MB
**Benefits:**
- ✅ Production-realistic testing (95%+ TYPO3 hosting uses MariaDB)
- ✅ Better for concurrent operations
- ✅ Proper performance benchmarking
- ✅ Extension compatibility (99%+ extensions tested on MariaDB)
### Tier 3: PostgreSQL 16 (Explicit Requirements)
**Recommended for extensions that:**
- 🎯 Require GIS/spatial data (PostGIS)
- 🎯 Advanced analytics or complex queries
- 🎯 Extension explicitly requires PostgreSQL
### Tier 4: MySQL 8.0 (Corporate/Oracle Ecosystem)
**Recommended for:**
- 🏢 Corporate environments requiring Oracle ecosystem integration
- 🏢 Existing production environments using MySQL 8
**Implement auto-detection logic** to analyze extension complexity and suggest appropriate database tier.
### Implementation Details
#### Default Configuration Based on Extension Analysis
**For Simple Extensions (Tier 1):**
No `.ddev/config.yaml` database configuration needed (uses DDEV default PHP with SQLite)
TYPO3 installation command:
```bash
vendor/bin/typo3 setup \
--driver=pdo_sqlite \
--path=/var/www/html/v13/database.sqlite \
--admin-username=admin \
--admin-password='Password:joh316' \
--project-name="Extension Dev v13"
```
**For Complex Extensions (Tier 2):**
`.ddev/config.yaml`:
```yaml
database:
type: mariadb
version: "10.11"
```
TYPO3 installation command uses: `--driver=mysqli --host=db --dbname=v13`
#### Auto-Detection Logic
During extension metadata extraction:
```yaml
Extension Complexity Analysis:
1. SQLite Detection (Tier 1 - Simple Extension):
Checks:
✓ ext_tables.sql: Absent or empty
✓ Raw SQL patterns: None found (grep for executeQuery, $GLOBALS['TYPO3_DB'])
✓ File size: < 1 MB
✓ Category: plugin, fe, be, misc
→ Suggest SQLite (development-optimized)
2. MariaDB Detection (Tier 2 - Complex Extension):
Checks:
✗ ext_tables.sql: Present with table definitions
✗ Raw SQL patterns: Found
✗ File size: > 1 MB
✗ Category: services, module
→ Suggest MariaDB 10.11 (production-realistic)
3. PostgreSQL Detection (Tier 3 - Explicit Requirement):
Checks:
• Extension name: Contains "postgres", "pgsql", "pg_", "postgis"
• composer.json: Requires "typo3/cms-pgsql"
• Description: Keywords "GIS", "spatial", "analytics"
→ Suggest PostgreSQL 16 (specialized)
4. MySQL Detection (Tier 4 - Corporate):
Checks:
• composer.json: Requires "typo3/cms-mysql"
• Manual override only
→ Suggest MySQL 8.0 (corporate/Oracle ecosystem)
```
**User Confirmation (Simple Extension Example):**
```
Detected Database Configuration:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Database: SQLite (Tier 1)
Reason: Simple extension using only TYPO3 Core APIs
No custom tables, no raw SQL
Benefits:
⚡ Startup: 5-10 seconds faster per ddev start
💾 RAM: 900 MB saved
💿 Disk: 744 MB saved
🔒 Isolation: Perfect v11/v12/v13 separation
Warnings:
⚠️ Development ONLY (never production)
⚠️ Switch to MariaDB if adding custom SQL
⚠️ Run final tests on MariaDB before release
Alternatives:
• mariadb:10.11 - Production-realistic testing
• postgres:16 - GIS/analytics requirements
• mysql:8.0 - Oracle ecosystem
Proceed with SQLite? (y/n)
```
**User Confirmation (Complex Extension Example):**
```
Detected Database Configuration:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Database: MariaDB 10.11 (Tier 2)
Reason: Complex extension with custom tables
Found: ext_tables.sql with 3 custom tables
Benefits:
✅ Production-realistic (95%+ TYPO3 hosting)
✅ Extension compatibility (99%+ tested)
✅ Proper concurrent operation handling
Alternatives:
• sqlite - Faster development (not recommended for custom tables)
• postgres:16 - GIS/analytics requirements
• mysql:8.0 - Oracle ecosystem
Proceed with MariaDB 10.11? (y/n)
```
---
## Consequences
### Positive
✅ **Production Parity**
- 95%+ TYPO3 hosting uses MariaDB
- Development environment matches production reality
- Reduces deployment surprises and compatibility issues
✅ **Extension Compatibility**
- 99%+ TYPO3 extensions tested on MariaDB
- Minimizes risk of raw SQL incompatibilities
- Safer default for general extension development
✅ **TYPO3 Ecosystem Alignment**
- TYPO3 documentation examples use MariaDB
- Community tutorials assume MariaDB
- Developer familiarity (most TYPO3 devs know MySQL/MariaDB)
✅ **Performance for CMS Workload**
- MariaDB 13-36% faster than MySQL 8 for transactional operations
- TYPO3 workload is primarily CRUD (transactional), not analytical
- Optimal for typical CMS usage patterns
✅ **DDEV Standard**
- DDEV defaults to MariaDB for TYPO3 projects
- Ecosystem-aligned with DDEV best practices
- Smooth migration within MySQL/MariaDB family
✅ **Mature & Stable**
- MariaDB 10.11 is production-proven LTS release
- 15+ years of MySQL/MariaDB history
- Battle-tested with TYPO3 workloads
### Negative
⚠️ **Not Leveraging PostgreSQL Advantages**
- PostgreSQL has smaller image (394 MB vs 744 MB DDEV MariaDB)
- PostgreSQL superior for complex queries, analytics, GIS
- PostgreSQL has better ACID compliance and advanced features (JSONB, full-text, PostGIS)
- **Counter-argument:** TYPO3 extensions rarely need these features; production uses MariaDB anyway
⚠️ **MySQL 8 Performance Gap**
- MariaDB 13-36% faster than MySQL 8 in benchmarks
- MySQL 8 has CPU overhead issues
- Defaulting to MariaDB means MySQL users must explicitly switch
- **Counter-argument:** MySQL 8 only needed for Oracle ecosystem; MariaDB is better performer
⚠️ **Limited PostgreSQL Exposure**
- Developers don't experience PostgreSQL advantages
- PostgreSQL adoption in TYPO3 ecosystem remains low
- **Counter-argument:** Production reality dictates development choices; can't force ecosystem change from dev tools
### Risks and Mitigations
| Risk | Severity | Likelihood | Mitigation |
|------|----------|------------|------------|
| PostgreSQL-specific extension not detected | Medium | Low | Explicit naming conventions documented; manual override available |
| Extension breaks on PostgreSQL in production | High | Very Low | Production hosting uses MariaDB (95%+); PostgreSQL hosting rare |
| Developer unfamiliar with MariaDB | Low | Very Low | MySQL/MariaDB standard in web development; extensive documentation |
| MariaDB 10.x deprecated before TYPO3 14 | Low | Low | MariaDB 11 alternative documented; DDEV migration smooth |
| Missing out on PostgreSQL innovation | Low | Medium | PostgreSQL 16 documented and available; auto-detection suggests when appropriate |
---
## Alternatives Considered
### Alternative 1: PostgreSQL 16 Default
**Reasoning:**
- Technically superior database (ACID, advanced features)
- Smaller image size (394 MB vs 744 MB)
- Better for complex queries and analytics
- Future-proof with modern features
**Rejected Because:**
- ❌ Only ~5% of TYPO3 hosting uses PostgreSQL
- ❌ Extension compatibility risk (raw SQL, testing coverage)
- ❌ Development-production mismatch for 95% of deployments
- ❌ No industry migration trend (unlike Valkey case)
- ❌ TYPO3 workload is transactional, not analytical
- ❌ Higher learning curve for TYPO3 developers
- ❌ Counter to TYPO3 ecosystem standards
**Key Difference from Valkey Decision:**
- Valkey: Industry migrating TO new technology (AWS/Google/Oracle adopting)
- PostgreSQL: Industry STABLE on existing technology (95% MariaDB, no migration)
### Alternative 2: MySQL 8.0 Default
**Reasoning:**
- TYPO3 officially supports MySQL 8.0.17+
- Oracle corporate backing
- Window functions, CTEs, document store features
**Rejected Because:**
- ❌ MariaDB 13-36% faster in benchmarks
- ❌ MySQL 8 has CPU overhead issues (1.38X vs MariaDB)
- ❌ Less common than MariaDB in TYPO3 hosting
- ❌ Oracle licensing concerns (GPL but Oracle-controlled)
- ❌ MariaDB is better open-source governance (MariaDB Foundation)
- ❌ TYPO3 doesn't leverage MySQL 8 advanced features heavily
### Alternative 3: MariaDB 11.x Default
**Reasoning:**
- Performance improvements over MariaDB 10.x (+40% in benchmarks)
- TYPO3 13 supports up to MariaDB 11.0
- Forward-looking choice
**Rejected Because:**
- ⚠️ MariaDB 11.0 has breaking changes (removed features)
- ⚠️ Less production-proven than 10.11 LTS
- ⚠️ Most hosting still on MariaDB 10.x
- ⚠️ Higher risk of compatibility issues
- **Compromise:** Offer as documented alternative for forward-looking users
### Alternative 4: No Default (User Choice Required)
**Reasoning:**
- Maximum flexibility
- User decides based on production environment
- No opinionated stance
**Rejected Because:**
- ❌ Forces decision without context for new developers
- ❌ Increases setup friction and confusion
- ❌ Reference implementations should have best-practice defaults
- ❌ Most users (95%+) would choose MariaDB anyway
- ❌ Skill value proposition includes intelligent defaults
### Alternative 5: SQLite for Development (REVISED - Now ACCEPTED for Tier 1)
**Reasoning:**
- Minimal setup (no container overhead)
- Fast for development iteration cycles
- Perfect isolation for multi-version testing
- TYPO3 13 officially supports SQLite >= 3.8.3
- Single-developer DDEV localhost use case
**Originally Rejected Because (Revision 1 Analysis):**
- ❌ "Not production-viable (no concurrent writes)" → **OVERSTATED** for single-developer localhost
- Reality: Human actions are sequential (seconds/minutes apart)
- SQLite WAL mode handles concurrent reads during writes
- DDEV is single developer, not multi-user production
- ❌ "Security risk (web-downloadable database)" → **INVALID** for DDEV localhost
- Reality: Localhost (127.0.0.1), not exposed to public internet
- This is a production concern, not development concern
- ❌ "Not representative of production" → **OVER-APPLIED** for simple extensions
- Reality: For extensions using only Core APIs, database type doesn't matter
- Production parity important for custom SQL, overkill for simple extensions
**Now ACCEPTED for Tier 1 (Simple Extensions) Because:**
- ✅ Development and production have DIFFERENT requirements
- ✅ Significant developer experience improvements (5-10 sec startup, 900 MB RAM saved)
- ✅ Perfect for extensions using only TYPO3 Core APIs (Doctrine DBAL abstraction)
- ✅ Clear warnings prevent production misuse
- ✅ Easy migration to MariaDB if extension complexity increases
**Critical Success Factor:** Clear documentation that SQLite is **development ONLY**, with automated warnings and migration path to MariaDB for production testing.
---
## Database Selection Matrix
| Use Case | Recommended Database | Rationale |
|----------|---------------------|-----------|
| **Simple Plugin Extension (Core APIs only)** | **SQLite** (Tier 1) | Fast development, resource-efficient, perfect isolation |
| **Simple Frontend Extension** | **SQLite** (Tier 1) | No custom tables, uses FAL/Extbase/Doctrine DBAL |
| **Simple Backend Module (no custom SQL)** | **SQLite** (Tier 1) | TYPO3 core tables only, development-optimized |
| **RTE/CKEditor Plugin** | **SQLite** (Tier 1) | File operations via FAL, no database complexity |
| **Complex Extension (custom tables)** | **MariaDB 10.11** (Tier 2) | Production parity, custom database schema |
| **Extension with Raw SQL** | **MariaDB 10.11** (Tier 2) | Database-specific syntax, production testing needed |
| **Performance-Critical Extension** | **MariaDB 10.11** (Tier 2) | Production-realistic benchmarking required |
| **General TYPO3 Extension (unknown complexity)** | **MariaDB 10.11** (Tier 2) | Safe default, ecosystem standard, fallback choice |
| **GIS/Mapping Extension** | **PostgreSQL 16** (Tier 3) | PostGIS support, spatial queries |
| **Analytics/Reporting Extension** | **PostgreSQL 16** (Tier 3) | Complex queries, parallel execution, window functions |
| **Full-Text Search Extension** | **PostgreSQL 16** (Tier 3) | Superior full-text search capabilities |
| **Corporate/Oracle Ecosystem** | **MySQL 8.0** (Tier 4) | Oracle integration, enterprise requirements |
| **Forward-Looking Performance** | **MariaDB 11.4** | Latest features, performance improvements |
| **Production Uses PostgreSQL** | **PostgreSQL 16** (Tier 3) | Development-production parity |
| **Production Uses MySQL** | **MySQL 8.0** (Tier 4) | Development-production parity |
**Key Changes from Original Decision:**
- ✅ SQLite now RECOMMENDED for simple extensions (Tier 1)
- ✅ MariaDB remains default for complex extensions (Tier 2)
- ✅ Tiered approach based on extension complexity analysis
- ✅ Development efficiency prioritized for simple extensions
- ✅ Production parity prioritized for complex extensions
---
## Implementation Roadmap
### Phase 1: Documentation (Immediate)
1. **ADR Creation**: This document
2. **SKILL.md Update**: Database section explaining default and alternatives
3. **README.md Update**: Quick reference for database options
4. **Template Comments**: Explain database choice in config.yaml
### Phase 2: Auto-Detection (v2.1.0)
1. **Extension Metadata Parsing**: Detect PostgreSQL signals
2. **User Confirmation**: Present detected database with rationale
3. **Override Option**: Allow manual database selection
4. **Logging**: Explain why database was chosen
### Phase 3: Testing & Validation (Ongoing)
1. **MariaDB 10.11**: Validate default (already working)
2. **PostgreSQL 16**: Test TYPO3 13 installation
3. **MariaDB 11.4**: Validate forward-looking alternative
4. **MySQL 8.0**: Validate corporate alternative
---
## References
### Technical Documentation
- [TYPO3 13 System Requirements](https://get.typo3.org/version/13#system-requirements)
- [TYPO3 Database Configuration](https://docs.typo3.org/m/typo3/reference-coreapi/13.4/en-us/ApiOverview/Database/Configuration/Index.html)
- [DDEV Database Documentation](https://ddev.readthedocs.io/en/stable/users/extend/database-types/)
- [MariaDB vs MySQL Performance](https://mariadb.org/how-mariadb-and-mysql-performance-changed-over-releases/)
### Benchmarks
- **MariaDB vs MySQL**: 13-36% faster (Sysbench 2024)
- **PostgreSQL vs MariaDB**: +84% OLTP orders (HammerDB TPROC-C)
- **MySQL 8 Performance**: 66-84% throughput vs MySQL 5.6
- **Image Sizes**: PostgreSQL 394 MB, MariaDB 456 MB, DDEV MariaDB 744 MB
### TYPO3 Community
- **Hosting Research**: "Most TYPO3 customers prefer MySQL/MariaDB"
- **Production Distribution**: 95%+ MariaDB, <10% MySQL, <5% PostgreSQL
- **TYPO3 Forum**: [PostgreSQL discussions](https://www.typo3forum.net/discussion/82437/typo3-with-postgresql)
---
## Decision Rationale Summary (Revised)
### Tiered Database Selection Strategy
**SQLite (Tier 1) is OPTIMAL for simple extensions because:**
1. **Development Efficiency** (5-10 seconds faster startup, 900 MB RAM saved)
2. **Resource Optimization** (744 MB less disk, no container overhead)
3. **Perfect Isolation** (Separate .sqlite files for v11/v12/v13)
4. **Core API Sufficiency** (Extensions using only TYPO3 Core APIs work across databases)
5. **Developer Experience** (Faster iteration cycles, simpler architecture)
**Critical:** Development ONLY. Clear warnings prevent production misuse.
**MariaDB 10.11 (Tier 2) is NECESSARY for complex extensions because:**
1. **Production Reality** (95%+ TYPO3 hosting uses MariaDB)
2. **Custom SQL Requirements** (Database-specific syntax testing)
3. **Extension Compatibility** (99%+ extensions tested on MariaDB)
4. **Performance Testing** (Production-realistic benchmarking)
5. **Stability** (LTS release, production-proven, DDEV standard)
**PostgreSQL 16 (Tier 3) is REQUIRED for specialized extensions because:**
1. **GIS/Spatial Data** (PostGIS support, spatial queries)
2. **Analytics** (Complex queries, parallel execution)
3. **Technical Superiority** (Advanced features for specific use cases)
**MySQL 8.0 (Tier 4) is AVAILABLE for corporate environments because:**
1. **Oracle Ecosystem** (Corporate integration requirements)
2. **Existing Production** (Development-production parity)
### Key Insight: Context Matters
**This is NOT like Valkey** where industry was migrating. Database choice is stable at MariaDB for production.
**This IS like Valkey** in that we recognize DEVELOPMENT and PRODUCTION have DIFFERENT optimal choices.
**The tiered approach is intelligent and context-aware:**
- **Simple extensions** → Optimize for development efficiency (SQLite)
- **Complex extensions** → Optimize for production parity (MariaDB)
- **Specialized extensions** → Match technical requirements (PostgreSQL/MySQL)
**Revision 1 Learning:** Original ADR over-applied production concerns to development context. After user challenge, re-analysis showed SQLite is OPTIMAL for simple extension development with proper warnings and migration path.
---
## Review and Updates
**Next Review Date:** 2025-06-01 (6 months)
**Trigger for Re-evaluation:**
- TYPO3 14 changes database support or recommendations
- PostgreSQL adoption in TYPO3 hosting exceeds 25%
- MariaDB 10.x becomes unsupported by TYPO3
- Major performance regressions discovered in MariaDB
- TYPO3 officially recommends different default database
**Success Metrics:**
- Developer feedback on database default (GitHub issues)
- PostgreSQL adoption rate for auto-detected extensions
- Extension compatibility reports
- Production deployment success rate
---
**Approved By:** TYPO3 DDEV Skill Project
**Implementation:** v2.1.0 (target release)

288
references/advanced-options.md Normal file
View File

@@ -0,0 +1,288 @@
## Advanced Options
### Custom PHP Version
If extension requires different PHP version:
```yaml
# In .ddev/config.yaml
php_version: "8.1" # or "8.3"
```
### Database Selection (Tiered Approach)
The skill uses **intelligent database selection** based on extension complexity.
**🎯 Tier 1: SQLite (Simple Extensions - Development Optimized)**
**Recommended for:**
- ✅ Extensions using only TYPO3 Core APIs (Extbase, FAL, DataHandler)
- ✅ No custom database tables (ext_tables.sql absent/empty)
- ✅ No raw SQL queries
- ✅ Category: plugin, fe, be, misc
- ✅ Example: rte_ckeditor_image, simple content elements, frontend plugins
**Benefits:**
- ⚡ **Startup**: 5-10 seconds faster per ddev start
- 💾 **RAM**: 900 MB saved (no MariaDB container)
- 💿 **Disk**: 744 MB saved (no container image)
- 🔒 **Isolation**: Perfect v11/v12/v13 separation (separate .sqlite files)
**Configuration:**
```yaml
# No .ddev/config.yaml database config needed
# TYPO3 installation uses SQLite automatically
```
**Critical Warnings:**
- ⚠️ **Development ONLY** - Never use SQLite in production
- ⚠️ **Switch to MariaDB** if you add custom SQL queries or tables
- ⚠️ **Final Testing** - Run compatibility tests on MariaDB before release
**🔧 Tier 2: MariaDB 10.11 (Complex Extensions - Production Parity)**
**Recommended for:**
- ❌ Extensions with custom database tables (ext_tables.sql present)
- ❌ Extensions using raw SQL queries
- ❌ Performance-critical operations
- ❌ Category: services, module
- ❌ Unknown complexity (safe default)
**Benefits:**
- ✅ **Production Standard**: 95%+ TYPO3 hosting uses MariaDB
- ✅ **Extension Compatibility**: 99%+ TYPO3 extensions tested on MariaDB
- ✅ **Performance**: 13-36% faster than MySQL 8 for transactional workloads
- ✅ **TYPO3 Ecosystem**: Documentation, tutorials, community standard
**Configuration:**
```yaml
# In .ddev/config.yaml
database:
type: mariadb
version: "10.11"
```
**🌐 Tier 3: PostgreSQL 16 (Specialized Requirements)**
**Recommended for:**
- 🎯 GIS/spatial data (PostGIS)
- 🎯 Advanced analytics or complex queries
- 🎯 Explicit PostgreSQL requirement
**Configuration:**
```yaml
# In .ddev/config.yaml
database:
type: postgres
version: "16"
```
**🏢 Tier 4: MySQL 8.0 (Corporate/Oracle Ecosystem)**
**Recommended for:**
- 🏢 Corporate environments requiring Oracle integration
- 🏢 Production specifically uses MySQL 8
**Configuration:**
```yaml
# In .ddev/config.yaml
database:
type: mysql
version: "8.0"
```
**Auto-Detection Logic:**
The skill will analyze your extension and suggest the appropriate tier:
```yaml
SQLite Detection (Tier 1):
✓ ext_tables.sql: Absent or empty
✓ Raw SQL patterns: None found
✓ File size: < 1 MB
✓ Category: plugin, fe, be, misc
→ Suggests: SQLite (development-optimized)
MariaDB Detection (Tier 2):
✗ ext_tables.sql: Present with custom tables
✗ Raw SQL patterns: Found
✗ File size: > 1 MB
✗ Category: services, module
→ Suggests: MariaDB 10.11 (production-realistic)
PostgreSQL Detection (Tier 3):
• Extension name: Contains "postgres", "pgsql", "postgis"
• composer.json: Requires "typo3/cms-pgsql"
• Keywords: "GIS", "spatial", "analytics"
→ Suggests: PostgreSQL 16 (specialized)
```
**Alternative Options:**
**MariaDB 11** - Forward-looking performance:
```yaml
database:
type: mariadb
version: "11.4"
```
- Latest features (+40% performance vs 10.11)
- Forward compatibility testing
**For detailed rationale**, see: `docs/adr/0002-mariadb-default-with-database-alternatives.md`
### XDebug Setup
Enable XDebug for debugging:
```bash
ddev xdebug on
```
### Customize TYPO3 Versions
Edit `.ddev/docker-compose.web.yaml` and installation scripts to add/remove versions.
### Database Access
```bash
# Direct database access
ddev mysql
# Export database
ddev export-db > backup.sql.gz
# Import database
ddev import-db --file=backup.sql.gz
```
### Optional Services
The skill includes optional service templates for enhanced TYPO3 development:
#### Valkey / Redis (Caching)
Add high-performance caching to TYPO3 using **Valkey** (default) or **Redis** (alternative).
**Default: Valkey 8** (Open Source, Future-Proof)
```bash
# Copy Valkey template (default)
cp .ddev/templates/docker-compose.services.yaml.optional .ddev/docker-compose.services.yaml
cp .ddev/templates/config.redis.php.example .ddev/config.redis.php.example
# Restart DDEV
ddev restart
# Test Valkey (wire-compatible with Redis)
ddev ssh
redis-cli -h valkey ping # Should return: PONG
```
**Alternative: Redis 7** (For Legacy Production Parity)
```bash
# Use Redis 7 alternative template
cp .ddev/templates/docker-compose.services-redis.yaml.optional .ddev/docker-compose.services.yaml
# Restart DDEV
ddev restart
# Test Redis
ddev ssh
redis-cli -h redis ping # Should return: PONG
```
**Why Valkey Default?**
Valkey is wire-protocol compatible with Redis but offers:
- ✅ **True Open Source**: BSD-3-Clause license (Redis 7.4+ is proprietary)
- ✅ **Industry Adoption**: AWS, Google Cloud, Oracle backing (Linux Foundation project)
- ✅ **Smaller Image**: 69.7 MB (vs 100 MB Redis 8, 60.6 MB Redis 7)
- ✅ **Cost-Effective**: 20-33% cheaper on AWS ElastiCache
- ✅ **Future-Proof**: Strategic direction for cloud/managed hosting
**When to Use Redis 7 Instead:**
- Your production environment explicitly uses Redis 7.x
- Corporate policy requires battle-tested technology only (Redis has 15 years vs Valkey 1 year)
- Exact production-development parity needed with existing infrastructure
**Technical Details:**
**Valkey**: `valkey/valkey:8-alpine` (69.7 MB)
**Redis**: `redis:7-alpine` (60.6 MB)
**Memory**: 256MB with LRU eviction policy
**Port**: 6379 (same for both)
**Configuration**: Both use identical TYPO3 configuration. Add cache backend to `AdditionalConfiguration.php` (see `.ddev/config.redis.php.example`)
**For detailed rationale**, see: `docs/adr/0001-valkey-default-with-redis-alternative.md`
#### MailPit (Email Testing)
Catch all emails sent by TYPO3 for testing:
```bash
# Already included in docker-compose.services.yaml.optional
# Access Web UI after ddev restart:
# http://{{DDEV_SITENAME}}.ddev.site:8025
```
**Image**: `axllent/mailpit:latest`
**SMTP**: `mailpit:1025` (automatically configured in docker-compose.web.yaml)
#### Ofelia (TYPO3 Scheduler Automation)
Automate TYPO3 scheduler tasks with **ghcr.io/netresearch/ofelia**:
```bash
# Copy Ofelia configuration
cp .ddev/templates/docker-compose.ofelia.yaml.optional .ddev/docker-compose.ofelia.yaml
# Restart DDEV
ddev restart
# View scheduler logs
docker logs -f ddev-{{DDEV_SITENAME}}-ofelia
```
**Image**: `ghcr.io/netresearch/ofelia:latest` (GitHub Container Registry - TYPO3-optimized fork)
**Default Schedule**: TYPO3 scheduler runs every 1 minute for all versions
**Cache Warmup**: Every 1 hour for v13
**DDEV Naming**: Uses `docker-compose.*.yaml` naming (DDEV v1.24.8 requirement, not Compose v2 standard)
**No Version Field**: All service files omit `version:` declaration per Compose v2 spec
#### Shell Aliases
Add convenient shortcuts:
```bash
# Copy bash additions
cp .ddev/templates/homeadditions/.bashrc_additions.optional .ddev/homeadditions/.bashrc_additions
# Restart DDEV to load aliases
ddev restart
# Available aliases:
ddev ssh
t3-scheduler-v11 # Run TYPO3 11 scheduler
t3-scheduler-v12 # Run TYPO3 12 scheduler
t3-scheduler-v13 # Run TYPO3 13 scheduler
t3-scheduler-all # Run scheduler on all versions
redis # Access Redis CLI
t3-cache-flush-v13 # Flush TYPO3 13 cache
```
#### Complete Services Documentation
For detailed service configuration, troubleshooting, and performance tuning:
```bash
# Copy services README
cp .ddev/templates/README-SERVICES.md.optional .ddev/README-SERVICES.md
```
**Important Notes**:
- DDEV v1.24.8 requires `docker-compose.*.yaml` naming (auto-loads from `.ddev/`)
- Ofelia image: `ghcr.io/netresearch/ofelia:latest` (not Docker Hub)
- Ofelia command: `daemon --docker-events` (not `--docker`)
- Redis config must NOT be `.yaml` (DDEV tries to parse it as config)

370
references/index-page-generation.md Normal file
View File

@@ -0,0 +1,370 @@
# Index Page Generation for TYPO3 DDEV Projects
## Purpose
Generate a professional overview page (`index.html`) that serves as the main entry point for the DDEV development environment, providing quick access to all TYPO3 versions and development tools.
## Automatic Branding Detection
**The index page MUST automatically detect and apply appropriate branding:**
### Step 1: Detect Available Branding Skills
Check for branding skills in this priority order:
1. **Company-specific branding** (e.g., `netresearch-branding`, `company-branding`)
2. **TYPO3 branding** (fallback - use TYPO3 orange #FF8700)
3. **Generic clean design** (last resort - neutral colors)
**Detection Method:**
```bash
# Check if branding skill exists
list-skills | grep -i branding
```
### Step 2: Apply Branding Based on Detection
#### If Netresearch Branding Detected
**Invoke:** `netresearch-branding` skill
**Colors:**
- Primary: #2F99A4 (Turquoise)
- Accent: #FF4D00 (Orange)
- Text: #585961 (Anthracite grey)
- Background: #FFFFFF (White)
- Light grey: #CCCDCC
**Typography:**
- Headlines: `font-family: 'Raleway', sans-serif;` (600/700 weight)
- Body: `font-family: 'Open Sans', sans-serif;` (400 weight)
**Layout:**
- Compact header: 20px padding
- High white space: 40px container padding
- Card shadows: subtle with turquoise glow on hover
#### If TYPO3 Branding (Fallback)
**Colors:**
- Primary: #FF8700 (TYPO3 Orange)
- Secondary: #000000 (Black)
- Text: #333333 (Dark grey)
- Background: #F8F9FA (Light grey)
- Cards: #FFFFFF (White)
**Typography:**
- System fonts: `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif`
- No external font imports
**Layout:**
- Standard header: 40px padding
- Moderate white space: 30px container padding
- Card shadows: standard grey shadows
#### If No Branding (Generic)
**Colors:**
- Primary: #0066CC (Professional blue)
- Text: #333333
- Background: #FFFFFF
- Cards: #F5F5F5
**Typography:**
- System fonts only
- Standard sizing
## HTML Template Structure
### Required Elements
1. **Header** - Compact bar with project title
2. **Info Box** - Backend credentials (username/password)
3. **Grid Layout** - 2-4 columns responsive
4. **Cards** - One per TYPO3 version + tools
5. **Links** - Frontend and Backend URLs
### Card Content Template
```html
<div class="card">
<div class="card-icon">[EMOJI]</div>
<h3>[VERSION NAME]</h3>
<p>[DESCRIPTION]</p>
<div class="card-links">
<a href="[FRONTEND_URL]">→ Frontend</a>
<a href="[BACKEND_URL]">→ Backend</a>
</div>
</div>
```
### Cards to Include
**Always include:**
1. TYPO3 12.4 LTS (🎯 emoji)
2. TYPO3 13.x (⚡ emoji)
3. Documentation (📚 emoji)
4. Development Tools (📧 emoji - Mailpit)
**Optional cards** (if applicable):
5. TYPO3 11.5 LTS (📦 emoji)
6. Redis/Valkey (🔄 emoji)
7. Custom tools
## Generation Workflow
### Step 1: Detect Branding
```
1. Check for branding skills
2. If netresearch-branding exists → Use Netresearch colors/fonts
3. Else if project has branding config → Use project branding
4. Else → Use TYPO3 branding (fallback)
```
### Step 2: Extract Project Metadata
```
- Project name (from .ddev/config.yaml or composer.json)
- DDEV sitename
- Configured TYPO3 versions (from docker-compose or config)
```
### Step 3: Generate HTML
**File location:** `.ddev/web-build/index.html`
**Template variables to replace:**
- `{{PROJECT_NAME}}` - Extension display name
- `{{DDEV_SITENAME}}` - DDEV project name
- `{{PRIMARY_COLOR}}` - Brand primary color
- `{{ACCENT_COLOR}}` - Brand accent color
- `{{TEXT_COLOR}}` - Body text color
- `{{FONT_HEADLINE}}` - Headline font family
- `{{FONT_BODY}}` - Body font family
### Step 4: Copy to Web Root
```bash
# After generation
ddev exec cp /var/www/hello_world/.ddev/web-build/index.html /var/www/html/
```
## Example: Netresearch-Branded Index
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{PROJECT_NAME}} - Development Environment</title>
<link href="https://fonts.googleapis.com/css2?family=Raleway:wght@600;700&family=Open+Sans:wght@400&display=swap" rel="stylesheet">
<style>
body {
font-family: 'Open Sans', sans-serif;
background: #FFFFFF;
color: #585961;
}
.header {
background: #2F99A4;
padding: 20px;
}
.header h1 {
font-family: 'Raleway', sans-serif;
color: #FFFFFF;
font-size: 24px;
}
.card-links a:hover {
background: #2F99A4;
color: #FFFFFF;
}
</style>
</head>
<body>
<!-- Content here -->
</body>
</html>
```
## Example: TYPO3-Branded Index (Fallback)
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>{{PROJECT_NAME}} - Development Environment</title>
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: #F8F9FA;
color: #333333;
}
.header {
background: #FF8700;
padding: 40px 20px;
}
.header h1 {
color: #FFFFFF;
font-size: 32px;
}
.card-links a {
color: #FF8700;
}
.card-links a:hover {
background: #FF8700;
color: #FFFFFF;
}
</style>
</head>
<body>
<!-- Content here -->
</body>
</html>
```
## Responsive Design Requirements
**Breakpoints:**
```css
/* Mobile: default (single column) */
.grid {
grid-template-columns: 1fr;
}
/* Tablet: 768px+ (2 columns) */
@media (min-width: 768px) {
.grid {
grid-template-columns: repeat(2, 1fr);
}
}
/* Desktop: 1024px+ (auto-fit) */
@media (min-width: 1024px) {
.grid {
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
}
}
```
## Accessibility Requirements
**WCAG AA Compliance:**
1. **Color Contrast**
- Text on background: minimum 4.5:1
- Large text (18px+): minimum 3:1
- Verify with: https://webaim.org/resources/contrastchecker/
2. **Keyboard Navigation**
- All links must be keyboard accessible
- Visible focus states
- Logical tab order
3. **Semantic HTML**
- Proper heading hierarchy (h1 → h2 → h3)
- Descriptive link text (not just "click here")
- Alt text for images (if any)
## Quality Checklist
Before finalizing the index page:
- [ ] Branding detection executed correctly
- [ ] Appropriate colors applied
- [ ] Proper fonts loaded (if external fonts used)
- [ ] All TYPO3 version links present
- [ ] Backend credentials displayed
- [ ] Responsive design works on mobile/tablet/desktop
- [ ] Color contrast passes WCAG AA
- [ ] No console errors
- [ ] File copied to /var/www/html/
- [ ] Accessible at https://{sitename}.ddev.site/
## Integration with SKILL.md
**In Step 8 of SKILL.md, replace the current text with:**
```markdown
### Step 8: Generate Project Overview Page
**Automatic branding detection:**
The overview page automatically detects and applies appropriate branding:
1. **Check for branding skills** (netresearch-branding, company-branding, etc.)
2. **Apply detected branding** (colors, fonts, layout)
3. **Fallback to TYPO3 branding** (orange #FF8700) if no branding detected
4. **Generate responsive HTML** with cards for each TYPO3 version
**Generation process:**
```bash
# Skill automatically:
# 1. Detects available branding (netresearch-branding skill if present)
# 2. Applies brand colors and fonts
# 3. Creates .ddev/web-build/index.html
# 4. Copies to /var/www/html/
# Manual copy if needed:
ddev exec cp /var/www/hello_world/.ddev/web-build/index.html /var/www/html/
```
**See:** `INDEX-PAGE-GENERATION.md` for complete branding detection logic
```
## Example Detection Logic (Pseudocode)
```python
def generate_index_page():
# Step 1: Detect branding
branding = detect_branding()
if branding == "netresearch":
colors = {
"primary": "#2F99A4",
"text": "#585961",
"background": "#FFFFFF"
}
fonts = {
"headline": "Raleway",
"body": "Open Sans"
}
header_padding = "20px"
elif branding == "company-specific":
# Load company branding
colors = load_company_colors()
fonts = load_company_fonts()
else: # TYPO3 fallback
colors = {
"primary": "#FF8700",
"text": "#333333",
"background": "#F8F9FA"
}
fonts = {
"headline": "system-ui",
"body": "system-ui"
}
header_padding = "40px"
# Step 2: Generate HTML
html = generate_html_template(colors, fonts, header_padding)
# Step 3: Write file
write_file(".ddev/web-build/index.html", html)
# Step 4: Copy to web root
copy_to_web_root()
```
---
**This approach ensures:**
- ✅ Automatic branding application
- ✅ Consistent professional appearance
- ✅ Graceful fallback to TYPO3 branding
- ✅ Company branding when available
- ✅ No manual branding decisions needed

242
references/prerequisites-validation.md Normal file
View File

@@ -0,0 +1,242 @@
## Prerequisites Validation
Before proceeding with ANY DDEV commands, especially on first DDEV command during a session, perform comprehensive validation:
### 1. Docker Daemon Status
**Check if Docker daemon is running:**
```bash
docker info >/dev/null 2>&1
```
**If Docker daemon is NOT running:**
```
❌ Docker daemon is not running.
Start Docker daemon based on your platform:
🐧 Linux/WSL2:
sudo service docker start
# or
sudo systemctl start docker
# Verify:
sudo systemctl status docker
🍎 macOS:
- Open Docker Desktop application
- Wait for whale icon to show "Docker Desktop is running"
# Verify from terminal:
docker info
🪟 Windows:
- Open Docker Desktop application
- Wait for notification "Docker Desktop is running"
# Verify from PowerShell/CMD:
docker info
After starting Docker, please retry the command.
```
### 2. Docker CLI Version
**Check Docker version (minimum: 20.10):**
```bash
docker version --format '{{.Client.Version}}'
```
**Expected output:** Version >= 20.10 (e.g., `24.0.7`, `25.0.0`)
**If version is too old or missing:**
```
❌ Docker CLI is outdated or missing.
Minimum required version: 20.10
Current version: [detected or "not found"]
Update Docker:
🐧 Linux:
# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
# Or follow: https://docs.docker.com/engine/install/
🍎 macOS:
brew upgrade --cask docker
# Or download from: https://www.docker.com/products/docker-desktop/
🪟 Windows:
# Update via Docker Desktop app or download from:
https://www.docker.com/products/docker-desktop/
```
### 3. Docker Compose Version
**Check Docker Compose version (minimum: 2.0):**
```bash
docker compose version --short
```
**Expected output:** Version >= 2.0 (e.g., `2.23.3`, `2.24.0`)
**Note:** Modern Docker includes Compose v2 as `docker compose` (not `docker-compose`)
**If version is too old or missing:**
```
❌ Docker Compose is outdated or using legacy v1.
Minimum required version: 2.0
Current version: [detected or "not found"]
Docker Compose v2 is included with Docker Desktop 3.4+ and Docker CLI 20.10+
Solutions:
🐧 Linux:
# If using legacy docker-compose v1:
sudo apt remove docker-compose
# Compose v2 is included with Docker 20.10+
# Verify installation:
docker compose version
# If missing, install Docker CLI with Compose plugin:
sudo apt-get install docker-compose-plugin
🍎 macOS / 🪟 Windows:
# Included in Docker Desktop - update to latest:
brew upgrade --cask docker # macOS
# Or download latest Docker Desktop
```
### 4. DDEV Installation
**Check if DDEV is installed:**
```bash
ddev version
```
**If DDEV is not installed:**
```
❌ DDEV is not installed.
Install DDEV based on your platform:
🍎 macOS:
brew install ddev/ddev/ddev
🐧 Linux:
# Ubuntu/Debian
curl -fsSL https://raw.githubusercontent.com/ddev/ddev/master/scripts/install_ddev.sh | bash
# Or see: https://ddev.readthedocs.io/en/stable/users/install/ddev-installation/
🪟 Windows:
choco install ddev
# Or see: https://ddev.readthedocs.io/en/stable/users/install/ddev-installation/
```
### 5. TYPO3 Extension Project Validation
**Confirm current directory is a TYPO3 extension:**
- Check for `ext_emconf.php` file
- OR check `composer.json` has `type: "typo3-cms-extension"`
- Check for typical TYPO3 extension structure (Classes/, Configuration/, Resources/)
**If not a TYPO3 extension:**
```
❌ This doesn't appear to be a TYPO3 extension project.
Requirements:
- ext_emconf.php file present
OR
- composer.json with "type": "typo3-cms-extension"
Current directory: [show path]
```
### 6. Existing DDEV Setup Check
**Check if `.ddev/` directory already exists:**
```bash
test -d .ddev && echo "DDEV config exists" || echo "No DDEV config"
```
**If `.ddev/` exists:**
```
⚠️ DDEV configuration already exists.
Do you want to:
1. Keep existing configuration (skip setup)
2. Overwrite with new configuration
3. Backup existing and create new
Please choose: [1/2/3]
```
### Prerequisites Validation Summary
**Run ALL checks before proceeding:**
```bash
# Quick validation script
echo "🔍 Validating prerequisites..."
# 1. Docker daemon
if docker info >/dev/null 2>&1; then
echo "✅ Docker daemon: Running"
else
echo "❌ Docker daemon: Not running"
exit 1
fi
# 2. Docker version
DOCKER_VERSION=$(docker version --format '{{.Client.Version}}' 2>/dev/null | cut -d. -f1,2)
if [ -n "$DOCKER_VERSION" ] && [ "$(printf '%s\n' "20.10" "$DOCKER_VERSION" | sort -V | head -n1)" = "20.10" ]; then
echo "✅ Docker CLI: $DOCKER_VERSION (>= 20.10)"
else
echo "❌ Docker CLI: Version check failed (need >= 20.10)"
exit 1
fi
# 3. Docker Compose version
COMPOSE_VERSION=$(docker compose version --short 2>/dev/null | cut -d. -f1)
if [ -n "$COMPOSE_VERSION" ] && [ "$COMPOSE_VERSION" -ge 2 ]; then
echo "✅ Docker Compose: $(docker compose version --short) (>= 2.0)"
else
echo "❌ Docker Compose: Version check failed (need >= 2.0)"
exit 1
fi
# 4. DDEV
if command -v ddev >/dev/null 2>&1; then
echo "✅ DDEV: $(ddev version | head -n1)"
else
echo "❌ DDEV: Not installed"
exit 1
fi
# 5. TYPO3 Extension
if [ -f "ext_emconf.php" ] || grep -q '"type".*"typo3-cms-extension"' composer.json 2>/dev/null; then
echo "✅ TYPO3 Extension: Detected"
else
echo "❌ TYPO3 Extension: Not detected"
exit 1
fi
echo ""
echo "✅ All prerequisites validated successfully!"
```
**Critical:** Always run these checks on the FIRST DDEV command in a session to catch environment issues early.
If any prerequisite fails, provide clear instructions on how to resolve it before proceeding.

292
references/quickstart.md Normal file
View File

@@ -0,0 +1,292 @@
# Quick Start Guide
This guide walks you through setting up DDEV for your TYPO3 extension using this skill.
## Prerequisites Check
Before starting, verify:
```bash
# Check DDEV
ddev version
# Expected: DDEV version v1.22+
# Check Docker
docker ps
# Expected: List of containers or empty (no error)
# Check you're in a TYPO3 extension directory
ls ext_emconf.php
# Expected: ext_emconf.php file exists
```
## Step 1: Install the Skill
```bash
cd ~/.claude/skills/
git clone https://github.com/netresearch/typo3-ddev-skill.git
```
## Step 2: Navigate to Your Extension
```bash
cd ~/projects/my-typo3-extension
```
## Step 3: Invoke the Skill in Claude Code
Open Claude Code and type:
```
Set up DDEV for this TYPO3 extension
```
Or use the slash command (if configured):
```
/typo3-ddev
```
## Step 4: Follow the Prompts
The skill will:
1. **Detect** your extension:
```
✅ Found TYPO3 extension: my_ext
```
2. **Extract** metadata:
```
Extension Key: my_ext
Package Name: vendor/my-ext
DDEV Sitename: my-ext
Vendor Namespace: Vendor\MyExt
```
3. **Confirm** with you:
```
Is this correct? (y/n)
```
4. **Generate** .ddev configuration files
5. **Start** DDEV (if you approve)
## Step 5: Install TYPO3
Once DDEV is running:
```bash
# Install all versions (recommended for first time)
ddev install-all
# Or install specific version
ddev install-v13
```
Wait 2-5 minutes per version for installation.
## Step 6: Access Your Environment
Open in your browser:
- **Overview**: https://my-ext.ddev.site/
- **TYPO3 13 Backend**: https://v13.my-ext.ddev.site/typo3/
- Username: `admin`
- Password: `Password:joh316`
## Step 7: Start Developing
Your extension source code is in the project root. Any changes you make will immediately reflect in all TYPO3 versions because the code is bind-mounted.
### Typical Development Workflow
```bash
# 1. Make changes to your extension code
vim Classes/Controller/MyController.php
# 2. Clear TYPO3 cache
ddev exec -d /var/www/html/v13 vendor/bin/typo3 cache:flush
# 3. Test in browser
# Open https://v13.my-ext.ddev.site/
# 4. Check logs if needed
ddev logs
```
## Next Steps
### Enable XDebug
```bash
ddev xdebug on
# Configure your IDE to connect to localhost:9003
```
### Add Database Fixtures
```bash
# Import database
ddev import-db --file=fixtures/database.sql
# Export database
ddev export-db > backup.sql.gz
```
### Run Tests
```bash
# Unit tests
ddev exec vendor/bin/phpunit Tests/Unit/
# Functional tests
ddev exec vendor/bin/phpunit Tests/Functional/
```
### Access Database
```bash
# MySQL CLI
ddev mysql
# Or use a GUI tool:
# Host: 127.0.0.1
# Port: (run `ddev describe` to get the port)
# User: root
# Password: root
```
## Common Tasks
### Restart DDEV
```bash
ddev restart
```
### Stop DDEV
```bash
ddev stop
```
### Remove Environment (keeps volumes)
```bash
ddev delete
```
### Complete Cleanup (removes everything)
```bash
ddev delete --omit-snapshot --yes
docker volume rm my-ext-v11-data my-ext-v12-data my-ext-v13-data
```
### SSH into Container
```bash
ddev ssh
# You're now inside the container
cd /var/www/html/v13
# Do stuff
exit
```
## Troubleshooting
### Port Already in Use
```bash
# Edit .ddev/config.yaml
router_http_port: "8080"
router_https_port: "8443"
ddev restart
```
### Installation Hangs or Fails
```bash
# Check logs
ddev logs
# Retry installation
ddev ssh
rm -rf /var/www/html/v13/*
exit
ddev install-v13
```
### Extension Not Found
```bash
# Verify environment variables
ddev ssh
echo $EXTENSION_KEY
echo $PACKAGE_NAME
# Check Composer setup
cd /var/www/html/v13
composer show $PACKAGE_NAME
```
### Clear Everything and Start Over
```bash
ddev delete --omit-snapshot --yes
rm -rf .ddev/
# Then re-run the skill setup
```
## Example Project Structure
After setup, your project should look like:
```
my-typo3-extension/
├── .ddev/ # DDEV configuration (generated)
│ ├── config.yaml
│ ├── docker-compose.web.yaml
│ ├── apache/
│ ├── web-build/
│ └── commands/
├── Classes/ # Your extension PHP classes
├── Configuration/ # Your extension configuration
├── Resources/ # Your extension resources
├── Tests/ # Your extension tests
├── composer.json # Your extension composer config
├── ext_emconf.php # TYPO3 extension declaration
└── README.md # Your extension documentation
```
## Tips for Extension Development
1. **Use Multiple Terminals**:
- Terminal 1: Code editing
- Terminal 2: `ddev logs -f` (follow logs)
- Terminal 3: `ddev ssh` (run commands)
2. **Cache Management**:
- Development: Clear cache frequently
- Use `ddev exec -d /var/www/html/v13 vendor/bin/typo3 cache:flush`
3. **Version Testing**:
- Test critical changes across all versions
- Use `ddev install-all` to have all versions ready
4. **Backup Important Data**:
- Export databases before major changes
- Use `ddev export-db --gzip=false > backup.sql`
5. **Keep DDEV Updated**:
```bash
ddev version # Check current version
# Update via your package manager (brew, apt, etc.)
```
---
**Happy TYPO3 Extension Development! 🚀**

75
references/troubleshooting.md Normal file
View File

@@ -0,0 +1,75 @@
## Error Handling
### Common Issues and Solutions
**1. Prerequisites Not Met**
```
❌ Prerequisites validation failed.
One or more requirements are not met:
- Docker daemon not running
- Docker CLI outdated (need >= 20.10)
- Docker Compose outdated (need >= 2.0)
- DDEV not installed
See "Prerequisites Validation" section above for detailed:
- Platform-specific installation instructions
- Version requirement details
- Validation script you can run
Run the validation script to identify which prerequisite is failing.
```
**2. Docker Daemon Not Running (Most Common)**
```
❌ Docker daemon is not running.
Quick fix for your platform:
🐧 Linux/WSL2:
sudo service docker start
🍎 macOS:
Open Docker Desktop application
🪟 Windows:
Open Docker Desktop application
For detailed instructions, see Prerequisites Validation section.
After starting Docker, run: docker info
```
**3. Not a TYPO3 Extension**
```
❌ This doesn't appear to be a TYPO3 extension project.
Requirements:
- ext_emconf.php file present
OR
- composer.json with "type": "typo3-cms-extension"
Current directory: /path/to/project
```
**4. Port Conflicts**
```
❌ DDEV failed to start (port 80/443 conflict)
Solutions:
- Stop other local web servers (Apache, Nginx, MAMP)
- Or use different ports in .ddev/config.yaml:
router_http_port: "8080"
router_https_port: "8443"
```
**5. Installation Failures**
```
❌ TYPO3 installation failed
Troubleshooting:
1. Check logs: ddev logs
2. SSH into container: ddev ssh
3. Check Composer: ddev composer diagnose
4. Try reinstalling: rm -rf /var/www/html/v13/* && ddev install-v13
```

297
references/windows-fixes.md Normal file
View File

@@ -0,0 +1,297 @@
# Windows-Specific DDEV Issues and Fixes
## Critical Issue: Health Check Failures
**Symptom:** `ddev start` hangs at "Waiting for containers to become ready" indefinitely
**Root Cause:** Custom Apache configurations override DDEV's default `/phpstatus` endpoint, causing health checks to fail
**Fix:** Always include PHP-FPM status endpoint in custom Apache configs
```apache
# CRITICAL: PHP-FPM status endpoint (required for DDEV health checks)
# Place this BEFORE any VirtualHost declarations
<Location /phpstatus>
SetHandler "proxy:unix:/run/php-fpm.sock|fcgi://localhost"
</Location>
```
**Correct Socket Path:** `/run/php-fpm.sock` (NOT `/run/php-fpm-socket/php-fpm.sock`)
**Verification:**
```bash
# After DDEV starts, verify health check passes:
ddev exec /healthcheck.sh
# Should output: /var/www/html:OK mailpit:OK phpstatus:OK
```
## Line Ending Issues
**Symptom:** `Command 'install-v12' contains CRLF, please convert to Linux-style linefeeds`
**Root Cause:** Files created on Windows have CRLF line endings; DDEV requires LF
**Fix:** Convert line endings after file creation **while preserving UTF-8 encoding for emojis**
```powershell
# PowerShell command to convert CRLF to LF (preserving UTF-8 for emojis)
# IMPORTANT: Must use -Raw flag, UTF-8 encoding, and proper replacement
foreach ($file in @('.ddev\commands\web\install-v12', '.ddev\commands\web\install-v13', '.ddev\commands\host\docs')) {
$content = Get-Content $file -Raw -Encoding UTF8
$content = $content -replace "`r`n", "`n"
[System.IO.File]::WriteAllText((Resolve-Path $file).Path, $content, [System.Text.UTF8Encoding]::new($false))
}
```
**Common Mistakes:**
- ❌ Using `(Get-Content $file)` without `-Raw` flag loses all line breaks
- ❌ Using `-Encoding ASCII` corrupts emojis (🚀 → ??)
- ✅ Must use UTF-8 encoding to preserve emoji characters
**Prevention:** Configure Git to handle line endings:
```bash
git config --global core.autocrlf input
```
## Router Not Starting Automatically
**Symptom:** Sites return 404, `docker ps | grep router` shows no router
**Root Cause:** On Windows, DDEV may fail to start the traefik router automatically
**Diagnostic:**
```bash
ddev describe
# If "SERVICE" table is empty, router didn't start
```
**Fix 1:** Restart DDEV after fixing health checks
```bash
ddev restart
# Router should start automatically if health checks pass
```
**Fix 2:** Check router status manually
```bash
docker ps -a | grep router
# If stopped, check logs:
docker logs ddev-router
```
## Mutagen Sync Issues
**Symptom:** `Mutagen Docker volume is not mounted. Please use 'ddev restart'`
**Root Cause:** Mutagen file sync can be problematic on Windows
**Fix:** Disable Mutagen and use direct bind mounts
```bash
ddev config --performance-mode=none
ddev restart
```
**Note:** Direct mounts may be slower but more reliable on Windows
## Docker Volume Permission Issues
**Symptom:** `Permission denied` when writing to `/var/www/html/vXX/composer.json`
**Root Cause:** Docker volumes on Windows are owned by root; web user can't write
**Solution:** Use `sudo chown` at the start of install scripts
```bash
#!/bin/bash
VERSION=v13
INSTALL_DIR=/var/www/html/$VERSION
# Fix permissions before writing (critical for Windows)
sudo rm -rf $INSTALL_DIR/*
sudo mkdir -p $INSTALL_DIR
sudo chown -R $(whoami):$(whoami) $INSTALL_DIR
# Now can write files
cd $INSTALL_DIR
echo "{}" > composer.json # Works!
```
**Why This Works:**
- Volumes are faster than bind mounts on Windows
- `sudo chown` fixes ownership without performance penalty
- Only needed once at the start of installation
**Bind Mounts Alternative (slower but simpler):**
```yaml
# In .ddev/docker-compose.web.yaml
volumes:
- type: bind
source: ./typo3-installations/v12
target: /var/www/html/v12
```
⚠️ Bind mounts are significantly slower on Windows
## Complete Apache Config Template (Windows-Safe)
```apache
# CRITICAL: PHP-FPM status endpoint (MUST be first)
<Location /phpstatus>
SetHandler "proxy:unix:/run/php-fpm.sock|fcgi://localhost"
</Location>
# Main project overview
<VirtualHost *:80>
ServerName {{DDEV_SITENAME}}.ddev.site
DocumentRoot /var/www/html
<Directory /var/www/html>
AllowOverride All
Require all granted
</Directory>
</VirtualHost>
# Additional VirtualHosts for multi-version setup
<VirtualHost *:80>
ServerName v12.{{DDEV_SITENAME}}.ddev.site
DocumentRoot /var/www/html/v12/public
<Directory /var/www/html/v12/public>
AllowOverride All
Require all granted
</Directory>
</VirtualHost>
# Add more VirtualHosts as needed...
```
## Debugging Steps
### 1. Check Container Health
```bash
docker inspect ddev-{{SITENAME}}-web --format='{{.State.Health.Status}}'
# Should be: healthy
```
### 2. Check Health Check Output
```bash
ddev exec /healthcheck.sh
# Should output: /var/www/html:OK mailpit:OK phpstatus:OK
```
### 3. Check PHP-FPM Socket
```bash
ddev exec ls -la /run/php-fpm.sock
# Should exist and be a socket
```
### 4. Test phpstatus Endpoint
```bash
ddev exec curl -f http://localhost/phpstatus
# Should return PHP-FPM status page
```
### 5. Check Router
```bash
docker ps | grep router
# Should show ddev-router container running and healthy
```
### 6. Check Traefik Logs
```bash
docker logs ddev-router --tail 50
# Look for routing errors
```
## Documentation Rendering (Host Commands)
**Symptom:** `ddev docs` command executes but produces no output, or Docker mount fails
**Root Cause:** Windows paths require special handling in DDEV host commands (Git Bash/WSL)
**Fix:** Use double-slash prefix for Docker volume mounts
```bash
#!/bin/bash
# For Windows compatibility - ensure path format works for Docker
if [[ "$OSTYPE" == "msys" ]]; then
# Git Bash on Windows - use double slash prefix
DOCKER_MOUNT="//$(pwd)"
else
DOCKER_MOUNT="$(pwd)"
fi
docker run --rm \
-v "$DOCKER_MOUNT:/project" \
ghcr.io/typo3-documentation/render-guides:latest \
--config=Documentation
```
**Path Transformation:**
- PowerShell: `C:\Users\live\project`
- Git Bash: `/c/Users/live/project`
- Docker (Windows): `//c/Users/live/project` (double slash prefix required)
## TYPO3 12 Database Setup Issue
**Symptom:** `install:setup` tries to create database repeatedly and fails
```
ERROR: Unable to create database
Database with name "v12" could not be created...
➤ Select database
```
**Root Cause:** TYPO3 12's `install:setup` tries to create the database itself
**Solution:** Use `--use-existing-database` flag
```bash
# Create database first
mysql -h db -u root -proot -e "CREATE DATABASE v12;"
# Then use existing database
vendor/bin/typo3 install:setup -n --database-name v12 --use-existing-database
```
**TYPO3 13 Comparison:**
TYPO3 13's `setup` command works differently and doesn't have this issue.
## Prevention Checklist
Before running `ddev start` on Windows:
- [ ] Apache config includes `/phpstatus` endpoint with correct socket path
- [ ] All script files in `.ddev/commands/` use LF line endings (with `-Raw` flag)
- [ ] Host commands use `//$(pwd)` for Docker mounts on Windows
- [ ] Git configured with `core.autocrlf=input`
- [ ] Mutagen disabled if experiencing sync issues
- [ ] Increased timeout: `ddev config --default-container-timeout=600`
## Quick Recovery
If DDEV is stuck or broken:
```bash
# 1. Stop everything
ddev poweroff
# 2. Remove any manual router
docker rm -f ddev-router
# 3. Fix Apache config (add phpstatus endpoint)
# 4. Fix line endings in command scripts
# 5. Disable Mutagen if needed
ddev config --performance-mode=none
# 6. Start with increased timeout
ddev config --default-container-timeout=600
ddev start
```
## Success Criteria
DDEV is properly working when:
1. ✅ `ddev start` completes without hanging
2. ✅ `ddev describe` shows all services with URLs
3. ✅ `ddev exec /healthcheck.sh` returns all OK
4. ✅ Browser can access `https://{{SITENAME}}.ddev.site`
5. ✅ `docker ps | grep router` shows healthy router

148
references/windows-optimizations.md Normal file
View File

@@ -0,0 +1,148 @@
# Windows Performance Optimizations
## Key Learnings
### 1. Use Docker Volumes (Not Bind Mounts)
**Performance Impact:** 3-5x faster installations
```yaml
# ✅ FAST: Docker volumes
volumes:
v12-data:/var/www/html/v12
v13-data:/var/www/html/v13
# ❌ SLOW: Bind mounts
volumes:
- type: bind
source: ./typo3-installations/v12
target: /var/www/html/v12
```
**Why:** Docker Desktop on Windows translates filesystem calls between Windows and Linux, making bind mounts significantly slower.
### 2. Fix Volume Permissions with sudo chown
```bash
# At start of install scripts
INSTALL_DIR=/var/www/html/v13
sudo rm -rf $INSTALL_DIR/*
sudo mkdir -p $INSTALL_DIR
sudo chown -R $(whoami):$(whoami) $INSTALL_DIR
```
This is the **critical Windows fix** that makes volumes work.
### 3. Preserve UTF-8 When Converting Line Endings
```powershell
# ✅ CORRECT: Preserves emojis
$content = Get-Content $file -Raw -Encoding UTF8
$content = $content -replace "`r`n", "`n"
[System.IO.File]::WriteAllText((Resolve-Path $file).Path, $content, [System.Text.UTF8Encoding]::new($false))
# ❌ WRONG: Corrupts emojis (🚀 → ??)
(Get-Content $file -Raw) -replace "`r`n", "`n" | Set-Content -NoNewline -Encoding ASCII $file
```
### 4. Install Commands: Use Shared Base Script
**DRY Principle:** Don't repeat 70+ lines of installation logic
```bash
# .ddev/commands/web/install-base (80 lines, shared)
install_typo3() {
# All common installation logic
}
# .ddev/commands/web/install-v13 (16 lines)
source /mnt/ddev_config/commands/web/install-base
SETUP_CMD="vendor/bin/typo3 setup -n ..."
install_typo3 "v13" "^13" "$SETUP_CMD"
# .ddev/commands/web/install-v12 (16 lines)
source /mnt/ddev_config/commands/web/install-base
SETUP_CMD="vendor/bin/typo3 install:setup -n --use-existing-database ..."
install_typo3 "v12" "^12" "$SETUP_CMD"
```
### 5. TYPO3 Version Differences
| Version | Setup Command | Database Creation | Extension Activation |
|---------|--------------|-------------------|---------------------|
| TYPO3 13 | `setup` | External (mysql) | `extension:setup` |
| TYPO3 12 | `install:setup --use-existing-database` | External (mysql) | Automatic |
## Installation Speed Comparison
| Method | v13 Install Time | Notes |
|--------|-----------------|-------|
| Bind mounts | ~10-15 min | ❌ Very slow on Windows |
| Volumes + sudo chown | ~3-5 min | ✅ Fast and working |
| Volumes (no chown) | N/A | ❌ Permission denied errors |
## Common Pitfalls
### ❌ Pitfall 1: Using Bind Mounts for Speed
```yaml
# Don't do this on Windows!
volumes:
- ./typo3-installations/v12:/var/www/html/v12
```
**Impact:** 3x slower installations
### ❌ Pitfall 2: Forgetting sudo chown
```bash
# This fails on Windows with volumes
echo "{}" > /var/www/html/v13/composer.json
# Permission denied!
```
### ❌ Pitfall 3: ASCII Encoding Corrupts Emojis
```powershell
# This breaks emojis in bash scripts
Set-Content -Encoding ASCII $file
```
### ❌ Pitfall 4: TYPO3 12 Database Creation
```bash
# This hangs/fails
vendor/bin/typo3 install:setup -n --database-name v12
# Missing: --use-existing-database
```
## Recommended Workflow
1. **Use skill templates** - They have the correct volume setup
2. **Add sudo chown** - Fix volume permissions (Windows-specific)
3. **Use UTF-8 encoding** - Preserve emojis when converting line endings
4. **Share install logic** - Use install-base for DRY principle
5. **Test both versions** - TYPO3 12 and 13 have different setup commands
## Windows-Specific .gitignore
```gitignore
# Don't commit these (Windows creates them)
.ddev/typo3-installations/
Thumbs.db
desktop.ini
```
## Quick Reference Commands
```powershell
# Convert to LF with UTF-8 (correct)
$file = '.ddev/commands/web/install-v13'
$content = Get-Content $file -Raw -Encoding UTF8
$content = $content -replace "`r`n", "`n"
[System.IO.File]::WriteAllText((Resolve-Path $file).Path, $content, [System.Text.UTF8Encoding]::new($false))
# Restart DDEV after config changes
ddev restart
# Check volume ownership
ddev exec ls -la /var/www/html/v13
# Fix permissions manually if needed
ddev exec sudo chown -R $(whoami):$(whoami) /var/www/html/v13
```