User Documentation

Download
Launch

Joomla 1.5 to 4 Planning and Migration Step-by-Step

Going from Joomla! 1.5 to 4.x is considered a major migration. This means that considerable changes in how Joomla works, tables, technology have occurred that require a migration instead of an upgrade or update. Both Joomla core extensions and any third-party extensions will need to migrate to Joomla 4.x. This includes the site template. Every single thing needs to be looked at, planned, decided upon, and executed. You will need to be diligent with staying organized throughout the process.

Intro

The fabulous thing about migration is that it is a great time to reassess goals, create a new look and feel (template), clean up, and develop other areas/elements of your site. The more organized you can be with your ideas/thoughts/plans, the better. Planning makes execution easier.

Start planning by asking the following questions or doing the tasks listed below. You may have more items to plan for depending on the complexity of your site. Sadly, there is no way we can list every possible scenario.

You can ask specific questions on the Joomla 4.x General Questions/New to Joomla 4.x Forum.

Planning Action Items

General

  1. Assess your original site goals. Migration is an opportunity to get back into focus with your goals or change direction.
  2. Does your server meet the minimum technical requirements for Joomla 4? If not, you will need to change hosts. No better time to change hosts than during a migration.
  3. What kind of development environment will you use? A development environment on your local device? A subdomain or subdirectory on your server? A new server/hosting account due to technical specifications?

Joomla Core

  1. Clean-up your current site. Take a look at your Sections, Categories, and Articles. Sections are converted to higher level categories from Joomla 2.5 on. Is there clean-up that needs to be done so that you don’t migrate unnecessary content? Document what you want to delete. Alternatively, you may want to document what you want to bring over depending on quantity.
  2. Organize your content on the current site. Do the Categories you have still apply? Document new categories you may want to add in your new site.
  3. Do you have any articles in the trash? If so, delete them (and any applicable media that may be associated with them if not in use elsewhere on the site). Articles (categories and menu items too) left in the trash can cause duplicate alias issues once migrated.
  4. The Media Manager: Decide whether you want to bring your entire /images directory over or just part of it. If your Media Manager has become a disaster, you may decide to bring over specific images via FTP or cPanel instead of migrating the entire directory. In the future, organize folders in the Media Manager so you don’t end up with a big mess.
  5. If you are using core components like Joomla Contacts, Web Links, or News Feeds, document this as you will need to bring those over.
  6. Check your menus and determine if you will bring them all over or only specific menus and menu items. Delete any menu items from the trash to prevent duplicate aliases.
  7. If you redesign or make changes to your site design or navigation, will you have obsolete pages that will require a redirect? Track all URLs that need redirects on a spreadsheet or notepad.
  8. Did you “hack the core” of your 1.5 site? If so, those changes will not migrate to Joomla 4. You will want to find alternatives to hacking the core in Joomla 4 (Understanding Output Overrides, Layout Overrides in Joomla).
  9. Check your User Manager. Are you intending to bring them all over? Is there clean up required? Perhaps Super Users that no longer should have access or spam users that need to be deleted? Are you using some kind of third-party extension to enhance User Profiles? This part needs careful planning especially if the user data changes frequently.
  10. Are there new features of Joomla that you wish to use, such as Access Control Levels (ACLs), tags, workflows, or custom fields? Start planning for that now. Planning ACLs is cautious business. Being thorough is very important.

Third-party Extensions

  1. Make a list of all third-party extensions in use. This includes components, modules, plugins, languages, and templates. You may copy/paste them from the Manage page into a document for reference if you’d like. A piece of paper and a pen will suffice. Include if these extensions are used heavily, moderately, hardly ever, or not at all.
  2. Determine whether the third-party extensions you rely on are ready for Joomla 4.
  3. Determine if you really need all the extensions you are using. Perhaps Joomla 4 has built-in features that could eliminate the third-party extension.
  4. What about your site template? If you purchased your template from a third-party source, is there a 4.x version released for it? Would you like to continue using it? Is there a migration path published by the developer? Is the new version of it responsive? Is your template a custom template? Or was it heavily customized from a third-party template? For an expansion of Template-based considerations, see Template Considerations During Migration.
  5. If you are changing your template for a new one, will it require any new images? For example, if your current site has a white background and your logo or other images are .jpg images with a white background, it won’t look very nice against a new template with an off-white or coloured background.

