TYPO3 Distribution - GitLab Project Template

Get going quickly with TYPO3 CMS and GitLab.

Quickstart

Use the following ddev command to set up the template:

ddev typo3-init

NOTE

For the quickstart, you have ddev to be installed on your host system. For further details, head over to the official documentation.

All commands - manual setup

Configure ddev, install packages and start the ddev instance:

ddev start
ddev composer install
ddev typo3 setup

Prepare and build frontend:

ddev npm install
ddev npm run build:production

Initialize data (page tree and link assets):

ddev typo3 extension:setup
ddev composer dumpautoload

Display all your project related information:

ddev describe

Configuration

Managing Environment Variables with DDEV

This TYPO3 GitLab template supports a clean and secure way of managing environment variables using DDEV's environment handling features. There are two .env files used in this setup with clearly defined purposes:

.ddev/.env — Local Development Defaults

This file contains environment variables specifically for your local development environment managed by DDEV.

• It includes default credentials and configuration for the TYPO3 application when running locally (e.g., database connection, admin login, mailer setup).
• These values are automatically loaded by DDEV when spinning up the project locally.
• You can adjust values here to match your local setup, but do not use this file for sensitive production credentials.

✅ Safe to commit 🔒 Do not store API keys or secrets here 🔁 Automatically loaded by DDEV during ddev start

.env — Project Root (Credentials & Secrets)

The root .env file is used for storing sensitive data and environment-specific credentials such as:

• API keys
• Production or staging database credentials
• Encryption keys
• Mail service configurations

This file is excluded from version control via .gitignore, so it's safe to store secrets here without risk of committing them to Git.

Use the included .env.example file as a reference to know which variables you may need to define. On your production or CI/CD server, make sure to create your own .env file based on this template.

🔐 Use this file for credentials 🚫 Never commit this file 📁 Refer to .env.example for available variables

Environment variables loading order

The following table shows the loading order of the environment variables. For example, 2. will overwrite 1. and so on.

	File	Note
1.	.env	Changes need TYPO3 Cache flush
2.	.ddev/.env	Changes require ddev restart
3.	.ddev/.env.web	Changes require ddev restart
4.	.ddev/config.yaml-> web_environment	Changes require ddev restart

Mapping Environment Variables in config/system/additional.php

To dynamically apply environment variables to TYPO3 configuration ($GLOBALS['TYPO3_CONF_VARS']), this template includes a mapping block in config/system/additional.php. This helps keep sensitive configuration out of version-controlled files and centralizes environment-specific logic.

This mapping looks for specific environment variables and assigns their values to TYPO3 settings. Only variables that are set will be applied. This keeps configuration clean and avoids overriding defaults unintentionally.

Add new keys to the array based on your needs (e.g., for extensions or additional system settings) and set the corresponding environment variable in either .env or .ddev/.env.

Example:

$configMappings = [
    ...
    'EXTENSIONS' => [
        'my-extension' => [
            'myCustomSetting' => 'MY_CUSTOM_ENV_VAR',
        ],
    ],
    ...
];

Mail GUI

Start the built-in Mailpit to access emails sent by TYPO3:

ddev launch -m

Database GUI

To access the database via a web GUI, you can install e.g. phpmyadmin ddev get ddev/ddev-phpmyadmin or adminer ddev get ddev/ddev-adminer.

Use the DDEV Vite Add-on

NOTE

The addon is already available after ddev typo3-init has completed.

Install:

ddev get s2b/ddev-vite-sidecar
ddev restart

Run the Vite dev server:

ddev vite

Files and folders

The folder packages contains all your local extension/packages. Require these packages simply by using composer req vendor/package:@dev

Each extension defines its own entry points in EXT:my-extension/Configuration/ViteEntrypoints.json they are automatically included by Vite.js with vite-plugin-typo3 and the output is stored in public/_assets/vite/.

Npm Scripts / Vite.js

The frontend toolchain uses NPM and Vite.js with the vite-plugin-typo3 to compile the frontend assets.

Watch for changes in js/scss files:

ddev npm run watch

Build JS, CSS for development use (not compressed/optimized):

ddev npm run build:development

Build JS, CSS for production use:

ddev npm run build:production

QA / Analysis

Run PHPStan:

ddev exec ./vendor/bin/phpstan analyse -c .phpstan.neon --no-progress

PHP CS Fixer:

ddev exec ./vendor/bin/php-cs-fixer fix --dry-run --diff

Deployer

deploy.yaml contains an example configuration for deployer (PHP deployment tool). It's recommended to run deployer in GitLab CI.

Run deployer locally (only for testing):

./vendor/bin/dep deploy -vvv staging

Scheduler script

The TYPO3 scheduler is executed via supervisor every five minutes. In case xdebug is enabled, the scheduler script is not executed. The daemon is configured via .ddev/config.yaml -> web_extra_daemons and will start on "boot".

Run the service:

ddev typo3-scheduler <start|stop|status>

Run the scheduler manually:

ddev typo3-scheduler # -f or --force to run it while xdebug is enabled

External documentation

• TYPO3 - https://docs.typo3.org/
• DDEV - https://ddev.readthedocs.io/en/stable/
  • Vite Add-on - https://github.com/s2b/ddev-vite-sidecar
• Vite.js - https://vitejs.dev/
  • vite-plugin-typo3 https://github.com/s2b/vite-plugin-typo3
• Deployer - https://deployer.org/docs/7.x/basics

License

GPL-2.0 or later