TYPO3 AI
Arrange a Call
de

Installing TYPO3 with DDEV: A Step-by-Step Guide

Sven Thelemann
TYPO3 CMS

TYPO3 development is most efficient when run in a containerized environment. DDEV provides a standardized local setup that removes system-specific configuration issues and ensures consistency across development teams.

Installing TYPO3 with DDEV: A Step-by-Step Guide

Why DDEV is used for TYPO3

DDEV simplifies TYPO3 development by providing a preconfigured Docker-based environment with all required services such as PHP, database, and web server. It eliminates manual setup and reduces environment-related errors.

Why Docker-based workflow matters

A Docker-based workflow ensures that TYPO3 runs in an isolated, reproducible environment. This means:

  • Consistent setup across all developers
  • No dependency conflicts on local machines
  • Easy project onboarding and replication
  • Production-like environment for safer development workflows

Quick Answer: Install TYPO3 with DDEV in 10 Minutes

You can set up a working TYPO3 local development environment using DDEV and Composer in a few steps.

5-Step Installation Flow

  1. Create a project directory

    mkdir typo3-project && cd typo3-project

  2. Initialize DDEV for TYPO3

    ddev config --project-type=typo3 --docroot=public --create-docroot

  3. Start the DDEV environment

    ddev start DDEV uses this configuration to build a consistent Docker-based environment containing PHP, database, and web server services specifically optimized for TYPO3 development.

  4. Install TYPO3 via Composer

    ddev composer create "typo3/cms-base-distribution:^12"

  5. Run the TYPO3 setup tool

    ddev launch typo3/install.php

Result

You get a fully functional TYPO3 development environment with web server, database, and email testing ready for local development.

User Intent Breakdown

This guide addresses different types of user intent behind searches for installing TYPO3 with DDEV.

Beginner Intent

Users who want a simple, step-by-step setup without deep technical knowledge. They expect:

  • Clear installation steps
  • Copy-paste commands
  • Minimal configuration complexity

Developer Intent

Users familiar with TYPO3, Composer, and Docker who want:

  • Structured DDEV project setup
  • TYPO3 Version compatibility details (v12–v14)
  • Clean local development workflow

Troubleshooting Intent

Users who already tried installation and face issues. They are looking for:

  • Fixes for setup errors
  • DDEV or Composer debugging
  • Database or install tool problems
  • Environment-related issues (ports, permissions, cache)

Agency / DevOps Intent

Teams or professionals setting up scalable environments who need:

  • Standardized TYPO3 development setup
  • Reusable DDEV configuration
  • Multi-project consistency
  • Production-aligned local environments

System Requirements

This section defines the minimum technical requirements needed to install and run TYPO3 with DDEV in a modern local development environment.

Core Requirements

Operating System Support

  • Windows (requires WSL2 for optimal DDEV performance)
  • macOS (Intel and Apple Silicon supported)
  • Linux (native support recommended for best performance)

Pre-Installation Checklist (Failure Prevention)

Before starting the installation, ensure your environment is properly prepared to avoid common setup errors.

Required Checks

  • Docker is installed and running
  • DDEV is installed and accessible via CLI
  • Composer is installed (version 2 or higher)
  • Required ports (80, 443, 3306) are not in use
  • System has sufficient memory (minimum 4GB, 8GB recommended for smooth TYPO3 operation)
  • Internet access is available for Composer package downloads

This checklist ensures a stable environment and prevents most common TYPO3 + DDEV installation failures before they occur.

Creating Installation Directory

This step sets up a clean workspace where the TYPO3 project will be installed.

Recommended Approach

Use a clear, project-specific naming convention that works well for agencies and multiple environments:

mkdir typo3-project && cd typo3-project

Why this structure matters

  • Avoids generic folder names like t3example
  • Improves clarity in multi-project setups
  • Aligns with agency-level development standards
  • Makes CI/CD and Git integration easier later

Creating a New DDEV Project

After preparing the project directory, initialize DDEV to create the TYPO3 development environment.

Basic Configuration Command

ddev config --project-type=typo3 --docroot=public --create-docroot

What this configuration does

  • Sets project type to TYPO3 (enables optimized defaults)
  • Defines public as the web root directory
  • Automatically creates the docroot if it does not exist
  • Generates a .ddev configuration for container setup

Why this step is important

DDEV uses this configuration to build a consistent Docker-based environment containing PHP, database, and web server services specifically optimized for TYPO3 development.

Starting the DDEV Project

After configuration, start the local development environment using DDEV. This initializes all required Docker containers for TYPO3.

ddev start

What happens when you start DDEV