The following are step-by-step instructions to migrate your 1.5 site to Joomla 4.x. While there are many ways to migrate your site, this will give you the basic procedure to follow.

Introduction

The migration from Joomla! 1.5 to 4.x is a major migration. There are many changes in features and database tables between these two versions. It is not a one-click update. You will be building and installing a fresh Joomla! 4 installation and then migrating (moving) your data into it. If you haven't already, you may want to start with the Self Assessment document.

Let’s first distinguish between Joomla Core data and third-party extension data. Joomla Core data (Components) are:

  • Categories
  • Articles
  • Menus
  • Modules (core modules - not third-party)
  • Banners
  • Contacts
  • Messaging
  • News Feeds
  • Redirect
  • Search
  • Smart Search

Step-by-Step

Moving Joomla core data is fairly straight-forward with the use of a migration tool. Everything else is a third-party extension or a custom built extension. This includes the template. Each third-party extension needs to be researched to determine if it’s ready for Joomla 4.x and has a migration path. You may have done this in the planning process above. If not, do it now. Some third-party extensions can be migrated with a third-party tool. Some cannot. Read. Research. Plan.

Since there are many ways to migrate data and each site is different, the exact steps are going to be slightly different for every site.

Prepare a Location for Joomla 4

  1. Make sure your server environment meets the technical requirements for Joomla! 4 before proceeding.
     
    Note If your host does not meet the technical requirements, you will need to change hosts. If you need to change hosts, set up a new hosting account on a host that meets the specifications and install your fresh Joomla 4.x site in the root of the server on a temporary domain. This will make it easier when it’s time to go live. Alternatively, you can set up a development location on a local device. (See below.)
  2. Create a new database and new user for your Joomla! 4.x site. Document the database name, database username and database password as you’ll need these when you install Joomla 4.

Set Up a Development Location

  1. Create a testing site or build area to work in with one of the following:
  2. Install a fresh installation of the latest version of Joomla 4.x into your testing site location using your new database name and database credentials.
     
     
    Note If you will be migrating any of the core extensions that will be decoupled from Joomla! 3.4+, you will need to install Joomla 4.x and the core supported extension. Core supported extensions will be accessible via the Joomla Extensions Directory and via the Install from web tab of the Extension Manager. Make sure you install any core supported extensions before migrating data. See the Project Roadmap for more details on what will be decoupled/removed. As of August 2021, only Web Links has been decoupled.
  3. Run a backup of your Joomla 4 site. (Backup Basics for a Joomla! Web Site or see Suggested Tools)

Prepare Your Current 1.5 Site

  1. On your 1.5 site, update it to the latest version 1.5.26 after backing it up.
  2. Clean up your sections, categories, articles, modules, menu items. Make sure they all have unique aliases.
  3. Empty the trash in the content manager (sections, categories, articles), menu manager, module manager.
     
    Note Sections no longer exist in Joomla 4. Sections become a parent Category. Categories became nested categories of the parent category.
     
  4. Notify users that any changes on the current site from this point forward will have to be reentered on the new site. For complex migrations with changing data, see the Complex Joomla! 1.5 Migration With Minimal Downtime magazine article and the Complex Migrations video.

