Install TYPO3 with Docker - Fast & Reliable Setup Guide (2026 Edition)

git clone https:// github.com/webdevops/TYPO3-docker-boilerplate.git my-typo3-project
cd my-typo3-project
cp docker-compose.development.yml docker-compose.yml
docker-compose up -d

After the containers start:

• Place or connect your TYPO3 project inside the application directory used by the setup.
• Choose the right web stack, such as Nginx or Apache, based on your hosting preference.
• Configure the database, PHP version, environment files, and required services.
• Enable optional services like Redis, Solr, or Elasticsearch only if the project needs them.
• Test the TYPO3 backend, frontend, file handling, and database connection before using it in a team workflow.

WebDevOps is useful for agencies and enterprise teams that need Docker to support more than basic local development. For production, review security, persistent storage, environment variables, backups, and exposed ports before deployment.

TYPO3 Docker Images Compared

Different TYPO3 Docker images serve different goals. Some are built for quick local development, while others work better as a base for structured team workflows or production-controlled setups.

For most developers, DDEV is the safest local development choice. For agencies and larger teams, WebDevOps or a custom Docker Compose setup gives more control over services and environments.

For production-focused TYPO3 projects, do not choose an image only because it is easy to start. Check maintenance status, supported TYPO3/PHP versions, image tags, security updates, persistent volumes, environment handling, and backup strategy before using it in a live setup.

Managing Volumes and Data Persistence in TYPO3 Docker

Volumes are critical in TYPO3 Docker because they keep website data safe when containers are stopped, rebuilt, or replaced.

Without proper volume mapping, uploads, database records, configuration files, and cached assets can disappear during a container rebuild.

Important TYPO3 data to persist:

• fileadmin/ – stores uploaded media, documents, images, and site assets
• uploads/ – stores backend-uploaded files in older or specific TYPO3 setups
• typo3conf/ – stores configuration, extensions, and project-specific settings
• var/ or typo3temp/ – stores cache, logs, and temporary files depending on the TYPO3 version
• Database volume – stores pages, users, content records, backend data, and site configuration

Example Docker volume mapping:

services:
 web:
   image: webdevops/php-apache:8.2
   volumes:
     - .:/var/www/html
     - fileadmin:/var/www/html/public/fileadmin
     - uploads:/var/www/html/public/uploads
     - typo3conf:/var/www/html/public/typo3conf
 db:
   image: mariadb:10.6
   volumes:
     - dbdata:/var/lib/mysql
volumes:
 fileadmin:
 uploads:
 typo3conf:
 dbdata:

Common mistake: storing uploaded files or database data only inside the container. When that container is recreated, the data can be lost.

For team projects, keep a clear process for sharing sanitized database dumps and file bundles, so every developer can work with a safe and updated local TYPO3 environment.

A reliable TYPO3 Docker setup should always separate temporary container files from permanent project data.

TYPO3 Docker Best Practices

A strong TYPO3 Docker setup should be stable, secure, repeatable, and easy for the team to maintain.

Follow these best practices:

• Separate environments: Use different settings for development, staging, and production.
• Use Composer properly: Keep composer.json and composer.lock version-controlled for reproducible builds.
• Pin important versions: Avoid unstable PHP, TYPO3, and image tags in serious projects.
• Use .env files carefully: Store environment values separately, but never expose sensitive credentials.
• Enable OPcache: Improve TYPO3 performance by caching compiled PHP code.
• Use Redis when needed: Add Redis for larger TYPO3 projects with heavier caching requirements.
• Persist important data: Map volumes fileadmin/, uploads, configuration files, and database storage.
• Avoid dev settings in production: Disable debug mode, development tools, and unnecessary logging.
• Keep services internal: Do not expose database, Redis, or admin tools publicly unless required and secured.
• Document common commands: Make it easy for developers to start, stop, rebuild, reset, and debug the setup.

Example command shortcuts:

up:

    docker-compose up -d

down:

    docker-compose down

logs:

    docker-compose logs -f

reset:

    docker-compose down -v
    docker-compose up -d

Before using TYPO3 Docker in staging or production, review security, backups, persistent storage, PHP settings, and exposed ports.

Common TYPO3 Docker Issues and Fixes

Most TYPO3 Docker issues come from wrong configuration, missing services, incorrect permissions, or unmapped volumes.

Useful diagnostic commands:

docker-compose logs -f
docker ps
docker-compose logs db

For DDEV projects:

ddev logs
ddev describe
ddev composer diagnose

Also check TYPO3 logs inside:

var/log/
var/log/typo3.log

Before rebuilding containers, always confirm that the database and uploaded files are stored in persistent volumes.

Dockerising an Existing TYPO3 Project

An existing TYPO3 project can be moved into Docker safely when the files, database, Composer setup, and environment values are mapped correctly.

Before starting, check:

• Database backup: Export a clean database dump before making changes.
• Project structure: Confirm whether the project is Composer-based or legacy.
• Web root: Check whether TYPO3 runs from public/, web/, or another document root.
• File storage: Move fileadmin/, uploads, and media assets without changing references.
• Configuration: Review typo3conf/, environment variables, database credentials, and local settings.
• PHP compatibility: Match the Docker PHP version with the TYPO3 version and installed extensions.
• Persistent volumes: Keep database data and uploaded files outside the temporary container filesystem.

Basic migration flow:

mysqldump -u USER -p OLD_DATABASE > typo3-backup.sql
mkdir my-typo3-docker
cd my-typo3-docker
# Add DDEV, WebDevOps, or custom Docker setup
# Copy TYPO3 project files into the correct web root
# Import the database into the Docker database container

