Upgrading the (Session-enabled) Content Service

The Content Service serves content from the Content Data Store to the website. The Session-enabled Content Service does the same, but adds session information.

Before you begin

To run Powershell scripts, you require a machine that meets the following requirements (any Tridion Sites 9.6 server machine running Windows meets these requirements):
PrerequisiteDescription
Operating systemYou can run the scripts on any machine running an operating system that supports any version of Powershell of 5.0 and higher.
Powershell softwareRunning the scripts requires a version of Powershell between 5.0 and higher.
Microsoft .NET FrameworkRunning the scripts requires Microsoft .NET Framework 4.8 or higher.
SecurityYou need to be logged in as a user with sufficient security clearance. For example, to run a script that installs software to a target folder, you must be logged in as a user with write access to that folder.
The following must be true before you start upgrading the (Session-enabled) Content Service:
  • If you are using Digital Experience Accelerator (DXA) to build your website, your (Session-enabled) Content Service needs to continue to be extended with the DXA Model Extension in order to support the DXA data model. So, when upgrading the (Session-enabled) Content Service, you must also upgrade the DXA Model Extension to the same version. Refer to the DXA documentation for installation instructions and a list of compatible versions.
  • You must have set up the search feature introduced in SDL Tridion Sites 9.5.

About this task

When you run the microservice installation script, you can specify the following types of parameters:
Environmental parameters
You can set and pass environmental parameters to the microservice scripts in the following ways:
  • You can create and set them as environment variables on the operating system of the machine on which the microservice runs.
  • You can hardcode them in the application.properties file located in the configuration location of the microservice.
  • You can pass them using the -D switch when you run the script from the command line. For example, to specify that the parameter foo has the value bar, you would type '-Dfoo=bar' after your script command.
Script parameters

You may want to add script parameters to your installation script. To do so, append them to the installation script command, in the form --PARAMETER (if it is a Boolean parameter) or --PARAMETER=VALUE (if it is a parameter-value pair) , where PARAMETER is the name of the parameter, and VALUE (when using) is the value you want to set it to.

You can install the microservice in one of the following ways:
Installation typeName of installation scriptWhen to use
Microsoft Windows serviceinstallService.ps1Choose for long-term use on Windows, say on a production system. The microservice continues to run when you close the PowerShell prompt. It can be stopped and restarted from the Windows Control Panel. It outputs its log as a file.
Microsoft Windows processstart.ps1Choose for short-term use on Windows, say on a test system. The microservice stops running when you close the PowerShell prompt. It outputs its log in the command prompt window.
Unix processstart.shChoose if you are installing on a Unix-based operating system.

Procedure

  1. If the server on which this microservice is installed is a Windows machine, uninstall the Windows service by doing the following:
    1. On the server, open a Powershell command prompt.
    2. Access the bin\ subfolder of the microservice root folder.
    3. Run the script called uninstallService.ps1, with an environmental parameter emscustomerid set to the customer ID you received from RWS Customer Support.
  2. On the server on which this microservice is installed, navigate to the configuration location of the microservice.
  3. Back up the contents of this folder to a safe location.
  4. Back up any custom microservice extensions you have created, along with their configuration files, to a safe location.
  5. On your Tridion Sites 9.6 installation media, navigate to the folder Content Delivery\roles\.
  6. Do one of the following:
    • If you are upgrading the Session-enabled Content Service, navigate to the session\service\ subfolder.
    • If you are upgrading the regular Content Service, navigate to the content\ subfolder.
  7. Navigate to the standalone\ subfolder.
  8. Delete all files and subfolders from the microservice location.
  9. Copy the contents of the installation media folder, including subfolders, to your installed microservice location.
  10. For each of your configuration files, do one of the folllowing:
    • If you have previously made changes to the file that you backed up, compare your backed-up version to the new version you just copied to the configuration location of the microservice, and merge your old file into the new file.
    • Alternatively, if you have not changed your backed-up file, ignore it and use the new file instead.
  11. If one of your microservice extensions is the DXA Model Extension, you must now get rid of this extension. Do not restore the DXA Model Extension in the next step.
  12. Restore any backed-up custom microservice extensions, along with their backed-up configuration files, to your microservice.
  13. In the configuration location of the service, open search.properties for editing. You see the following properties:
    Property nameDescriptionDefault value if not modified
    es.hostThe name of the host on which your Elasticsearch instance runs localhost
    es.portThe number of the port on which your Elasticsearch instance runs 9200
    es.schemeIf you connect to the Elasticsearch instance through HTTPS, https none (connect through HTTP)
    es.usernameIf the Elasticsearch instance is secured, the name of a user who can access the Elasticsearch instance none (Elasticsearch instance is not secured)
    es.passwordIf the Elasticsearch instance is secured, the password of the user above, encrypted with the RWS encryption toolnone (Elasticsearch instance is not secured)
    index.common.name.prefixAn index prefix (if needed) to distinguish this Elasticsearch instance from others. For example, if you have a staging and a live environment, you might set this prefix to staging for all your Elasticsearch indexes for the staging environment, and to live for all your Elasticsearch indexes for the live environment. The prefix is prepended to the normal index name, udp-index, to create PREFIXudp-index, where PREFIX is the value of this property.an empty string (the index has no prefix)
  14. Do one of the following:
    • Set environment variables on your server operating system to set values for the properties above. The environment variables to set are:
      • eshost
      • esport
      • esscheme
      • esusername
      • espassword
      • indexprefix
    • Alternatively, hard-code the property values in search.properties itself.
    In either case, use the RWS encryption tool to encrypt the password and set the value of the password in its encrypted form.
  15. If your Discovery Service is running on another server, on another port, or if you have changed the password of the user who registers Capabilities in the Discovery Service, go to the config\ subfolder, open cd_storage_conf.xml for viewing, and specify environment parameters for the variables being mentioned in the ConfigRepository element: discoveryurl for your custom server and/or port, and registrationpassword for your custom password.
  16. If you are running this microservice script on a machine on which the Discovery Service is also running (that is, if you are not in a scaled-out setup), pass a DependsOn script parameter, set to the value TridionDiscoveryService.
  17. On a Unix-based system, to run the microservice as a standalone process, type /bin/sh start.sh, with an environmental parameter emscustomerid set to the customer ID provided to you by RWS, but do not yet press Enter.
  18. Alternatively, on a Windows system, open a PowerShell prompt and do one of the following:
    • To install as a Windows service, type & '.\installService.ps1', with an environmental parameter emscustomerid set to the customer ID provided to you by RWS, but do not yet press Enter.
    • To start as a standalone Windows process, type & '.\start.ps1', with an environmental parameter emscustomerid set to the customer ID provided to you by RWS, but do not yet press Enter.
  19. If you do not want the service to register itself as a Capability with the Discovery Service automatically, add an auto-register parameter set to the value false.
  20. After making sure that your Add-on service is up and running, add the string -Daddonserviceurl=URL, where URL is the URL of the Add-on service. Alternatively, you can define an environment variable called addonserviceurl on this machine, and set it to the URL of the Add-on service.
  21. If your Add-on service is secured, set a number of additional parameters to connect to the identity provider, either using -D switches or by setting environment variables in your operating system.
  22. To specify a different default HTTP port than the default, add a server.port parameter and set it to the port number of your choice.
  23. To specify a default context path, add a server.contextPath parameter and set it to the context path of your choice (the value must start with a /).
  24. Press Enter.