Updating Neos – Why, When and How - 2024 edition
0 likes•9 views
The document discusses the importance of regularly updating Neos projects to benefit from new features, bug fixes, and better security, encouraging updates as soon as new versions are released. It outlines a structured approach for updating, including testing in a staging environment, ensuring backup strategies, and understanding the types of releases (patch, minor, major). Additionally, it provides guidance for upgrading to Neos 9, including preparing the content repository and migrating data, while emphasizing community support for troubleshooting issues during the update process.
![$ ./flow cr:migratelegacydata
Do you want to migrate resources from the current installation "/…/Data/Persistent/Resources" (y/n)?
Do you want to migrate nodes from the current database "dbname@dbhost" (y/n)?
Successfully connected to database "dbname"
Which site to migrate?
[acmecom] acme.com (Acme.AcmeCom)
> acmecom
Site "acmecom" already exists, update it? [n] y
We will clear the events from "cr_default_events". ARE YOU SURE [n]? y
Truncated events
Exporting assets...
Exported 211 assets. Errors: 54
Exporting node data...
Exported 1840 events
Importing assets...
Imported 196 Assets and 60 Image Variants. Errors: 0
Importing events...
Imported 1840 events into stream "ContentStream:6ae1f48e-b3ed-4438-b685-d703c446cc29"
Replaying projections
Done](https://image.slidesharecdn.com/updatingneoswhywhenandhow-2024-240603082906-ca120272/85/Updating-Neos-Why-When-and-How-2024-edition-45-320.jpg)
Updating Neos – Why, When and How - 2024 edition
- 2. Updating Neos – Why, When and How Karsten Dambekalns
- 3. Karsten Dambekalns • Developer and consultant at Flownative GmbH • Working on & with Neos since 2005… for 19 years… • Updated quite a number of Flow and Neos projects over the years • Most recently a Flow 3.0.2 project essentially unchanged since 2013 🤪
- 4. Why, When and How Why? Because you get new features and bug fi xes. When? Whenever a new version is released. How? Read & follow instructions, test & deploy. Done!
- 5. Thanks for listening • Any questions? • Just kidding…
- 6. Why should you update? • You bene fi t from fewer bugs, new features and better performance most of the time
- 8. Bugs to get rid of…
- 9. Why should you update? • You bene fi t from fewer bugs, new features and better performance most of the time • Outdated versions will no longer receive support
- 10. SECURITY
- 13. Why should you update? • You bene fi t from fewer bugs, new features and better performance most of the time • Outdated versions will no longer receive support • Security fi xes will no longer be done on old releases
- 15. Other tools in your stack
- 18. When should you update? • As often and as fast as possible! • Updating often keeps the routine drilled… • Staying up to date keeps the steps to take smaller! • Smaller steps mean lower risk when updating!
- 19. But… we updated once, and it broke our site! As mentioned, in case something goes wrong: • do test your updates on a staging instance • have a current backup • have a rollback-strategy If things still break on production deployment, the cause is almost never the new version…
- 20. But… we don‘t need new stu ff and things work fi ne That is the „our small site works well“ reasoning, which is fi ne until: • Your hosting provider emails you to inform you about the EOL of PHP 5.6, so your Neos 1.0 site will stop working. • Some security issue requires you to upgrade, but in a hurry! • Related technology must be updated for some reason. • New features must be added (GDPR adjustments, anyone?) – but no one wants to work with such old code…
- 21. But… we run a mission critical site! Some sites cannot a ff ord a downtime caused by a bug introduced by an update. But of course you don‘t deploy the update to your mission-critical site untested, do you? And you do have a backup and a rollback strategy in place, don‘t you? If you can‘t have a staging instance for testing, your mission can’t be that critical…
- 22. But… we only use LTS versions! Sometimes people claim they must only use LTS versions, because they are more reliable or receive better support. Reliability Granted, new features may introduce bugs. But all supported branches receive all fi xes – due to how we manage the source code. Support lifetime Any versions „after“ an LTS receive support for as long as the LTS version – due to how we manage the source code.
- 24. How should you update? The generic recipe is: • read release notes • adjust composer.json, if needed • do a dry-run of composer update, check results • do composer update, commit result • run core migrations, check result, adjust as needed • run database migrations • test, test again, commit, deploy to staging, test, deploy to production
- 26. Patch-level releases • Must never be breaking, only contain bug fi xes • Might add new issues due to a buggy bug fi x, happens rarely, though • Usually about an hour of work x.y.z+1
- 27. Minor releases • Add features and contain all the features and fi xes of the previous minor release(s) • Must never be breaking, but new features may still have bugs (more probably in a x.y.0 release) • Could take longer. If new features need to be enabled or con fi gured, even a few hours, depending on the complexity of your site • Might need a database migration and/or new con fi guration • A bit more testing than for a patch-level release is advisable x.y+1.z
- 28. Major releases • Add features, contain features and fi xes of the previous minor release(s) and may have breaking changes • Probably need adjustments to your site’s code and new (major) versions of used extensions • Probably need a database migration and con fi guration changes • Could require updated infrastructure (PHP or Elasticsearch version, …) • Needs the most testing of all types of releases x+1.y.z
- 29. Approaching an update Updating to a new version can always be done “in one go”, you do not need to upgrade to each version in between But you always need to read the release notes of the full range of versions you cover in your update Check your dependencies, if needed adjust to allow newer packages Collect a list of (breaking) changes that need attention
- 30. Packages needing a dependency adjustment Sometimes you must raise the allowed version of dependencies, e.g. • fl ownative/google-cloudstorage 5.2 vs 5.3 • psmb/splitadd 0.3 vs 0.4 Usually not a problem, if you use constraints like ^5.2 – then 5.3 is allowed, too. And patch-level releases should aways be allowed… It’s di ff erent for major versions (no surprise) and for 0.x versions! Hint: use https://semver.madewithlove.com/ to check constraints!
- 32. Doing the update • As soon as your dry-run update works and gives reasonable results • Update without the dry-run fl ag and commit the changes to the manifest(s) and lock fi le • Run core migrations on your own packages, check results, clean up as needed
- 33. Clean up after core:migrate Here’s what I do after running core migrations: • check the commits that were created • soft-reset the repository to the latest upstream commit • adjust changes as needed • commit the changes in one commit That way it’s easier for me to keep things clean and clear
- 34. Further adjustments Core migrations usually adjust the „easy“ stu ff , but some things cannot be automagically adjusted with reasonable e ff ort So some changes need to be done manually, examples for this are: • Fusion removal of the default prototype generator • Logging PSR-3 logger adjustments • Fluid ViewHelpers no more render() arguments • HTTP components use PSR middlewares instead
- 35. Neos 9
- 36. Upgrading to Neos 9 … is not just another major version upgrade.
- 37. Upgrading to Neos 9 Upgrading Composer packages • Adjust the version of any Neos packages to require ^9.0 and run composer update. • This will probably fail due to other packages in your project that need to be updated to work with Neos 9, so check those for newer versions. You will also need to require (at least) one new package: • neos/contentrepositoryregistry-doctrinedbalclient is the DBAL adapter for the CR After the upgrade try to run ./flow – with a bitlot of luck, everything compiles already. 🍀
- 38. Upgrading PHP code • As usual, a fi rst step is to run ./flow core:migrate on all packages you maintain or want to create a PR for. • Next install the neos/rector package to be able to use the migrations we ship for upgrading to v9. • Now run Rector in dry-run mode and if things look good, run it for real. If the automated ways of fi xing your PHP code did not work (well enough), it is now time for manual adjustments… • To begin with, just try to make the code compile again!
- 39. Migrating con fi guration • If you have Routes con fi gured, make them use the new FrontendNodeRoutePartHandlerInterface if needed. • Adjust your Content Dimensions setup • … probably more to come!
- 40. Migrate your content Moving your content from the old Content Repository into the new one is the major step. In a nutshell: 1. Prepare your data 2. Prepare the new Content Repository 3. Install migration tooling 4. Do the data migration
- 41. Prepare your data Your project ideally is at version 8.3 already (you upgrade early & often, no?) To be on the safe side, run the migrations as usual: ./flow doctrine:migrate To make the migration smoother, fi x as many errors in the CR as possible. So think about cleaning things up using node:repair to fi x unde fi ned properties, remove nodes with unknown nodetypes and so forth. This will make the output less verbose, later… As usual, be careful with that tool, it can destroy data…
- 42. Prepare your data Make your site's root node a dedicated "home page nodetype.” Otherwise you will run into an error like this: The site node “bf…f8" (type: "Neos.NodeTypes:Page") must be of type "Neos.Neos:Site" • If you already have a dedicated nodetype for the site root, you can simply add Neos.Neos:Site as a supertype to it. • Otherwise, create a new nodetype like below and change the type of the current site root node to it: 'Acme.AcmeCom:Document.Homepage': superTypes: 'Neos.Neos:Site': true 'Neos.NodeTypes:Page': true
- 43. Prepare the new CR Before you can do anything, you need to set up the needed tables for the new Content Repository. Fear not – this is as easy as: ./flow cr:setup Now a number of new tables named cr_default_* will appear in your database – it is no problem to use the same database as before.
- 44. Install migration tooling To migrate the data, you need another "helper package", so install neos/ contentrepository-legacynodemigration now, which allows to migrate CR data: composer require --dev neos/contentrepository-legacynodemigration
- 45. $ ./flow cr:migratelegacydata Do you want to migrate resources from the current installation "/…/Data/Persistent/Resources" (y/n)? Do you want to migrate nodes from the current database "dbname@dbhost" (y/n)? Successfully connected to database "dbname" Which site to migrate? [acmecom] acme.com (Acme.AcmeCom) > acmecom Site "acmecom" already exists, update it? [n] y We will clear the events from "cr_default_events". ARE YOU SURE [n]? y Truncated events Exporting assets... Exported 211 assets. Errors: 54 Exporting node data... Exported 1840 events Importing assets... Imported 196 Assets and 60 Image Variants. Errors: 0 Importing events... Imported 1840 events into stream "ContentStream:6ae1f48e-b3ed-4438-b685-d703c446cc29" Replaying projections Done
- 46. Migrate your Fusion code • The automated migration using Rector will have adjusted your Fusion code already. • Check those changes and look for instructions added – there are adjustments you must do manually yourself. • Some more manual changes are needed when using deprecated ways of doing things, e.g. for adding @cache con fi guration. • When (still) using Fluid, you need a few more changes – those doing AFX already are better o ff – as Neos.Fusion:Template is no longer a default.
- 47. Upgrading more PHP code • Most projects will probably not be a ff ected much by the changes to the Content Repository PHP API • If you do interact with the CR, it is probably to • import things from some source, • export things to some source, • do things in some added Neos backend module. As we come closer to the release of Neos 9, examples and recipes will be published for common cases!
- 48. If you get stuck Finally, if you get stuck with an update even though you were well prepared • Search for your issue, chances are someone else found a solution already • Ask the community for help on Slack or discuss.neos.io • Ask your agency for help • If you are an agency, ask me or my company for help 😎
- 49. Test and deploy Now test your site. You may • Run unit and functional tests if you have them • Run a link checker on the site • Check logs for error messages and warnings • Click around and manually test important or prominent features If all is well, deploy and be happy. 🎉
- 50. Problems after an update If some new problems appear after an update – ideally found before going into production – there are two possible causes: • You made a mistake. Double-check your changes and try to verify against the previous version. • You found a bug. Check the issue tracker for a new report that looks like your problem
- 51. Recap: Why, When and How Why? Because you get new features and bug fi xes. When? Whenever a new version is released. How? Read & follow instructions, test & deploy. Done!
- 52. Done. Questions!
- 53. Thanks for listening! Further reading: https://www. fl ownative.com/en/blog/neoscon-2024-updating-neos.html Contact me at: • karsten@ fl ownative.com • @kdambekalns in the Neos Slack