DDEV spins up a complete local stack with the following services:

  • Web server container (Apache/Nginx + PHP)
  • Database container (MariaDB/MySQL)
  • Mailpit container (for email testing)

Important note

TYPO3 is not installed at this stage. This step only prepares the local runtime environment.

Installing TYPO3 via Composer

Once the DDEV environment is running, install TYPO3 using Composer inside the container.

ddev composer create “typo3/cms-base-distribution:^12”

Version compatibility (2026 standard)

  • TYPO3 v12 LTS → PHP 8.1
  • TYPO3 v13 LTS → PHP 8.2
  • TYPO3 v14 → PHP 8.3

Important note

During installation, you may be prompted to confirm overwriting existing files. This is expected in fresh project setups and should be accepted.

Running the TYPO3 Setup Tool

After installation, TYPO3 must be initialized using the setup process. You can do this in two ways:

Option 1: CLI Setup (Recommended for developers)

ddev exec ./vendor/bin/typo3 setup

This command launches an interactive setup wizard in the terminal.

Option 2: Browser Setup (Install Tool)

  1. Create the FIRST_INSTALL file:

    ddev exec touch public/FIRST_INSTALL

  2. Launch the installer:

    ddev launch typo3/install.php
  3. Complete the setup wizard in the browser

Summary

  • CLI setup is faster and automation-friendly
  • Browser setup is easier for beginners and first-time installations

Post-Installation Setup (High Value Section)

After TYPO3 is installed, the next step is to configure the system for first use. This ensures the backend, site configuration, and initial content structure are ready.

Backend Login Flow

  • Access the TYPO3 Backend via /typo3
  • Log in using the admin credentials created during setup
  • Verify successful access to the backend dashboard

Admin User Setup

  • Ensure the first admin user has full system permissions
  • Create additional backend users if working in a team environment
  • Assign appropriate roles and access levels where needed

Site Configuration

  • Define the main site in the Site Management module
  • Configure base URL (important for routing and links)
  • Set language settings and site identifier
  • Verify TypoScript template availability if required

First Page Creation

  • Create a root page in the page tree
  • Set it as the website root (using page properties)
  • Add initial content elements to validate frontend rendering

DDEV Architecture Explanation

Understanding how DDEV structures a TYPO3 project helps with debugging and long-term maintenance.

Container Structure

DDEV runs TYPO3 inside isolated Docker containers:

  • Web container: PHP runtime + web server
  • Database container: MariaDB/MySQL storage
  • Mailpit container: captures outgoing emails for testing

Why the public Folder is Used

  • Acts as the web root (document root)
  • Ensures only public assets are accessible via browser
  • Keeps system files outside public access for security

config.yaml Overview

The .ddev/config.yaml file defines:

  • Project type (TYPO3)
  • PHP version
  • Web server configuration
  • Port mapping and routing rules

This file ensures the environment is reproducible across all developer machines.

Datenbank- und E-Mail-Verwaltung (Services-Ebene)

DDEV provides built-in tools to manage database and email testing without external setup.

Database Access

ddev launch -p

  • Opens database management interface (e.g., phpMyAdmin/Adminer depending on setup)
  • Used to inspect and manage TYPO3 database tables

Email Testing

ddev launch -m

  • Opens Mailpit interface
  • Captures all outgoing TYPO3 emails locally
  • Useful for testing password resets and system notifications

Configuration Source

Database and mail settings are automatically configured in:

  • config/system/additional.php

Summary

  • Database and email are preconfigured in DDEV
  • No manual server setup required
  • Ideal for fast local development and testing workflows

Developer Tools Setup (DDEV + TYPO3)

This section focuses on improving debugging efficiency and developer productivity during TYPO3 development.

Xdebug Setup

  • Enable Xdebug in the DDEV project configuration
  • Configure IDE integration (PhpStorm / VS Code)
  • Use breakpoints for backend and frontend debugging
  • Validate PHP request flow inside TYPO3 controllers and Extbase

Logs Location

TYPO3 and DDEV logs are essential for debugging issues.

  • TYPO3 logs:
    • var/log/
  • System-level logs:
    • DDEV container logs via ddev logs
  • Web server logs:
    • Accessible through DDEV container output

Debugging Workflow

Recommended workflow for TYPO3 development:

  • Enable TYPO3 dev context if required
  • Use Xdebug for step-by-step execution
  • Monitor logs in real time using DDEV
  • Clear cache when configuration changes are not reflected
  • Validate database queries via debug tools or SQL inspection

Troubleshooting Common Issues

This section covers the most frequent issues encountered during TYPO3 + DDEV setup and their fixes.

