Initial commit
This commit is contained in:
Zhongwei Li
288
references/advanced-options.md
Normal file
288
references/advanced-options.md
Normal 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)
|
||||
|
||||
Reference in New Issue
Block a user