TYPO3 Gitlab CI/CD Auto Deployment (2024)

Are you looking for best practices to automate TYPO3 deployment? This article will find official TYPO3’s standard deployment using Gitlab CI/CD, deployer, code review, frontend build, docker/ddev, prepare dev/staging/production environments, etc. Read this article to know the best practices for TYPO3 DevOps.

TYPO3 development and deployment in 2023! My friend, I hope you are still not manually deploying your TYPO3 project like old-school SFTP. Even if you are still using a manual TYPO3 deployer or surf to deploy TYPO3 with some SSH commands, it’s time to make it completely automated using TYPO3 Gitlab CI/CD. This article explains the architecture of the official TYPO3 team (demo.typo3.org).

Before we start, I want to dedicate this article to the team of demo.typo3.org, benni, and B13 company, who developed and shared a better way to deploy the TYPO3 project https://git.typo3.org/services/demo.typo3.org/site #T3Kudos to everyone for the contribution, Thanks a lot.

Are you excited to begin the journey of TYPO3 + Gitlab + CI/CD? Let’s go!

Let’s stop theory knowledge, and let’s practically know what kind of steps need to be performed to auto-deploy TYPO3 using Gitlab CI/CD.

Step 1. `git push` You make code changes and commit to Git.

Step 2. Start TYPO3 Gitlab pipeline runners.

Step 3. Done! If everything goes well, your new code will `deploy to server`.

Just run the command `git push` and boom! Isn’t it cool, huh?

You will need to start with modern technologies to develop and deploy TYPO3 projects efficiently.

• Operating System (recommended UNIX based)
• Docker >= 18.x
• Docker Composer >= 3.x
• DDEV
• Composer >= 2.x
• PHP >= 7.4.x
• Deployer >= 6.x
• PHPStan and PHP-CS-Fixer
• Nodejs/Webpack (optional)

For your first experience and testing purpose, we highly recommend to g

// Download code
git clone git.typo3.org/services/demo.typo3.org/site.git

// Install composer packages
ddev composer install

// Build the frontend
ddev composer frontend-builds

// Get database and fileadmin using
ddev pull dump

// Update schema
ddev typo3cms database:updateschema

// Create a backend user
ddev typo3cms backend:createadmin username password

// Start the project running
ddev start

Let’s take a quick look at the architecture of TYPO3 DevOps which has been designed at demo.typo3.org.

Initially you will find basic configuration like Deployer, TYPO3 configuration, Sites config, etc.

- .ddev
- build
  -- deploy.php
  -- servers.yml
- config
  -- AdditionalConfiguration (development, production)
  -- sites (site configuration)
- src
  -- extensions
  -- webpack
- web
  -- LocalConfiguration.php
  -- AdditionalConfiguration.php
- composer.json
- .gitlab-ci.yml

Here are the important information instructions to understand local development and TYPO3 DevOps setup.

build/deploy.php

Contains PHP Deployer recipe, It’s just a simple PHP script - I’m sure you will easily understand.

build/servers.yml

Information about all your servers like Staging/Production, it will use in deploy.php

