Review main Abandoned

92695[FEATURE] Add DDEV-powered workbench setup for Core development

Benni Mack CR 0 V 0 Normal +224 −0 updated 04/01/26, 15:42

Commit message

When working on the TYPO3 Core monorepo, there is currently no quick
way to spin up a fully functional TYPO3 installation that uses the
local system extensions directly. Developers must either maintain a
separate TYPO3 project with manual Composer configuration or rely on
the acceptance test setup, which is tailored for testing, not
interactive development.

This patch adds a workbench tool that creates a DDEV-powered TYPO3
instance in seconds, with all system extensions symlinked from the
local Core checkout via Composer path repositories. Any code change
in typo3/sysext/ is immediately reflected in the running workbench
— no rebuild or copy step needed.

Components:

  Build/workbench/composer.json
    Static Composer template committed to the repository. Declares
    a path repository pointing at ../../../typo3/sysext/* with
    symlink enabled and explicit version stubs for all 37 system
    extensions. Uses type "project" with minimum-stability "dev".

  Build/Scripts/setupWorkbench.sh
    Shell script that creates a project subfolder under
    Build/workbench/<name>/, copies the Composer template, runs
    "ddev config" for DDEV setup, installs dependencies via
    "ddev composer install", and bootstraps TYPO3 via the
    "typo3 setup" CLI command. Supports multiple simultaneous
    workbenches with different project names.

  .gitignore
    Updated to ignore all runtime artifacts under Build/workbench/
    while keeping the committed composer.json template.

Usage:

  # Create the default workbench
  ./Build/Scripts/setupWorkbench.sh

  # Create a named workbench (multiple can run simultaneously)
  ./Build/Scripts/setupWorkbench.sh -p my-feature

  # Reset and recreate from scratch
  ./Build/Scripts/setupWorkbench.sh -p my-feature -r

  # Custom admin credentials
  ./Build/Scripts/setupWorkbench.sh -u admin -a MyP@ssw0rd

Example — testing a patch from review.typo3.org:

  # 1. Set up a fresh workbench
  ./Build/Scripts/setupWorkbench.sh -p review-12345

  # 2. Fetch and cherry-pick the patch (from the Gerrit download
  #    commands on the patch page)
  git fetch https://review.typo3.org/Packages/TYPO3.CMS \
    refs/changes/45/12345/3 && git cherry-pick FETCH_HEAD

  # 3. Open the workbench — the patch is live immediately
  #    because sysexts are symlinked
  open https://review-12345.ddev.site/typo3

Testing third-party extensions:

  To test a third-party extension alongside the Core checkout,
  create a packages/ directory inside the workbench project folder
  (e.g. Build/workbench/typo3-workbench/packages/) and clone or
  place the extension there. Then add a path repository entry
  to the project's composer.json with "url": "packages/*" and
  "symlink": true in the options, and require the package with
  "ddev composer require vendor/extension-name:@dev". Composer
  will symlink the extension into the vendor directory, so edits
  are reflected immediately — the same mechanism used for the
  system extensions.

Review

  • Code review CR 0
  • Verified V 0
    • core-ci +1 CI

Files 3

Review log 67

  1. Benni Mack uploaded patch set 1 02/05/26, 19:08

  2. core-ci voted on patch set 1 V +1 02/05/26, 19:18 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/95203

  3. Garvin Hicking commented on patch set 1 02/06/26, 09:21

    Very nice. The setupWorkbench helper should IMO directly also setup the `packages/` subdir and add it as a composer.json entry, to reduce the friction of setting up a third party or custom extension. Also an extension could directly be required externally without the need to git clone it - only "custom" test extensions or those not compatible with main would need the packages workaround.
  4. Garvin Hicking commented on patch set 1 02/06/26, 09:26

    PURE JOY to get this on the road

    setupWorkbench.sh:11 Unresolved

    no spiritual guidance? 😊

    setupWorkbench.sh:121 Unresolved

    Maybe here also add guidance on how to require extra packages, and that cherry-picks can be applied (as in the commit message)

    composer.json:2 Unresolved

    can we reserve this package key?

    composer.json:19 Unresolved

    This feels like high maintenance and be added to the release procedure to adapt the file. Could we let this file be dynamically created and grep the environment file for the current main's version? We could probably also iterate all available system extensions dynamically then.
  5. Stefan Bürk commented on patch set 1 02/07/26, 12:15

    Overview/Introduction ===================== I must say that I'm personally not really happy that we start to create a tool around ddev, which itself is a tool around docker compose in a more static than dynamic way coming with a lot of issues and a maintenance burden. We rejected to have a `.ddev/` config in the repository due to many requirements across different host operating systems, for example macos with mutagen due to performance reasons becasue many does not know how to handle that on a global level, multi instances, project names, database syttem to use or php version etc without the danger that "local" changes get commited or making contribution work harder. Are "multiple" composer-mode instances really required within one checkout ? If not, we have the `Build/composer` folder which is used for "distrubtion integration test" and has been prepared to be used as a composer mode installation - single or dual next to use the monorepository root as core development (classic mode). Custom extensions can be used by checking them out in typo3conf/ext/<extension_key> either from a github (or any other git) repository or by simply providing the deflated downloaded zip. Without any conflict to commitable files. Something some developers don't get or are confused with by the "root" composer.json - which we should than document in a better way ? Putting these concerns away after mentioning them at least for the sake of completeness, the current state has two main flaws beside mentioned additional thoughts to make this "really" usefull. Hard Flaws/Issues with the current state ======================================== 1. Conflicts with ddev instance for monorepository root development ------------------------------------------------------------------- > NOTE: `Build/composer/` has the same issue using ddev having a > ddev instance for the root folder. Core contribution guide describes the way to create a instance on the monorepository rootlevel for the basic non-composer development, which conflicts with nested instances based on the simple fact that `ddev` does not support nesting instances. Having such in place failes and suggest to remove the root monorepo instance first, verified with: ``` $ ./Build/Scripts/setupWorkbench.sh Created project directory 'typo3-workbench' with composer.json You are reconfiguring the project at /var/www/work/t3c/core-main/core-main. The existing configuration will be updated and replaced. This project root '/var/www/work/t3c/core-main/core-main' already contains a project named 't3c-v13-mono'. You may want to remove the existing project with "ddev stop --unlist t3c-v13-mono" ``` That means, that either root ddev OR workspaces are usable but not both together. That is something which really needs to be mentioned. 2. Does not work as described (without a root instance) ------------------------------------------------------- > NOTE: `Build/composer/` has the same issue using ddev, but with the same > mitigation strategy done manually absolutly doable. Just from reading the introduced script and my generic knowledge on how ddev works (albeit not a ddev user myself) I was pretty sure that this does not work regarding symlinking the system extensions using composer within the ddev web container (`ddev composer`), verified with: ``` $ ./Build/Scripts/setupWorkbench.sh Created project directory 'typo3-workbench' with composer.json Creating a new DDEV project config in the current directory (/var/www/work/t3c/core-main/core-main/Build/workbench/typo3-workbench) Once completed, your configuration will be written to /var/www/work/t3c/core-main/core-main/Build/workbench/typo3-workbench/.ddev/config.yaml Created docroot at /var/www/work/t3c/core-main/core-main/Build/workbench/typo3-workbench/public Configuring a 'php' project named 'typo3-workbench' with docroot 'public' at '/var/www/work/t3c/core-main/core-main/Build/workbench/typo3-workbench/public'. For full details use 'ddev describe'. Configuration complete. You may now run 'ddev start'. Starting DDEV project 'typo3-workbench'... Starting typo3-workbench... The index.php or index.html does not yet exist at this path: /var/www/work/t3c/core-main/core-main/Build/workbench/typo3-workbench/public/index.* You may get 403 errors 'permission denied' from the browser until it does. Ignore if a later action (like `ddev composer create-project`) will create it. Building project images........ Project images built in 5s. Network ddev-typo3-workbench_default Created Container ddev-typo3-workbench-db Started Container ddev-typo3-workbench-web Started Waiting for containers to become ready: [web db]... ready in 6.0s ddev-router already running, pushing new config... Waiting for ddev-router to become ready... ready in 0.5s Successfully started typo3-workbench Your project can be reached at https://typo3-workbench.ddev.site See 'ddev describe' for alternate URLs. Running composer install... No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information. Loading composer repositories with package information In PathRepository.php line 163: The `url` supplied for the path (../../../typo3/sysext/*) repository does not exist install [--prefer-source] [--prefer-dist] [--prefer-install PREFER-INSTALL] [--dry-run] [--download-only] [--dev] [--no-suggest] [--no-dev] [--no-security-blocking] [--no-autoloader] [--no-progress] [--no-install] [--audit] [--audit-format AUDIT-FORMAT] [-v|vv|vvv|--verbose] [-o|--optimize-autoloader] [-a|--classmap-authoritative] [--apcu-autoloader] [--apcu-autoloader-prefix APCU-AUTOLOADER-PREFIX] [--ignore-platform-req IGNORE-PLATFORM-REQ] [--ignore-platform-reqs] [--] [<packages>...] Composer [install --no-progress --no-interaction] failed, composer command failed: exit status 1. stderr= ``` To get this working, each `workspace instance` needs to add a extending docker-compose file to add a additional mount, for example `../../../typo3 => /var/www/html/typo3-system-extension` for example with a file: ``` services: web: volumes: - "${MONOREPO_ROOT_PATH}/typo3:/var/www/typo3" ``` and adjusting the relative paths in the provided composer.json relativ within the ddev instance, for example instead of ``` "repositories": [ { "type": "path", "url": "../../../typo3/sysext/*", ``` it should be ``` "repositories": [ { "type": "path", "url": "../typo3/sysext/*", ``` Additional thoughts/missing parts: ================================== * Database backend (MariaDB, MYLSQ, Postgres, SQLite) should be also directly configurable with the "wrapping" script, to make more sense for multiple workspaces. Same for version selection of the used database except sqlite. * For MariaDB/MySQL we should use `pdo_mysql` over `mysqli`, which is already the recommended driver and removes some performance penalties over `mysqli`. `ddev` creates TYPO3 projects with `mysqli` driver, but as we omit that and configure it using the TYPO3 setup command we use the better default here (or make it configurable). * PHP version should also be selectable - that is important to avoid possible DI issues when first composer install and setup with PHP8.2 and later switched to PHP8.5 for example. (We had these issues in the past). * `ddev` reduced the available locales within the setup, a point many developers still not aware. Should that be documentend at least as "after" ddev reconfiguration per workspace instance ? * What are the plans documenting this, mainly in combination with the "current" ddev based quick setup guide ? Is this really a benefit for the broader contributor instance or do we document/provide this as "additional/experienced" workflows explicitly not for contribution startes or devs not really familar with ddev ? I would really want to avoid that we start to reflect a lot of use cases and ddev configuration in the core contribution guide. * If multiple instances are not really required (**must have**) we could simply document that as a additional setup way with ddev in the core contribution guie using `Build/composer/` folder directls (with a copy of composer.json.dist) and the above mentioned mount of and adoption to the dist file. Or having a second one with `composer.json.ddev` in the folder. * Not sure about macos users and possible syncing issues due to having a VM between the host and docker regarding updates in the container when checking out a gerrit change - or if mutagen needs to be enabled for this. Something which should not be enabled directly by the script due to performace decrease for ddev users with linux hosts not using `Docker Desktop for Linux`, and something which needs to be enabled per workspace instance manually or globally already. Not sure if mutagen sync excludes are required (based on lacking usage knowledge on macsystems). Conclusion/Personal takeaway ============================ Personally I would not start adding this in that form and even not with the "more usable" extended version with additional options mentioned above - due to maintenance reasons. Literally, getting it with "running" basically for monorepo non-composer mode (dev mode) is a simple 3 step list - except leaving enabling all extensions out. I'd suggest that we consider following to simplify this and reduce maintenance burden: * Provide only the `Build/workspaces/` folder with three files: * A `docker-compose.mounts.yaml` to mount the system extensions into the ddev web conntainer as copy template. * A `composer.json` file, the current one with adjusteted relative path(s) within the ddev instance. * A `README.md` file to describe how to create a instance below the path with the simple commands: 0. Introduction/Use-case for this folder with a warning that this conflicts when used nested within another ddev instance, running or not. 1. mkdir -p ./instance-name 2. ddev config ... command as customizable example, for example for the PHP version, db vendor and version and similar. 3. ddev typo3 setup command as example how to setup the instance also as customizable variant. 4. (OPTIONAL) ddev typo3 styleguide:generate command as example to setup tca and/or frontend tree in the instance as startup, or theme_camino example frontend tree in case a installable preset exists.
  6. Benni Mack commented on patch set 1 04/01/26, 15:42

    Reply

    nevermind, I wanted to have an easier setup for non-devs and newbies, and we might need different solutions to see which one will be adopted, because we have opinions (right so) and we can discuss endlessly on them. All I can say that in the past 6 weeks I had contact with roughly 15 people who wanted to set up a new TYPO3 installation (dev-main branch) without Git-Hooks, my.typo3.org accounts, SSH keys, contribution - like the entry drug to get going. Today, I published the results, which I will recommend to people for the time being: https://github.com/bmack/tryout - don't worry, I endorse DDEV for various reasons, and we can agree to disagree on that choice of tooling, no worries.
  7. Benni Mack abandoned the change 04/01/26, 15:42

    won't pursue this any further