TL;DR: Zero to Drupal 10 on Aegir 3 in About Fifteen Minutes
For those in a hurry:
- Start with a fresh Ubuntu 22 VM.
- Clone this git repository and follow the instructions in the README file.
- Use the Aegir 3 site migration process to move your Drupal sites to your new setup.
Happy migrating!
For more detailed information, keep reading.
Background: Tectonic Drift
At Consensus Enterprises, we’re dedicated to helping organizations transition smoothly from Drupal 7 to Drupal 10 on Aegir 3. While we’re developing the future of Drupal self-hosting with Aegir5, we continue to see a range of users in the Aegir community, from small organizations through academic institutions to large government departments, who need to keep their existing Aegir 3 installations working. In particular, as Drupal development moves forward, the requirements of Aegir 3 itself and modern versions of Drupal core have begun to drift apart.
Of course, the medium-to-long term solution we recommend will be to migrate to Aegir5, but until it becomes available, the community needs a way forward.
Our Approach: Ensuring Continuity
As one of Consensus’s DevOps specialists, I started documenting how Aegir 3 could continue to host modern Drupal versions when it became clear that the old Aegir 3 Debian repositories were no longer sufficient. This led me to create an example repository that anyone can use to deploy and configure an Aegir 3 instance for hosting modern Drupal versions on Ubuntu LTS in about 15 minutes, utilizing our Consensus Ansible roles.
When long-time Aegir and Drush contributor Steven Jones started working on a solution for hosting Drupal 10 on Aegir 3, I was particularly keen to see what he would come up with. As Steven writes in his 2-part series on the subject, there are several tricky interactions between Drupal core, Drush, and Aegir’s Provision component that require tending to, in order to make the whole stack work together. He also points out the crucial caveat that this solution should be regarded as temporary, since it is brittle, and has to dance around conflicts between Drush 8 and Symfony 6. His articles are great, and I’m not going to rehash his eloquent explanation here. However, he does not quite fill in all the details one needs in order to achieve a running Aegir instance that supports Drupal 10. My goal was, thus, to extend my earlier work and provide a working example that Aegir users can then customize to meet their local needs.
Drupal, Drush, and Provision: Oh, My!
Building on Steven’s recipe, we need several ingredients to build an Aegir 3 that can host Drupal 10:
- Use BOA Drush 8
- Add Drupal 10 Support to Provision
- Address Drupal Core Asset Handling Changes
- Resolve Conflicts Between Symfony 6 and Drupal 10
We accomplish the first of these via our Ansible playbook and our Ansible roles; the second and third via patches to Provision; and the fourth via a custom Drupal 10 Aegir 3 Platform. All the code for these solutions is public and freely available under open-source license terms, and we are actively working to contribute the Provision patches upstream.
1. Use BOA Drush 8
Drush 9+ fundamentally refuses to be anything other than site-local; and, for better or for worse, Aegir 3 fundamentally relies on global Drush functionality, so we must stick with Drush 8. Aegir5 will solve this problem by adopting more flexible DevOps tools like Ansible; but, for now, we follow Steven’s suggestion and use BOA’s version of Drush 8 in our Ansible playbook.
2. Add Drupal 10 Support to Provision
Provision doesn’t include support for Drupal 10 (yet)–but we can add it from BOA Provision, as Steven suggests. This causes a few minor problems, because the files from BOA that support Drupal 10 assume they are living in the BOA ecosystem, which breaks vanilla Provision. With some careful testing, we’ve found and removed those assumptions, and thus fixed the problems.
3. Address Drupal Core Asset Handling Changes
Meanwhile, Drupal core has changed the way it handles CSS and JavaScript assets, which requires fixes in Provision’s Nginx config generation code. Thanks to Consensus colleague Scott Zhu Reeves for help tracking these down so we can ensure Provision generates the correct Nginx config!
4. Resolve Conflicts Between Symfony 6 and Drupal 10
As Steven says, “Drupal 10 uses Symfony 6, which has type hints on various interfaces and methods, and Drush 8 uses Symfony 2, which does not. So, if you load one before the other, then as soon as PHP tries to load the second, it’ll die because either the types are there, or they aren’t.” He walks through the steps required to resolve this dilemma, which we won’t repeat here; long story short, we are following his suggestions. We do it all with Composer, as you can see via these links to our open-source Drupal 10.2 Aegir Platform:
Conclusion
By following the steps at the top of this post, you can bridge the gap from Aegir 3 to Aegir5, ensuring continuity and modernizing your Drupal hosting environment. If you need assistance or have questions, our team at Consensus Enterprises is here to help. Let’s navigate the migration journey together and keep your projects running smoothly.
For detailed instructions and support, feel free to contact us and follow us on LinkedIn.
The article Drupal 10 on Aegir 3: A Step-by-Step Guide first appeared on the Consensus Enterprises blog.
We've disabled blog comments to prevent spam, but if you have questions or comments about this post, get in touch!