https://github.com/sourcebroker/deployer-typo3-deploy-ci
TYPO3 CMS deployment with deployer at CI level.
https://github.com/sourcebroker/deployer-typo3-deploy-ci
deployer deployment typo3
Last synced: 3 months ago
JSON representation
TYPO3 CMS deployment with deployer at CI level.
- Host: GitHub
- URL: https://github.com/sourcebroker/deployer-typo3-deploy-ci
- Owner: sourcebroker
- License: mit
- Created: 2025-03-01T15:04:49.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-19T20:51:44.000Z (12 months ago)
- Last Synced: 2025-08-04T11:05:47.005Z (10 months ago)
- Topics: deployer, deployment, typo3
- Language: PHP
- Homepage:
- Size: 101 KB
- Stars: 0
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.rst
- License: LICENSE.txt
Awesome Lists containing this project
README
deployer-typo3-deploy-ci
========================
[](https://packagist.org/packages/sourcebroker/deployer-typo3-deploy-ci) [](https://packagist.org/packages/sourcebroker/deployer-typo3-deploy-ci)
## Contents
- [Introduction](#introduction)
- [Installation](#installation)
- [Stages](#stages)
- [Variables](#variables)
- [Deployer Tasks](#deployer-tasks)
- [Own repo for overwrites](#own-repo-for-overwrites)
- [Example configs](#example-configs)
## Introduction
This is a template for TYPO3 CMS projects that need continuous integration and deployment.
For now, it uses only GitLab CI/CD (Deployer).
**The aim is to have minimal config at `gitlab-ci.yml` of projects and keep the base of CI/CD config outside of projects'
repositories.**
You can use this repository in several possible ways:
1. Reference it from your project with "include remote" and overwrite at your project's `gitlab-ci.yml`.
2. Reference it from your project with "include remote", then overwrite it with "include remote" from your own special
repo and finally overwrite edge cases at the project's `gitlab-ci.yml`.
The worst possible scenario you can use is to copy all CI/CD files to your project repository and maintain them there
for each project. This is not recommended as it will be hard for you to maintain and upgrade in the future if you have
several dozen projects and each has its own CI/CD config inside the project's repo.
## Installation
1. Install with composer:
```sh
composer require sourcebroker/deployer-typo3-deploy-ci
```
2. Create a file `gitlab-ci.yml` in the root of your project and put the content below.
```yaml
include:
- remote: https://raw.githubusercontent.com/sourcebroker/deployer-typo3-deploy-ci/2.0.0/ci/provider/gitlab/main.yaml
variables:
PHP: '8.2'
NODE: '20'
DEPLOY_TRIGGER_BY_CI_COMMIT_BRANCH: /^(develop|main)$/
DEPLOYER_SELECTOR_FOR_BRANCH: develop:staging,main:preprod
DEPLOYER_SELECTOR_FOR_TAG: prod
```
Adapt the tag version in the include remote URL. This version should be the same as the version of `deployer-typo3-deploy-ci`
installed in your project in step 1 with composer. Use: `composer show | grep 'sourcebroker/deployer-typo3-deploy-ci'`
to see the version of the `deployer-typo3-deploy-ci` installed in your project.
If after pushing the pipeline does not start at all, check the `TEST_TRIGGER_BY_CI_COMMIT_BRANCH` value. The name
of the branch you push to must be inside the pregmatch of `TEST_TRIGGER_BY_CI_COMMIT_BRANCH`.
3. **Backend test**.
The command for backend test is defined in `BACKEND_COMMAND_TEST` and has the value:
```sh
composer install --prefer-dist --no-progress --no-interaction --optimize-autoloader && composer test
```
You can either overwrite it in your `gitlab-ci.yml` or you can just add a `test` script in your `composer.json`.
4. **Frontend test**.
The command for frontend test is defined in `FRONTEND_COMMAND_TEST` and has the value:
```sh
cd assets && npm ci && npm run test
```
This is probably a part you would like to overwrite as this is very custom and not normalized in the TYPO3 world.
Just change `FRONTEND_COMMAND_TEST` to your needs in your `gitlab-ci.yml`.
5. **Build the backend**.
The command for backend build is defined in `BACKEND_COMMAND_BUILD` and has the value:
```sh
composer install --prefer-dist --no-progress --no-interaction --optimize-autoloader --no-dev
```
You probably do not want to overwrite it as this is the default for all PHP projects.
6. **Build the frontend**.
The command for frontend build is defined in `FRONTEND_COMMAND_BUILD` and has the value:
```sh
cd assets && npm ci && npm run prod
```
You can either overwrite it in your `gitlab-ci.yml`. If you modify the `FRONTEND_COMMAND_TEST` command, remember
to also modify the `FRONTEND_FOLDER_BUILD_1`.
7. **Deploy**.
Add the `SSH_PRIVATE_KEY` variable to your GitLab project CI/CD settings as a "mask variable". This variable holds
the private key for the user that will deploy the project from the deployer level. Prepare this `SSH_PRIVATE_KEY`
with the following command: `cat privatekey | base64 -w0` and on mac: `cat privatekey | base64 -b0`
8. Define your deployer configuration in your project's `deploy.php` file. Example of a real working configuration:
```php
'sourcebroker/deployer-typo3-deploy-ci'],
]);
task('deploy:writable')->disable(); // Disable deploy:writable task if httpd user is the same as ssh user.
host('prod')
->setHostname('vm-dev.example.com')
->setRemoteUser('project1')
->set('bin/php', '/usr/bin/php8.4')
->set('public_urls', ['https://t3base13.example.com'])
->set('deploy_path', '~/t3base13.example.com/prod');
host('preprod')
->setHostname('vm-dev.example.com')
->setRemoteUser('project1')
->set('bin/php', '/usr/bin/php8.4')
->set('public_urls', ['https://preprod-t3base13.example.com'])
->set('deploy_path', '~/t3base13.example.com/preprod');
host('staging')
->setHostname('vm-dev.example.com')
->setRemoteUser('project1')
->set('bin/php', '/usr/bin/php8.4')
->set('public_urls', ['https://staging-t3base13.example.com'])
->set('deploy_path', '~/t3base13.example.com/staging');
```
9. Push the changes to your repository and see the pipeline at your project.
## Stages
- **Init Stage** (`ci/provider/gitlab/config/300-init.yaml`): Initializes the environment.
- **Test Stage**:
- **Backend Tests** (`ci/provider/gitlab/config/400-test-backend.yaml`): Runs backend tests.
- **Frontend Tests** (`ci/provider/gitlab/config/410-test-frontend.yaml`): Runs frontend tests.
- **Build Stage**:
- **Backend Build** (`ci/provider/gitlab/config/500-build-backend.yaml`): Builds the backend.
- **Frontend Build** (`ci/provider/gitlab/config/510-build-frontend.yaml`): Builds the frontend.
- **Deploy Stage** (`ci/provider/gitlab/config/600-deploy.yaml`): Deploys the application using Deployer.
## Variables
- **Variables** (`ci/provider/gitlab/config/100-variables.yaml`):
- `PHP` PHP version for backend test and build.
- `NODE` PHP version for frontend test and build.
- `TEST_TRIGGER_BY_CI_COMMIT_BRANCH` Regexp for branches that trigger the pipeline for test only.
- `TEST_TRIGGER_BY_CI_COMMIT_TAG` Regexp for tags that trigger the pipeline for test only.
- `DEPLOY_TRIGGER_BY_CI_COMMIT_TAG` Regexp for tags that trigger deployment.
- **Backend Variables** (`ci/provider/gitlab/config/110-variables-backend.yaml`):
- `BACKEND_COMMAND_TEST` Command to run backend tests.
- `BACKEND_COMMAND_BUILD` Command to build the backend.
- `BACKEND_IMAGE` Docker image for the backend.
- `BACKEND_FOLDER_BUILD_*` Paths for backend build artifacts.
- **Frontend Variables** (`ci/provider/gitlab/config/120-variables-frontend.yaml`):
- `FRONTEND_COMMAND_TESTS` Command to run frontend tests.
- `FRONTEND_COMMAND_BUILD` Command to build the frontend.
- `FRONTEND_IMAGE` Docker image for the frontend.
- `FRONTEND_FOLDER_BUILD_*` Paths for frontend build artifacts.
- **GitLab Variables** (`ci/provider/gitlab/config/130-variables-gitlab.yaml`):
- `FF_USE_FASTZIP` Enable fast zip for artifacts.
- `ARTIFACT_COMPRESSION_LEVEL` Compression level for artifacts.
- `CACHE_COMPRESSION_LEVEL` Compression level for cache.
- `TRANSFER_METER_FREQUENCY` Frequency of transfer meter updates.
- `DOCKER_DRIVER` Docker driver to use.
- `DOCKER_BUILDKIT` Enable Docker BuildKit.
- `BUILDKIT_INLINE_CACHE` Enable inline cache for BuildKit.
- `COMPOSE_DOCKER_CLI_BUILD` Enable Docker CLI build for Compose.
- **Deployer**
- `DEPLOYER_SELECTOR_FOR_BRANCH` Mapping of GitLab branch to Deployer selector. It is a collection of `branch:deployer_selector`
pairs separated by commas. Example: `develop:staging,main:preprod`.
- `DEPLOYER_SELECTOR_FOR_TAG` Deployer selector to be used when tag is pushed. Example: `prod`.
- `DEPLOYER_OPTIONS` Additional options for Deployer.
## Deployer Tasks
The project uses Deployer for deployment tasks. The configuration files are located in the `deployer/default` directory.
- **Cache Management**:
- `typo3:cache:flush:pages` Flushes TYPO3 CMS page cache.
- `typo3:cache:warmup:system` Warms up TYPO3 CMS system cache.
- **Extension Management**:
- `typo3:extension:setup` Sets up TYPO3 CMS extensions.
- **Language Management**:
- `typo3:language:update` Updates TYPO3 CMS languages.
- **Deployment**:
- `deploy:upload_build` Uploads the build to the server.
- `deploy-ci` Main deployment task for continuous integration.
## Own Repo for Overwrites
You may be interested in creating your own repo with values for overwriting variables of `sourcebroker/deployer-typo3-deploy-ci`.
Good candidates for overwrites are `DEPLOY_TRIGGER_BY_CI_COMMIT_BRANCH`, `DEPLOYER_SELECTOR_FOR_BRANCH`, `DEPLOYER_SELECTOR_FOR_TAG`, `FRONTEND_COMMAND_TEST`, `FRONTEND_COMMAND_BUILD`.
Then you should add your remote inclusion in `gitlab-ci.yml`. Example:
```yaml
include:
- remote: https://raw.githubusercontent.com/sourcebroker/deployer-typo3-deploy-ci/2.0.0/ci/provider/gitlab/main.yaml
- remote: https://raw.githubusercontent.com/my_company/deployer-typo3-deploy-ci/1.0.0/ci/provider/gitlab/overrides.yaml
```
## FAQ
1. How to disable frontend or backend part?
Example when you would like to have only backend:
```yaml
deploy:
needs:
- job: test-backend
- job: build-backend
test-frontend:
rules:
- when: never
build-frontend:
rules:
- when: never
```
## Example Configs
### Few separate assets with separate build commands
```yaml
FRONTEND_COMMAND_BUILD: >
cd ${CI_PROJECT_DIR}/assets-1 && npm ci && npm run prod;
cd ${CI_PROJECT_DIR}/assets-2 && npm ci && npm run prod;
FRONTEND_FOLDER_BUILD_1: public/assets-1/frontend/build
FRONTEND_FOLDER_BUILD_2: public/assets-2/frontend/build
```
### Few separate assets with separate build commands and different node versions
```yaml
build-frontend-assets3:
stage: build
image:
name: thecodingmachine/php:${PHP}-v4-cli-node18
retry:
max: 2
script:
- bash -c "cd vendor/my_company/my_ext/Resources/Private/Assets && npm ci && npm run prod"
artifacts:
paths:
- public/assets/frontend/build-assets3
expire_in: 15 min
rules:
- if: $CI_COMMIT_BRANCH && $CI_COMMIT_BRANCH =~ $DEPLOY_TRIGGER_BY_CI_COMMIT_BRANCH
- if: $CI_COMMIT_TAG && $CI_COMMIT_TAG =~ $DEPLOY_TRIGGER_BY_CI_COMMIT_TAG
deploy:
needs:
- job: test-frontend
- job: test-backend
- job: build-frontend
- job: build-backend
- job: build-frontend-assets3