Reading time: 7 min read
Upgrade Sitecore 10.1.X - 10.3.X to 10.4 on Your Local Docker Environment
Looking for a easy to follow guide on upgrading to Sitecore 10.4? Checkout our step by step guide that can help with that
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.
| Name | Description |
|---|---|
| COMPOSE_PROJECT_NAME | The name of the topology/name of your project |
| SQL_DATABASE_PREFIX | Database prefix (default is Sitecore) |
| SQL_SERVER | SQL Server name |
| SQL_USERNAME | SQL admin username |
| SQL_PASSWORD | SQL admin password |
| DATABASE_UPGRADE_FROM_VERSION | Sitecore version which you are going to upgrade |
| SITECORE_LICENSE* | License file converted to base64 |
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.ymlhas correctconnectionStrings-
SQL Server’s network and Upgrade container’s network match
-
To check the network you can run
docker network lsand 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_defaultalong with theCOMPOSE_PROJECT_NAMEenvironment variable.
-
To specify a network to the container, you can look at the screenshot under
Database connection stringssection.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.