If the project is still using a legacy non-Composer structure, document the web root, extensions, and custom paths before moving it. For long-term maintainability, consider converting the project to a Composer-based setup during the migration.

The safest approach is to test the Dockerized TYPO3 project locally first. Check backend login, frontend pages, media files, forms, extensions, redirects, and file references before moving the setup to staging or production.

TYPO3 Docker Performance Optimization

TYPO3 Docker performance depends on PHP tuning, caching, database configuration, file handling, and how cleanly the services are separated.

Key optimization steps:

• Enable OPcache: Cache compiled PHP code to improve TYPO3 response time.
• Use Redis for caching: Add Redis for larger websites, complex content structures, or high-traffic projects.
• Optimize the database: Review indexes, slow queries, memory settings, and connection limits.
• Keep images lightweight: Avoid unnecessary packages inside Docker images.
• Separate services: Run PHP, web server, database, cache, and search as separate services.
• Tune TYPO3 caching: Choose cache backends based on project size and traffic needs.
• Avoid dev settings in production: Disable debug mode, development tools, and excessive logging.
• Check file sharing performance: On macOS or Windows, large fileadmin/ folders can slow Docker down. Use Docker Desktop performance settings, DDEV performance tips, or WSL2 on Windows.

For staging and production, test performance in an environment close to the live setup. Check backend speed, frontend load time, database queries, cache behavior, and media processing before release.

Security Best Practices for TYPO3 Docker

Security is important when TYPO3 Docker is used beyond local development, especially for staging and production projects.

Follow these security practices:

• Separate dev, staging, and production settings: Do not use local development settings on live websites.
• Protect environment variables: Avoid exposing database passwords, API keys, and backend credentials.
• Use Docker secrets where possible: Keep sensitive values safer than plain environment variables.
• Force HTTPS in production: Use SSL and secure web server configuration.
• Set TYPO3 context correctly: Use production context for live environments.
• Disable debug mode: Keep error details hidden from public users.
• Limit container access: Run only required services and avoid unnecessary open ports.
• Keep images updated: Use maintained base images and update security patches regularly.

A secure TYPO3 Docker setup should keep sensitive data protected, separate environments clearly, and avoid exposing development tools on production servers.

TYPO3 Docker in CI/CD Pipelines

CI/CD helps TYPO3 teams test, build, and deploy Docker-based projects with fewer manual errors.

A basic TYPO3 Docker CI/CD flow includes:

• Code push: Developer pushes changes to Git.
• Dependency check: Composer installs and validates required TYPO3 packages.
• Docker build: The pipeline builds a versioned TYPO3 Docker image.
• Automated testing: TYPO3 checks, PHP checks, and basic frontend/backend tests run before deployment.
• Staging deployment: The tested image is deployed to a staging environment first.
• Production release: After approval, the same image moves to production.
• Rollback plan: Previous image versions are kept ready in case the new release fails.

For safer deployments, avoid building directly on the production server. Build the image once, test it properly, and then promote the same version across staging and production.

Migration Guide – Moving TYPO3 to Docker

Moving TYPO3 to Docker requires proper handling of the database, uploaded files, Composer setup, and environment configuration.

Follow this migration checklist:

• Export the database: Take a full backup before changing the setup.
• Check project structure: Confirm whether the project is Composer-based or legacy.
• Move uploaded files: Transfer fileadmin/, uploads, and other user-generated assets.
• Map configuration files: Review TYPO3 settings, database credentials, and environment-specific values.
• Align Composer: Make sure composer.json and composer.lock match the TYPO3 version.
• Create Docker services: Set up PHP, web server, database, cache, and required extensions.
• Test locally first: Check backend login, frontend pages, media files, forms, and extensions.
• Move to staging: Validate the Docker setup before using it in production.

The biggest migration risks are missing uploaded files, incorrect database credentials, broken file paths, wrong PHP versions, and unmapped persistent volumes.

When Should You Use TYPO3 with Docker?

Use TYPO3 with Docker when the project needs a stable, repeatable, and team-friendly development setup.

Docker is a good choice for:

• Agency projects: Multiple developers need the same setup.
• Enterprise websites: The project has complex services, staging workflows, or long-term maintenance needs.
• Composer-based TYPO3 projects: Dependencies need to stay controlled and versioned.
• Multi-environment workflows: Development, staging, and production need better consistency.
• CI/CD deployments: The team wants automated testing and controlled releases.

Docker may not be necessary for a very small TYPO3 Website managed by one person on simple hosting. But for professional TYPO3 development, team workflows, and scalable projects, Docker is usually the better long-term setup.

Conclusion

TYPO3 Docker makes development faster, cleaner, and easier to manage, especially for teams working with complex CMS projects. With the right setup, developers can avoid environment issues, manage dependencies better, protect project data, and prepare TYPO3 websites for smoother testing, staging, and deployment.

For local development, DDEV is the easiest starting point. For advanced projects, WebDevOps or a custom Docker Compose setup gives more control over services, performance, security, and production workflows.

If your TYPO3 website is running on an older version or outdated setup, this is the right time to plan a TYPO3 Upgrade. A proper upgrade can improve security, performance, compatibility, and long-term stability while making your website easier to maintain.

Need help with a TYPO3 upgrade or Docker-based TYPO3 setup? Contact our TYPO3 experts to upgrade, optimize, and modernize your TYPO3 website with a stable development and deployment workflow.