Installation Fails

  • Check Composer version (must be 2.x)
  • Ensure sufficient memory limit for Composer
  • Verify correct TYPO3 package version

Port Conflicts (80/443/3306)

  • Stop conflicting services (Apache, MySQL, nginx)
  • Change DDEV ports if required
  • Restart DDEV environment

Composer Memory Errors

  • Increase PHP memory limit for CLI
  • Use COMPOSER_MEMORY_LIMIT=-1 if needed

Database Connection Failure

  • Ensure DDEV is running
  • Verify .env or configuration matches DDEV credentials
  • Restart database container

Permission Issues (Linux / WSL)

  • Fix file ownership inside project directory
  • Ensure correct user permissions for Docker volumes

Install Tool Not Loading

  • Ensure FIRST_INSTALL file exists in public/
  • Clear browser cache
  • Restart DDEV project

Reset / Reinstall TYPO3 in DDEV

This section explains how to safely reset or completely reinstall a TYPO3 project inside DDEV.

Full Project Reset

  • Stop DDEV project
  • Remove containers and volumes
  • Delete existing database

ddev delete --omit-snapshot

Clean Rebuild Workflow

  • Reinitialize project with ddev config
  • Reinstall TYPO3 via Composer
  • Re-run installation setup tool

Safe Reinstall Workflow

  • Backup necessary configuration if needed
  • Remove vendor and database
  • Re-run full installation process from scratch

Summary

This reset workflow ensures a clean state for debugging broken installations or recreating development environments quickly.

Performance & Best Practices

This section covers optimization techniques to ensure a faster and more stable TYPO3 development environment using DDEV.

Composer Optimization

  • Use composer install --optimize-autoloader for production-like performance
  • Prefer --no-dev for production builds (not local DDEV)
  • Regularly update dependencies to avoid outdated packages
  • Use Composer cache to speed up repeated installs

Cache Cleanup (TYPO3)

  • Clear TYPO3 cache after configuration changes
  • Use backend cache clearing or CLI commands when needed
  • Avoid stale cache issues during extension development

Dev vs Production Separation

  • Keep DDEV strictly for local development
  • Do not replicate production optimizations locally unless testing
  • Separate .env configurations for dev and production environments
  • Avoid enabling production caching strategies in local setups

Security Notes (Local Development)

This section highlights security considerations when running TYPO3 in a local DDEV environment.

Local HTTPS Trust (mkcert concept)

  • DDEV supports HTTPS via locally trusted certificates
  • Use mkcert-based trust for secure local development
  • Ensures browser behaves like production environment

Development Environment Warning

  • Do not use DDEV configuration in production
  • Local setups may expose debug tools and verbose errors
  • Disable debugging features before deployment
  • Keep credentials and sensitive data isolated from production systems

Conclusion

TYPO3 Installation with DDEV provides a fast, reliable, and reproducible local development environment. By combining Docker, Composer, and DDEV, you get a fully containerized setup that eliminates system dependency issues and standardizes development across teams.

If you follow this guide, you now have:

  • A working TYPO3 local development environment
  • A Composer-based project structure
  • A fully configured DDEV setup with database and email support
  • A repeatable workflow for future projects

Next Steps

  • Start building your TYPO3 site structure
  • Install required extensions based on project needs
  • Configure TypoScript and site settings
  • Move towards production deployment when ready

FAQs

Yes. TYPO3 v12, v13, and v14 all work with DDEV when using compatible PHP versions (8.1–8.3 depending on TYPO3 version).

Yes. DDEV is built on Docker, so Docker is mandatory for running TYPO3 in this setup.

Common reasons include:

  • Incorrect Composer version
  • Missing PHP memory allocation
  • Port conflicts
  • Incomplete DDEV setup
  • Missing database connection during setup

Yes. DDEV is only a local development environment. You can migrate files, database, and configuration to any production server.

This message appears when the setup process has not been completed. You must run the TYPO3 setup tool (setup or install.php) after Composer installation.

Yes. Modern TYPO3 installations (v12+) are Composer-based and require Composer for dependency management.

Contact for Internet agency and TYPO3 projects

Sven Thelemann

Service Partner - Germany

st@nitsantech.de +49 351 48196661
Sven Thelemann

Sven Thelemann

Client Service Lead

Sven Thelemann serves as the Client Service Lead at NITSAN, focusing on delivering TYPO3 solutions that meet client goals. With a strong understanding of technology and client expectations, he ensures smooth communication and project execution. Outside of work, Sven enjoys cycling and experimenting with homemade recipes.

Comments and Responses

×

Name is required!

Enter valid name

Valid email is required!

Enter valid email address

Comment is required!

* These fields are required.

Be the First to Comment