config/AdditionalConfiguration/*Context.php

You can configure TYPO3 installation based on your server needs like Local or Production.

src/extensions/*

Add your custom developed TYPO3 extensions e.g, your template extension.

.env

Contains TYPO3 environment variables.

Before you start and understand the Gitlab CI architecture, I hope you have some basic knowledge of SSH commands. Otherwise, you should consider to learn basic UNIX commands and utilities.

Here is the base setup of .gitlab-ci.yml which is the standard of the Gitlab.org OpenSource project.

Define Deployment Stages

stages:
  - maintenance
  - lint
  - build
  - build-frontend
  - deploy

Initiate Global Variables & Cache

variables:
  ssh_hosts: "yourserver.com"
  build_frontend_path: "src/webpack"
  # see getcomposer.org/doc/03-cli.md
  COMPOSER_CACHE_DIR: ".composer-cache"
  composer_options:  "--no-progress --no-interaction"

# These files/folders are untracked, but should be kept between stages
cache:
  key: composer-cache-files
  paths:
    - "$COMPOSER_CACHE_DIR"
    - "$build_frontend_path/node_modules"

Connect with SSH Server

.prepare_ssh: &prepare-ssh
  before_script:
    - apk add rsync --update
    - eval $(ssh-agent -s)
    - echo -e "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null
    - mkdir -p ~/.ssh && chmod 700 ~/.ssh
    - ssh-keyscan "$ssh_hosts" >> ~/.ssh/known_hosts
    - chmod 644 ~/.ssh/known_hosts

For the TYPO3 automatic code review (aka code lints test), you can consider PHP, Fluid, TypoScript, YML etc. Here is an example of PHP code review using PHPStan + PHP-CS-Fixer.

# Runs tests, currently it runs phpstan + php-cs-fixer
code-analysis:php:
  stage: lint
  image: composer:2.1.8
  before_script:
    - composer install --ignore-platform-reqs $composer_options
  script:
    - if [ -e bin/phpstan ]; then php -d memory_limit=2G ./bin/phpstan analyse; fi
    - if [ -e bin/php-cs-fixer ]; then php -d memory_limit=2G ./bin/php-cs-fixer fix --config=.php_cs -v --dry-run --stop-on-violation --using-cache=no; fi

Now it’s time to build the whole TYPO3 artifact composer setup, It will create whole TYPO3 setup.

# Builds the artifacts for the production system (composer first)
build:php:
  stage: build
  image: composer:2.1.8
  script:
    - composer install --no-dev -o -a --ignore-platform-reqs $composer_options
  artifacts:
    paths:
      - bin
      - web
      - src
      - config
      - vendor
      # needed to have the deployer tool available
      - build
    expire_in: '2h'
  only:
    - tags
    - main
    - develop

Most modern TYPO3 projects use webpack framework to bundle JavaScript and SASS/LESS based CSS files. Let’s build frontend.

# compile and build JS / CSS
# should be used in conjunction with an artifact
.frontend_bootstrap: &frontend-bootstrap
  image: node:14.16-buster
  variables:
    node_path: src/webpack
  script:
    - cd $build_frontend_path
    - yarn install
    - yarn build-prod

Everything is ready! It’s time to deploy it to production or staging with below CI/CD.

# rsyncs the artifacts to the target server via deployer
.deploy: &deploy
  <<: *prepare-ssh
  image: composer:2.0.8
  variables:
    # no git needed, only the artifacts are required
    GIT_STRATEGY: none
    TARGET_HOSTS: ""
  script:
    - composer global require deployer/deployer deployer/recipes --dev $composer_options
    - /tmp/vendor/bin/dep --file=./build/deploy.php deploy -vv --hosts=${TARGET_HOSTS}

deploy:production:
  <<: *deploy
  stage: deploy
  variables:
    TARGET_HOSTS: "main,contentmaster"
  only:
    - tags
    - main
  dependencies:
    - build-frontend

deploy:staging:
  <<: *deploy
  stage: deploy
  variables:
    TARGET_HOSTS: "staging"
  only:
    - develop

Last but not the least, of course, you should consider optimizing and modifying the structure according to your needs e.g., Remove content context which is used by demo.typo3.org to reset the whole TYPO3 content context ;)

You may also like to read more articles on the TYPO3 deployment as below.

• How to Automise Your TYPO3 Deployment (with PHP Deployer)
• How to Configure PHP Deployer in TYPO3?
• 8 Best TYPO3 Docker Development Approaches
• How to Auto-Release TYPO3 Extension with Github?
• 8 Ways to Publish Your TER TYPO3 Extensions
• The Best Guide to TYPO3 Composer

Thanks for reading my blog. I hope you like it and found it helpful.

I highly recommend giving it a try! If you are still working as a traditional TYPO3 developer (with the old-school manual deployment) then you should take the challenge and set up TYPO3 CI/CD auto-deploy - with the goal and vision of 2023! If you are getting stuck then feel free to write to the comment box, I'll be happy to help you.

Oh! Are you already doing great with TYPO3 DevOps? Great, What’s your favorite way of TYPO3 deployment? I always love to learn new things.