Hi!
In today's post, I would like to talk about the migration of Liferay projects between the versions, and more precisely to present the problems related to this based on my own experience. I personally participated in the migration of several projects - both from version 6.2 to 7.x and from version 7.0 to 7.2 (here additionally from CE version to DXP version). In addition, these migrations covered the whole spectrum of "cases" in terms of size - these were small modules with literally several portlets, medium projects with several database entities and several dozen portlets, but there was also one project that contained far more than 100 portlets and database entities.
It is on the basis of these experiences that I would like to show some examples of what problems we may encounter during migration. By doing so, I would like to make you aware of the fact not to believe that you will automatically manage to migrate the project, because that will most probably not be the case. I will say more - I had to debug the Liferay code myself in some cases because unfortunately, in many cases neither the documentation, nor the existing topics in the forum, nor even asking my own question, helped. Of course, if you have DXP versions, there is a chance that you will receive official support, although I know from experience that a small part of portals is based on a paid version which, due to the cost, is quite understandable.
I warn you straight away that there will not be too much code or real examples in this post because it would just take too much time to recreate them, and the production code at which my problems occurred for obvious reasons I cannot show. Nevertheless, I hope you will be able to get something useful out of the few minutes you spend reading this text.
Attention: During the writing process, it turned out to be so much material that I decided to split it into two parts. The second part will be coming soon - I simply thought, when writing this post, which was supposed to be a whole, that there was too much of it, and I did not even get to the 'main' part that I wanted to write about, namely the migration of modules.
Note! There is also second part of the article available showing some issues in code migration process. Check this out Why migrating Liferay projects to a newer version is not easy v2
Why update Liferay versions at all?
It is worth asking ourselves first - why do we migrate at all? There are a few answers - first and foremost safety. Just look at the so-called "known vulnerabilities" to see that old versions of Liferay contain a lot of shortcomings.
Another issue may be the novelties that offer newer versions of the technology used. In the case of Liferay, it is perfectly visible on the example of version 6.2 and 7.x (even 7.0) - the leap was huge due to the transition to OSGI, for example.
How does migration in Liferay look like
As I wrote earlier - this entry will not be an instruction to carry out the migration because for it is the official documentation. I'm not hiding the fact that it could probably be presented much better than in the official documentation, but it would be a topic for the whole course rather than a blog post.
However, if at this point you are not interested in going through the whole documentation, you can still assume that migration comes down to a few points in a nutshell:
- Preparation of our portal - all backups, removal of duplicates or unused articles etc.
- Updating the database - using a script
- Migration of our modules to new versions - in case of migration from 6.2 you will most probably also need to break down the application into any modules
- Tests, tests and more tests
And I'll focus on the first three to describe what can happen to us.
Preparation of a portal
The preparation of a portal is a step that is recommended in the official documentation, although, does it seems to be possible to skip it? Well, unfortunately, as it turns out, that not always it is possible. As a standard, this preparation of a portal is aimed at saving space and speeding up the migration process, although there is also a second bottom - Liferay does not always deal properly with old references. What is the old reference? For example, it could be some old webcontent that we no longer use and have long forgotten about. At one point, someone deleted the photo that this WebContent was using. It seems that nothing bad can happen because this is standard behavior - after all, nobody analyzes the content of all articles before removing the photo and really nothing bad happens in this case.
However, we move on to the migration of our portal to a higher version, we have migrated everything, the portal works until one time we download the whole LAR from the server in order to locally restore the portal and... we finish with the so-called "infinite loop". Sounds incredible? And yet, that's what happened to me. I'll add that the portal was originally 7.0.6 CE and migrated to 7.2.1 DXP. You can see the whole story (along with the advice I received) on the Liferay forum. I'll just add that in addition to the solutions proposed there with logs (which helped a lot!) I had to debug the Liferay code.
And it was only about the removed photo... In the defense of Liferay, I'll only admit that this case was specific - not always the removed photo will spoil anything (rather never), but from what I've noticed only when we upload the photo directly to the content from the editor, skipping documents & media. Maybe there must be some additional cases because I had a lot of pictures in this migrated portal (thousands), and only one of them turned out to be problematic.
How to look for such “bad” pictures? Generally, I didn't know that such a problem exists and so, as I mentioned, I ended up debugging the Liferay code along with reading logs on the DEBUG level (a lot of it) and so I found my broken WebContent. However, if I had more of such cases, most probably I would try some tool for searching "Broken references" - generally it would be to search our site for places where we have broken photos (you know - such a small icon of a photo that didn't load because of a bad source). Unfortunately, it won't work if our webcontent is not embedded anywhere - then you could probably write some small program to look for it.
Updating the database
As far as updating the database itself is concerned, I admit it's not bad. The creators of the so-called "upgrade tool" did a good job because I didn't encounter any major problems, despite migrating really large databases (one with about 8 virtual instances and the other even with about 20). In fact, I encountered only two problems strictly related to the migration of the database, but they were not tragic - considering how much it could have broken down in WebContents for example
JAX-RS configuration entries
In one of the migrated applications (7.0.6 -> 7.2.1 DXP), where the JAX-RS was used (about which in the context of Liferay you can read here) there was an error at the start of the application and it looked like this:
It was associated with incorrect entries in the Configuration_ table. They looked more or less like this:
- liferay.portal.remote.rest.extender.configuration.RestExtenderConfiguration.e7c762dd-9fed-4956-8bbf-a89ec9e3a1b8
- liferay.portal.remote.rest.extender.configuration.RestExtenderConfiguration.factory
There were more of them (one for "Factory" and one for each registered endpoint). Numbers will also be different (in case of the first one), so the easiest way to find them is with a query:
select * from Configuration_ WHERE configurationId like ‘%com.liferay.portal.remote.rest.extender.configuration.RestExtenderConfiguratio%’
Solution? Just delete these entries and use them during the database migration. When we migrate our JAX-RS related modules and run them all will work properly.
Release_ table
The second problem I encountered was incorrect entries in the Release_ table, which stores information about application versions or modules. The problem arose when migrating from version 6.2 GA2 to version 7.3 GA1 - the release table did not migrate correctly, although it was enough to compare its contents with the "fresh" database created in 7.3.1 and "swap" the entries and everything worked correctly.
In conclusion
As I mentioned in the introduction, this is the first of two articles on migration problems. In the second post I'll describe the topic of module migration where there are many more problems - there I'm sure I won't even describe everyone I've met because there are a lot of them, although many of them are rather due to poor documentation (and deficiencies in the so-called "Breaking changes"), but most of them are not so difficult to fix.
And finally, good luck!
PS
If you are looking for help with such migrations in your company, do not hesitate to contact me. I can help with small migrations as well as large ones.