{"id":14968556,"url":"https://github.com/peter-neumann-dev/ddev-cms-upgrader","last_synced_at":"2025-10-26T02:31:09.750Z","repository":{"id":203983149,"uuid":"694346374","full_name":"peter-neumann-dev/ddev-cms-upgrader","owner":"peter-neumann-dev","description":"A sample script to automatically upgrade major CMS versions with DDEV and Bash (e.g. TYPO3, Drupal, WordPress, Craft CMS)","archived":false,"fork":false,"pushed_at":"2024-11-21T07:48:07.000Z","size":37,"stargazers_count":27,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-01-31T13:43:29.109Z","etag":null,"topics":["bash","craftcms","ddev","drupal","open-source","typo3","upgrade","wordpress"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peter-neumann-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-20T20:15:57.000Z","updated_at":"2024-12-03T05:24:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"98c748e6-83ee-428a-9e63-5106a7f34f84","html_url":"https://github.com/peter-neumann-dev/ddev-cms-upgrader","commit_stats":{"total_commits":17,"total_committers":3,"mean_commits":5.666666666666667,"dds":0.4117647058823529,"last_synced_commit":"4ce92579da52b350f8067db9c18651c5a0580543"},"previous_names":["peter-neumann-dev/ddev-cms-upgrader"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-neumann-dev%2Fddev-cms-upgrader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-neumann-dev%2Fddev-cms-upgrader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-neumann-dev%2Fddev-cms-upgrader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-neumann-dev%2Fddev-cms-upgrader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peter-neumann-dev","download_url":"https://codeload.github.com/peter-neumann-dev/ddev-cms-upgrader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238247980,"owners_count":19440879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","craftcms","ddev","drupal","open-source","typo3","upgrade","wordpress"],"created_at":"2024-09-24T13:40:07.081Z","updated_at":"2025-10-26T02:31:09.403Z","avatar_url":"https://github.com/peter-neumann-dev.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# DDEV CMS Upgrader\n\n**A sample script to automatically upgrade major CMS versions with DDEV and Bash (e.g. TYPO3,\nDrupal, WordPress, Craft CMS)**\n\n[![TYPO3 Usergroup Magdeburg](https://img.shields.io/badge/TYPO3-Usergroup_Magdeburg-ff8700?style=flat-square\u0026logo=typo3)](https://www.meetup.com/de-DE/typo3-usergroup-magdeburg/)\n[![DDEV](https://img.shields.io/badge/DDEV-Foundation-02a8e2?style=flat-square\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABMAAAAPCAYAAAAGRPQsAAAACXBIWXMAAAsSAAALEgHS3X78AAABIElEQVQ4jY2T0XGDMBBE383wbzoIHYRUELuDdBBTQXAH7sAlQCdOKsCuIKQC6GDzkVOsgCDeGY3uxGnvMZKMFUn69LBfKLmY2SEk2ZoZcAFG4CvxbQPUknIzqwAsQVMAnRv91+gKNEBrZlWKbIzm64LRBqiBFqiARtKNTNIReFwxmDYcA5XvOcVkz0AJ5J4XPnr+HkDudS1wAE7ADiCT1HiXDx+hcwuc3TCsPzhFD+yDya+0rEZSLqmbrJ8lHT3exnMGPEWdRo9fPcd/Jajw+Y3bQc0laVihnGpwmi6KFZuVfseQtA/xQuN8YtRJGlKF2xnHfXRl6gXk/FzI8JS2wHsCMNyzAtiZ2fqLkVTfQVeG+hnZxKwEXiLKqXoz60PyDWDeV6d2QUBxAAAAAElFTkSuQmCC)](https://ddev.com/)\n[![TYPO3 News Article](https://img.shields.io/badge/TYPO3-News_Article-ff8700?style=flat-square\u0026logo=typo3)](https://typo3.org/article/automatic-typo3-updates-across-several-major-versions-with-ddev)\n\n\u003c/div\u003e\n\n## ✨ The Idea\n\nAfter a major version upgrade of a CMS, there are often plenty of manual steps to take, like\nrunning Upgrade-Wizards, SQL Migrations, other Scripts, etc.\n\nThis script should help to automate these steps and make the upgrade process more efficient and\nreproducible by using DDEV, branches of each major version, and Bash scripts. For each major version,\na DDEV environment will be started, and the upgrade steps will be executed via DDEV's post-start\nhooks and then stopped. Afterward, the next major version will be started, and so on.\n\nRead more about in the [TYPO3 News Article](https://typo3.org/article/automatic-typo3-updates-across-several-major-versions-with-ddev).\n\n**This script is a sample that should be adjusted to your project's needs.**\n\n## 🔧 Preparations\n\n- Create branches for each major version in a structure `CMS-MAJOR_VERSION`\n    - (e.g. `typo3-10.4`, `typo3-11.5`, `typo3-12.4`)\n- Add a MySQL dump of the current/the oldest production version to a git-ignored folder\n    - This will be used to import the database in the first version cycle during the upgrade process\n\n## 🚀 Usage\n\n1. Clone or download this repository into your project\n2. Copy the `.env.sample` file to `.env` and adjust the variables\n3. Adjust paths if needed in [`auto-upgrade.sh`](auto-upgrade.sh)\n4. Run the script\n\n## 📝 Example Upgrade with TYPO3\n\nPreparation and requirements to update an existing TYPO3 website from version 9.5 to version 12.\n\n* Existing local development system with DDEV and the current TYPO3 version 9.5\n* Latest database dump from the live system, ready for import into the local system\n* local system is not running\n\nBefore starting with creating new branches or adjusting data in the .env file, you have to decide\nwhether you can go directly to the last TYPO3 version or not. That depends on your installation and\nused extensions. Usually, you need some upgrade wizards to update the database step-by-step for the\nsingle TYPO3 version.\n\nLet's assume you require an upgrade wizard for an extension that exists only in a version of TYPO3 10.\nAnd another extension with an upgrade wizard in TYPO3 11. Then you require both of them, 10 and 11,\nand finally a branch for TYPO3 12.\n\nIf you don't need to execute upgrade wizards of extensions, or use the\n[`Core-Upgrader`](https://github.com/WapplerSystems/core_upgrader) to execute all upgrade wizards from previous TYPO3 versions, then you just\nneed some code in the DDEV commands. Of course, it is possible to use our upgrade script with\njust one target branch.\n\nNow create a branch for the first needed TYPO3 version. We assume that we require upgrade wizards\nfrom extensions in TYPO3 10, 11 and 12.\n\n---\n\u003e Always add only the respective version of the current branch in the .env file\n\u003e That means: if you start in branch 10.4, versions in .env file are only \"10.4\"\n\u003e If you create (or switch) to the next branch 11.5, versions in .env file should \"10.4 11.5\"\n\u003e In the next branch 12.4, version should be \"10.4 11.5 12.4\" and so on …\n\u003e That gives you the possibility of running the upgrade only up to the current branch.\n---\n\nWe assume you are on the main branch of your website. Start with creating a new branch `typo3-10.4`.\nAdd version 10.4 to the .env file. This is the first branch where we need our DDEV Post-Start Hooks.\nAdd your DDEV Post-Start Hooks.\n\n**We have some examples of DDEV's post-start hook commands here:**\n\n```yaml\nhooks:\n  post-start:\n    - exec-host: ddev composerinstall\n    - exec-host: ddev warmup\n    - exec-host: ddev upgrade-steps-10.4\n```\n\nMove them to your `.ddev` folder and adjust the code to your needs. You can add more files and hooks\nif you need them. Maybe there are some steps needed to delete folders and files in your installation.\nThere is a sample file  [`aftercheckout`](.ddev/commands/web/aftercheckout) for doing stuff locally after checkout the branch.\n\n---\n\u003e We recommend that you perform as many database actions as possible in the upgrade steps.\n\u003e Sometimes it's easy to save the data in the backend after doing changes and make a simple sql\n\u003e export for generating the update query. Then use this in individually SQL files.\n---\n\nThere is an example of how to execute your SQL on the upgrade step in the file\n[`UpdateQueryForMe.sql`](.ddev/commands/web/UpdateQueryForMe.sql).\n\n### Import the database on the first branch\n\nThere is a special feature in the first branch. You have to import the database. For those step,\nwe have a ddev post-start hook for that. Our sample file expects a .sql (or zipped as .sql.gz) file\nin the folder\n\n    fixtures/database\n\nBe sure there is a file and the database is empty.\n\nIn the following branches, you can remove that hook from the config.yaml\n\nThat's it!\n\n---\n\nCommit your changes and go further to create the next branch. Add the next version to the .env file,\nadd new files and commands for ddev's post-start hooks. Commit your changes.\n\nWe are using separate files for each TYPO3 version, adding a new one to each branch, and changing\nthe post-start hook command. It's also possible to use one file without a version dependency. Then\nyou just have to change the code inside the file for each branch (version).\n\n---\n\nIf you have finished creating all branches and the post-start hooks for DDEV it is time to test\nyour upgrade.\n\n### Start your automatically upgrade\n\nYou have to prepare something to start the upgrade process. We assume you are in the latest branch.\nIn our example, this is the branch `typo3-12.4`.\n\n* Stop the running DDEV containers\n```\nddev stop\n```\n* delete the DDEV containers. Upgrades should start everytime with a clean database. It's possible\nto create a backup before doing this step.\n```\nddev delete -O\n```\n* now start the upgrade script `./auto-upgrade.sh`\n\n---\n\u003e I always want to know how long such an upgrade will run, therefore I use the `time` command.\n\u003e Starting upgrade with `time ./auto-upgrade.sh`\n---\n\nI hope that works for you. And now … happy upgrading 😄\n\n## 🚀 Possible improvements\n\nThis tool is just a first approach, an idea, a suggestion. It is certainly appropriate to\nimprove it.\n\n### One possible variant with stop using DDEV's post-start hooks.\n\nA check for the first run was added in the `auto-upgrade.sh`. Now it's possible to do some special\nthings on first run:\n\n* Use ddev providers to get a database dump from production and import them automatically\n  * Not implemented here. That depends on your production system. You have to do it by yourself.\nSee DDEV Docs: https://ddev.readthedocs.io/en/stable/users/providers/\n* Do some preparation stuff (composer install, activate extensions, updateschema …)\n  * See example for `.ddev/commands/web/warmup`\n* Do upgrade steps with the command in DDEV's Web-Container (`.ddev/commands/web/upgrade`).\n  * File/DDEV-Command (`upgrade-steps-10.4` -\u003e `upgrade`) renamed. It's enough to change code in the\nfile for each branch. Filename is secondary.\n\n\n## 💎 Credits\n\nThis script was created within the [TYPO3 Usergroup Magdeburg](https://www.meetup.com/de-DE/typo3-usergroup-magdeburg/)\nduring a live coding session testing to automate the upgrade process of TYPO3 with DDEV and Bash.\n\nThanks to [Karsten Nowak](https://github.com/kanow) for the idea to test this approach!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-neumann-dev%2Fddev-cms-upgrader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeter-neumann-dev%2Fddev-cms-upgrader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-neumann-dev%2Fddev-cms-upgrader/lists"}