Choose a Migration Tool

  1. There are many migration tools. Some are free, some cost a bit of money. Some only migrate certain data. Some migrate more types of data than others.
  2. Migration tools can be found at the Migration & Conversion category in the Joomla Extension Directory.
  3. Verify that the candidate migration tool has been updated to work with Joomla 4.
  4. Each migration tool has its own step-by-step documentation on how to move data. (If they don’t don’t use it.) Some migration tools will require the 1.5 site and 4 site on the same server. If you’re switching hosts, you will want to restore a *subdomain* of your 1.5 site on your new hosting account to pull the data from. Then kill it when you’re done.
  5. When you choose a tool, select one that allows you to preserve the ItemIDs. This is necessary to keep your search engine ranking intact or you may have more redirects to do. More information on redirects follow.
  6. If you have a small site, you may want to do the migration manually. Create categories and articles and copy the HTML over into your new site. Then copy the image directory over. Keep the /stories directory (which is no longer the default image directory in Joomla 4.x) or your image links will be broken until you fix each one.
  7. One of the migration tools (a free one) allows you to bring articles and only images associated with those articles over. This is helpful if your Media Manager is out of control.

Migration

  1. Migrate all core data you want to move to Joomla 4.x. If your migration tool asks to move Sections and Categories, definitely do both. The conversion will happen to categories and nested categories automatically.
  2. Run the Database Fix by going to Extension Manager → Database and click the Fix button in the top toolbar.
  3. Install your new template or converted template so that you can see your content. See more about Template Considerations.
  4. Add new menus if the tool you chose to use didn't bring over menus. If you want to use split menus, set that up now.
  5. Add modules if the tool you chose to use didn't bring over modules. If the tool you chose to use brought over modules, change the module positions to the positions in your new template if required so that your modules show up and you can see what you’re working with.
  6. Check for duplicate alias issues and fix them.
  7. Check your internal links. If any are broken, fix them.
  8. Take a backup.
  9. Install other third-party extensions and configure them. (For example editors, Akeeba backup, slideshows, or plugins.)
  10. Take a backup.
  11. If you have large extensions with data to migrate, do each one according to the developer documentation and then take a backup after each one.
  12. If your migration tool didn't move the images, you will want to move your images from the 1.5 site to the 4.x site. Note: keep the /stories directory unless you want to relink all your images. You can start a new organisational structure in the /images directory from here forward if stories is a mess.
  13. Recommended but not required unless you have issues: Fix asset issues. See below for a helpful tool.
  14. If you are going to add anything to your site or use new core features such as Tags or Custom Fields, get them set up and configured at this time.
  15. Check your URLs on the Joomla 4 site and compare to the Joomla 1.5 site. If they are different, document each 1.5 URL and what Joomla 4.x URL they will be going to so that you can do redirects and keep your ranking. (An Excel spreadsheet is helpful.) See:
  16. Take a backup.
  17. Check everything.
  18. Clean up more.
  19. Test everything.
  20. Take a backup.
  21. Move or change or add updated data from the 1.5 site to the Joomla 4 site.
  22. Add Google Analytics to the template or use a third-party plugin.
  23. Check the Global Configuration and make sure all is as it should be.
  24. Take a final backup of the Joomla 4.x site.
  25. Take a final backup of the 1.5 site.
  26. Move your 1.5 site from the root to another subdomain or subdirectory or simply delete it. (This is so that you have it again for a brief time if you need to refer to it.)
  27. Backup and restore using a suggested tool (below) or simply move files to restore your 4.x site to the root of your hosting.
     
    Note If you are changing hosts, you can leave your Joomla 4.x site where it is and simply change name servers on the domain to make it live. Make sure you've addressed any email issues first.
  28. Enable .htaccess if necessary for Search Engine Friendly URLs.
  29. Create a sitemap and submit to Google Webmaster Tools or any other search engine you would like.
  30. Do all your redirects from the spreadsheet you created earlier for URLs that changed in the migration process.
  31. Make any other changes that needed to wait until the 4.x site was live.
  32. Test again.
  33. Take another backup.
  34. Kill any instance(s) of the 1.5 site as soon as possible.
  35. Remove all other development sites you may have been working with or keep them up-to-date if they are running a current version in order to ward off hack attempts on your server.
  36. Welcome to Joomla! 4.x!

Suggested Tools