Note: this whole story is written about migrating from J!3 to J!4 and changing the template from (a modified copy of) Protostar to Cassiopeia. If you're using another template, a lot of stuff after the actual migration will probably be different.
Right, it's time to do my first migration...
Chose the simplest site I've made, early in 2018. The template is a copy of Protostar. It does use a custom font, though. There are no users.
Set up a local "migration" folder
You need a place to temporarily store files that need to be moved from the old site to the new one (e.g. custom fonts, favicons) and files that need to be modified and then moved (e.g. htaccess, user.css).
Download user.css to the local folder. Do a general check. Remove all the menu-css (won't work anyway, and a lot of it is native Cassiopeia).
Save user.css for use after migration.
Freeze the live site
No problem in this case. It's a pretty static site.
If any changes do come up, they'll have to wait until after the migration (or I'll have to do them twice).
Set up Dev Location
Created a subdomain on my own website, and created a shiny new database.
Moved the J!3 site to the subdomain using the Akeeba .jpa file and Kickstart.
Did a backup.
Check database schema
Structure is up to date.
For articles, categories, menu's and modules. Easy in this case, trash was empty.
There were some "left overs" from old Akeeba versions (fofs and fefs, stuff like that). Akeeba has developed a tool to remove them, the Magic Eraser. I ran it, and it did an excellent job of removing the left overs.
All the other stuff can be simply uninstalled:
- Dutch Language pack - I can uninstall that, and there is a working version for J!4.
- RL Emailprotector - can be uninstalled. J!4 has it's own native Emailprotector.
- MySites plugin - needs to be removed, the site will be added back to MySites after migration.
- Top-of-the-page plugin - can be uninstalled. J!4 has it's own native To-top.
Dutch Language pack
Checked for overrides (there weren't any).
Set default language to English for front & backend.
Uninstalled Dutch language pack.
Uninstalled them. No issues.
Set Protostar as default.
Remove all other templates, frontend (Beez and my copy of Protostar), and backend (Hathor).
Run a backup
Turn on error reporting
Check pre-update checker one more time, just in case
Good to go.
We're going to update to 4.0.3.
Step-by-step says: make tea... But for this site, it didn't take very long.
Read post-installation messages. Activated HTTP Security Headers.
Install Akeeba 9 (the J4 version). Let it convert the settings from Akeeba 8. Run Configuration Wizard. Run a backup. Interesting: the new jpa backup file is about twice as large as the old one.
Uninstall Akeeba 8.
Set the Atum Style to one of the site's main colors and add the site's logo. 🤣
So far, so good 😊 🍷
Have a glass of wine.
Upload and install any extensions that have a J!4 version (if you had to remove the J!3 version).
Make sure Joomla Text Filtering is ON, at least for the sets that will be used on the site. (Note: the migration process does not retain the settings you had in J!3).
If the Dutch language pack was uninstalled before upgrade, and is necessary on the site, re-install it (and set as default).
Make new .htaccess
The standard htaccess.txt that comes with J!4 is not the same as the J!3 one. (See Github).
The migration process, however, dutifully copies your old .htaccess to your new J!4 installation.
So: remove the J!3 .htaccess, add any "personal" rules to the J!4 htaccess.txt, rename it to .htaccess, upload to J!4 root folder.
In this case, I added the rule to rewrite www to non-www (which I copied from Developer Mozilla).
Go to the modules list, and reassign all your modules to Cassiopeia positions.
Set the style for your Main Menu module - I set Cassiopeia Collapsible Dropdown.
Get the old site's favicon.ico. Get an SVG version of the favicon, rename it to joomla-favicon.svg. Make a copy of this, and rename it to joomla-favicon-pinned.svg.
Upload these three files to cassiopeia/images.
If used, upload any custom fonts to templates/cassiopeia/fonts. The @font-face rules in the old user.css should still work.
If used: set Cassiopeia's style to use Roboto as font.
Rework the CSS
This is actually the part I was dreading the most...
Transfer the old user.css from your local migration folder - checked and modified in an earlier step - to Cassiopeia. The site is now starting to look more like itself again but there's a lot of CSS tweaking to be done.
The CSS for custom modules still works nicely, though sometimes you need to add a class, or modify the selector slightly.
And then start checking page by page, adding custom css rules as you go along.
Make a final backup, save a copy off-site. Transfer a copy of the .jpa to your local migration-folder.
Log in to the J!3 site, run a final backup, save a copy off-site.
Take a deep breath.
In the hoster's C-Panel, delete the J!3 database and remove all the files.
Create a new database for the J!4 site.
Upload the J!4 definitive .jpa file plus Kickstart.
If error reporting is still on, turn it off again.
Check in Global that robots.txt is set to index and follow.
If you hadn't done so already, set a custom Output Directory for Akeeba.
If required, register the J!4 site with MySites.guru.