Upgrade Sitecore 10.1.X - 10.3.X to 10.4 on Your Local Docker Environment

Step-by-Step Guide to Upgrading Your Sitecore Environment

With the release of much awaited Sitecore 10.4 here is our barebones guide on you can upgrade to 10.4 from 10.1.x -10.3.x. If you wish to know what’s new in Sitecore 10.4 checkout our comprehensive overview of 10.4. Let’s get started!

First and foremost, download the Sitecore Container Deployment package and the upgrade container guide. Extract the container deployment to your desired location like C:\Fishtank\Sitecore packages\ and we are only interested in the upgrade folder which will be located at SitecoreContainerDeployment.10.4.0.010422.1755\compose\ltsc2022\upgrade. The upgrade is divided in three parts:

• Database (DB) Upgrade
• Docker Container upgrade
• Clean up

Disclaimer: We’ll be looking at upgrading an XM 10.3.0 to 10.4 but you can use this as a guide along with the upgrade container guide to upgrade your XM OR XP to 10.4. For now it only supports 9.3.0 to 10.3.x version to upgrade so keep that in mind before you start with your upgrade.

Upgrading Your Database

Before jumping into the db upgrade process, take the backup of your existing dbs to be on the safe side. In order to do the db upgrade, we’ll do the following:

• Migrate Environment Variables
• Upgrade Database connection strings
• Execute DB upgrade scripts

Migrate Environment Variables

Copy the contents of folder from SitecoreContainerDeployment.10.4.0.010422.1755\compose\ltsc2022\upgrade\xm1 folder to your project except compose-init.ps1 file. Open up upgrade.env and populate the variables according to your existing .env file for your project.

To convert your license file to base64 use the helper function in Appendix A from the upgrade container guide. Simply execute the script while passing the license.xml file and it’ll give you the base64 encoded version of your license which you can paste in your upgrade.env file above.

Upgrade Database Connection Strings

Modify any of connection strings in docker-compose.upgrade.yml if you use custom databases. If you don’t use any custom databases, you can leave it as is. The best way to go about it is comparing what the cm image is using for its dbs and matching them.

You can ignore the User ID and Password being different as it’ll depend upon what the variable name is in the env files. The docker-compose.yml or docker-compose.override.yml will depend on the .env file and the docker-compose.upgrade.yml will depend upon the upgrade.env file.

Execution

Make sure to get your SQL Server up before starting with the execution and for that you can simply get your Sitecore instance by running up command or the up script if you’re using one. Once the server is up, run the following command from where you have docker-compose.upgrade.yml and upgrade.env file located.

docker compose -f .\docker-compose.upgrade.yml --env-file .\upgrade.env up

The above command will download the scr.sitecore.com/sxp/sitecore-xm1-mssql-upgrade:10.4-ltsc2022 image which will execute the necessary upgrade scripts for the databases and you should see the following in your console/terminal after it is completed.

Next we’ll upgrade the docker containers so the project downloads the necessary 10.4 docker images and as previously stated, currently Sitecore 10.4 only supports ltsc2022.

Docker Container Upgrade

Make sure to down your Sitecore instance before you start with docker container upgrade. You can do this by running docker down command or down script if you’re using one. Once your instance is down, simply change the SITECORE_VERSION variable from your .env file from , in our case, 10.3-ltsc2022 to 10.4-ltsc2022. After this, we recommend to run a --no-cache build for your docker images if you override the OOTB Sitecore images. To do so, run the following:

docker-compose build --no-cache

Once the images are built you get your Sitecore instance up which will download the OOTB Sitecore 10.4 ltsc2022 docker images. Be patient as depending upon your internet it can take a while but let the process finish and this will be a good time to treat yourself with a cup of coffee or tea. After this you should have Sitecore 10.4 running and to verify you can go the control panel and check the license details.

Clean Up

After going through the DB upgrade step you’ll be left with the mssql-upgrade container and image. It is recommended that you remove this and to do so run the following:

docker compose -f .\docker-compose.upgrade.yml --env-file .\upgrade.env down

Troubleshooting

ERROR: A network-related or instance-specific error occurred while
establishing a connection to SQL Server. The server was not found or was not
accessible. Verify that the instance name is correct and that SQL Server is
configured to allow remote connections. (provider: Named Pipes Provider,
error: 40 - Could not open a connection to SQL Server)

To resolve the above error verify the following and make sure:

• SQL Server is running
• docker-compose.upgrade.yml has correct connectionStrings

• SQL Server’s network and Upgrade container’s network match

  • To check the network you can run docker network ls and it will give you all the list of your networks. A general rule of thumb is that the network is created with a suffix of _default along with the COMPOSE_PROJECT_NAME environment variable.

    

  • To specify a network to the container, you can look at the screenshot under Database connection strings section.

      networks:
        network1:
          name: fishtank-xm1_default
          external: true
    

Final Thoughts and Reverting (If Things Don’t Go as Planned)

That’s all folks! We went through a step by step guide on how to upgrade your Sitecore Instance to 10.4. As mentioned earlier, this is barebones guide so make sure that if you’re not using the default databases that comes with OOTB Sitecore installation then change the connectionStrings accordingly otherwise it will be difficult to revert this if you don’t have the backups of the dbs.

In case if you had any issues, simply put back the databases under mssql-data folder. Also, don’t forget to revert the SITECORE_VERSION back to what you had in your .env file before you started with the upgrade. Our recommendation would be reverse what we did in Docker Container upgrade section and then do the Clean up in case you ran with the upgrade. You won’t need this upgrade if you were using XM Cloud, one of the many advantages of moving to XMCloud. If you’re interested in making to XM Cloud please reach out to our team for chat. Fishtank is an XM Cloud specialized Sitecore partner.

---