Deploying TYPO3

This guide explains how to deploy a TYPO3 project to a production environment securely and efficiently. It covers both manual deployment and automated strategies using deployment tools.

TYPO3 can be deployed in various ways. A common and simple approach is to copy files and the database from a local environment to the live server.

However, for larger or more professional projects, automated deployments using tools are highly recommended.

Table of contents

What is deployment and why do I need it?

It is recommended to develop TYPO3 projects locally on your computer using, for example, Docker, DDEV, or a local PHP and database installation. At some point you will want to transfer your work to the server for a first initial deployment, which can be done manually or semi-manually.

As time goes on, you will fix bugs, prepare updates and develop new features on your local computer. These changes will then need to be transferred to the server. This can be done manually or can be automated.

Deployment can only be avoided if you Install and use TYPO3 directly on the server, which comes with a number of Quick wins & pitfalls.

Manual deployment of a Composer-based installation

The deployment process for TYPO3 can be divided into two parts:

  1. Initial Deployment – the first time the project is set up on the server.
  2. Regular Deployment – ongoing updates to code or configuration.

Initial deployment

This is the first deployment of TYPO3 to a production environment. It includes setting up the full application, database, and user-generated content.

Steps:

  1. Build the project locally:

    composer install --no-dev
    Copied!

  2. Export the local database using mysqldump, ddev export-db, or a GUI-based tool like Heidi SQL or phpmyadmin.

    mysqldump -u <user> -p -h <host> <database_name> > dump.sql
    Copied! 
    ddev export-db --file=dump.sql
    Copied!

  3. Transfer all necessary files to the server.

    Folders to include:

    • public/
    • config/
    • vendor/,
    • Files from the project directory: composer.json, composer.lock

    You can speed up the transfer using archive tools like zip or tar, or use rsync.

  4. Import the database on the production server, for example using mysql:

    mysql -u <user> -p -h <host> <database_name> < dump.sql
    Copied!

  5. Set up shared and writable directories on the server:

    • public/fileadmin/
    • var/

  6. Adjust web server configuration:

    • Set the document root to public/
    • Ensure correct permissions for writable folders

  7. Flush TYPO3 caches:

    ./vendor/bin/typo3 cache:flush
    Copied!

Regular deployment

After the initial deployment, regular deployments are used to update code and configuration.

Steps:

  1. Prepare the updated version locally:

    • Apply code or configuration changes

    • Run:

      composer install --no-dev
      Copied!

  2. Transfer only updated files to the server.

    Include:

    • public/ (excluding fileadmin/, uploads/)
    • config/
    • vendor/
    • composer.lock
    • etc.

    Do not include dynamic or environment-specific files such as:

    • var/, public/fileadmin/, (these are managed on the server)

    You can speed up the transfer using archive tools like zip or tar, or use rsync to copy only changed files.

  3. If database changes are required:

    • Run the Upgrade Wizard in the TYPO3 backend
    • Or apply schema changes via CLI tools

  4. Flush TYPO3 caches:

    ./vendor/bin/typo3 cache:flush
    Copied!

Deployment Automation

A typical setup for deploying web applications consists of three different parts:

  • The local environment (for development)
  • The build environment (for reproducible builds). This can be a controlled local environment or a remote continuous integration server (for example Gitlab CI or Github Actions)
  • The live (production) environment

To get an application from the local environment to the production system, the usage of a deployment tool and/or a continuous integration solution is recommended. This ensures that only version-controlled code is deployed and that builds are reproducible. Ideally setting a new release live will be an atomical operation and lead to no downtime. If there are errors in any of the deployment or test stages, most deployment tools will initiate an automatic "rollback" preventing that an erroneous build is released.

One widely employed strategy is the "symlink-switching" approach:

In that strategy, the webserver serves files from a virtual path releases/current/public which consists of a symlink releases/current pointing to the latest deployment ("release"). That symlink is switched after a new release has been successfully prepared. The latest deployment contains symlinks to folders that should be common among all releases (commonly called "shared folders").

Usually the database is shared between releases and upgrade wizards and schema upgrades are run automatically before or shortly after the new release has been set live.

This is an exemplatory directory structure of a "symlink-switching" TYPO3 installation:

  • shared

    • fileadmin

    • var

      • charset
      • lock
      • log
      • session

  • releases

    • current -> ./release1 (symlink to current release)

    • release1

      • public (webserver root, via releases/current/public)

        • typo3conf
        • fileadmin -> ../../../shared/fileadmin (symlink)
        • index.php

      • var

        • build
        • cache
        • charset -> ../../../shared/var/charset (symlink)
        • labels
        • lock -> ../../../shared/var/lock (symlink)
        • log -> ../../../shared/var/log (symlink)
        • session -> ../../../shared/var/session (symlink)
      • vendor
      • composer.json
      • composer.lock

The files in shared are shared between different releases of a web site. The releases directory contains the TYPO3 code that will change between the release of each version.

When using a deployment tool this kind of directory structure is usually created automatically.

The following section contains examples for various deployment tools and how they can be configured to use TYPO3: