Skip to main content

Upgrade the Fredhopper version included in the deployment package

Rumyana Grigorova
  • Updated

    The following article describes the process of upgrading the Fredhopper installation without impacting your web page.
    The intended audience are System Operators familiar with Fredhopper.

    Impact on the environment
    The steps below outline the procedure necessary to upgrade from one Fredhopper version to another.
    Please be aware that this process may necessitate upgrades to connected systems, such as:
    • Custom components used in the deployment
    • The data-manager components used in the deployment.
    • The jobs defining the deployment process.
    • The deployment agent software itself.
    • Changes to the configuration and data as required by the migration.
    • Changes to your front end.

    Prerequisites

    Before starting the upgrade, ensure that the environment is in a fully working state. This includes the following conditions:

    • The ETL process is working correctly and the the correct source data is available.
    • The indexing processes show no errors when loading the FAS-XML input.
    • All live servers are up and running with no errors in their respective log files.
    • The config/topology.txt file is up to date and available on all environments.

    The following variables will be used:

    • <INSTANCE>: Name of the instance you are working on
    • <HOST>: Name of the server the instance is residing on
    • <PRESET>: The preset name to configure the defaults of the Fredhopper instance. See Working with the topology file for more information about presets.
    • <SYNCSERVER_PORT>: Port of the syncserver process of the indexer.
    • <SYNCSERVER_HOST>: Host of the syncserver process of the indexer. Identical with the <HOST> value of the indexer.
    • <QSERVER_MEMORY>: Memory available to the query server process.
    • <BASE_DIRECTORY> : Fredhopper Deployment Package Base Directory (e.g. C:\fredhopper, /home/fredhopper/)
    All commands are executed from the base directory of the controlling server (the server with the config/topology.txt), unless noted otherwise.
    Downtime
    In order to avoid downtime it is essential that you have at least 2 live instances available in your environment.

    Custom Components

    Fredhopper can be extended with "custom" components, which are stored in data/instances/<INSTANCE>/custom.

    When upgrading these components usually require an update as well.

    If you are using custom components please check with Attraqt for compatibility.

    Step-By-Step Instructions

    Step 1: Shut down the synchronization between indexer and live instances

    Upgrading Fredhopper will produce a new item-index and configuration which will we incompatible with the current Fredhopper version. To avoid impact on your web page you have to shut down the synchronization between the instances.

    1. Login to the controlling server
    2. For each live instance connected to this indexer:
      1. Stop the syncclient 
        bin/deployment-agent-client --location <HOST> invoke <INSTANCE> syncclient stop
      2. Verify that the syncclient is stopped by executing 
        bin/deployment-agent-client --location <HOST> invoke <INSTANCE> syncclient status

        The expected result is STOPPED.

    Find the hostname
    You can retrieve the live instance host from the config/topology.txt file.

    Step 2: Upgrade the indexer first

    1. Login to the controlling server
    2. Get the current memory settings for the indexer processes: qserver, treebuilder, searchindexer, xmlloader, syncserver and syncclient: 
       bin/deployment-agent-client get-option <INSTANCE> <PROCESS_NAME>_memory
      Memory Settings
      Please use the gathered settings when recreating this instance, for further reference check Fredhopper Memory Settings
    3. Stop the indexer: 
      bin/instance <INSTANCE> stop
    4. Backup the existing configuration of the indexer instance: 
      bin/capture-export <INSTANCE> tmp/<INSTANCE>_fas_update.zip -c
      This will produce a zip file in the tmp directory that is later on needed.
    5. Download the requested FAS version from: https://extranet.fredhopper.com/fas/ into <BASE_DIRECTORY>/fredhopper-releases
    6. Rename the current Fredhopper installation with the "--force" parameter: 
      bin/deployment-agent-client rename-installation --force FAS FAS_original
      Please be aware that all instances on the current server attached to the installation will be switched off.
    7. Create a new installation of the name FAS using the new Fredhopper version: 
      bin/deployment-agent-client install --name FAS fredhopper-releases/FASX_Y_Z.zip
    8. Rename the instance with the "--force" parameter: 
      bin/deployment-agent-client rename-instance --force <INSTANCE> <INSTANCE>_original
    9. Recreate your instance on the required preset and base it on your newly installed "FAS" installation: 
      bin/deployment-agent-client create -I <PRESET> <INSTANCE> FAS
    10. Check if the instance <INSTANCE> has been created: 
      bin/deployment-agent-client list-instances
    11. Import the previously created cofiguration capture into the indexer instance: 
      bin/capture-import <INSTANCE> tmp/<INSTANCE>_fas_update.zip
    12. Update custom components: Install the correct versions of the custom components into data/instances/<INSTANCE>/custom
      Custom Component Compatibility
      It is usually not possible to use the custom components from the old instance in the new version of Fredhopper.
      Custom Configuration Files
      Some custom components require additional configuration files. When updating the components also ensure to provide correct configuration files. A typical example is the "space management" component, which uses the file data/instances/<INSTANCE>/config/space-management.xml
    13. Execute a reindex to load the data: 
      bin/reindex <INSTANCE>
      Indices are not compatible between FAS versions. Therefore the data needs to be reloaded
    14. Verify that instance is up and running: Access the preview pages through the browser.
    15. Go to merchandising studio and publish the config.
    16. Start the syncserver: 
      bin/deployment-agent-client invoke <INSTANCE> syncserver start

    Step 3: Upgrade every live instance one by one

    Upgrade one instance at a time
    If you execute this process on a high availability environment, ensure that you always completely finish the steps below on one instance before starting on the next one, as the shutdown of instances is required.
    1. Log in on the live instance server
    2. Find the qserver and syncclient processes memory settings: 
      bin/deployment-agent-client get-option <INSTANCE> <PROCESS>_memory

      This request will return you a value which will be referred to as <PROCESS_MEMORY> from here on.

      Additional settings
      If you manually changed additional settings, for example when configuring suggest, make sure to get these settings too.
    3. Download the requested FAS version from: https://extranet.fredhopper.com/fas/ into <BASE_DIRECTORY>/fredhopper-releases
    4. Stop the instance 
      bin/instance <INSTANCE> stop
    5. Rename the current Fredhopper installation with the "--force" parameter: 
      bin/deployment-agent-client rename-installation --force FAS FAS_original
      Please be aware that all instances on the current server attached to the installation will be switched off. In some Windows systems, it is not possible to use the rename-installation command. In this case, captures of all instances connected to the installation need to be created. Once done, the installation needs to be removed  (bin/deployment-agent-client remove-installation --force FAS) before it is recreated as described below.
    6. Create a new installation of the name FAS using the new Fredhopper version: 
      bin/deployment-agent-client install --name FAS fredhopper-releases/FASX_Y_Z.zip
    7. Rename the instance with the "--force" parameter: 
      bin/deployment-agent-client rename-instance --force <INSTANCE> <INSTANCE>_original
    8. Recreate your instance on the required preset and base it on your newly installed "FAS" installation: 
      bin/deployment-agent-client create -I <PRESET> <INSTANCE> FAS
    9. Set the syncserver port this instance should connect to: 
      bin/deployment-agent-client set-option <INSTANCE> syncclient_serverport=<SYNCSERVER_PORT>
    10. Set the syncserver host this instance should connect to: 
      bin/deployment-agent-client set-option <INSTANCE> syncclient_server=<SYNCSERVER_HOST>
    11. Reuse the memory setting from the original instance: 
      bin/deployment-agent-client set-option <INSTANCE> <PROCESS>_memory=<PROCESS_MEMORY>
      Additional settings
      If you manually changed additional settings, for example when configuring suggest, make sure to set these settings too.
    12. Check if the values were set correctly: 
      bin/deployment-agent-client describe-instance <INSTANCE>
    13. Set the role of the server to be "live": 
      bin/deployment-agent-client add-role <INSTANCE> http://localhost:8177/static/live.xml
    14. Verify that the role was set correctly: 
      bin/deployment-agent-client list-roles <INSTANCE>
    15. Update custom components: Install the correct versions of the custom components into data/instances/<INSTANCE>/custom
      Custom Component Compatibility
      It is usually not possible to use the custom components from the old instance in the new version of Fredhopper.
      Custom Configuration Files
      Some custom components require additional configuration files. When updating the components also ensure to provide correct configuration files. A typical example is the "space management" component, which uses the file data/instances/<INSTANCE>/config/space-management.xml
    16. Start the syncclient process of the instance: 
      bin/deployment-agent-client invoke <INSTANCE> syncclient start
    17. Start the qserver process of the instance in live mode: 
      bin/deployment-agent-client invoke <INSTANCE> qserver start -Drole=live
    18. Verify that instance is up and running: Access the preview pages through the browser.

    Step 4: Clean up each server

    Verify your environment first
    By executing the process described in this step, you will remove the ability to roll back to the old Fredhopper version quickly
    1. Log in on the server
    2. Delete the original installation with the "--force" parameter: 
      bin/deployment-agent-client remove-installation --force FAS_original
      Please be aware that all instances on the current server attached to the installation will also be deleted.

    Troubleshooting

    Restore your environment to the old Fredhopper version

    If you require to restore your old environment and have not yet cleaned up the servers you can execute the following steps on each server to revert:

    1. Rename the current Fredhopper installation with the "--force" parameter: 
      bin/deployment-agent-client rename-installation --force FAS FAS_new
    2. Rename the instance with the "--force" parameter: 
      bin/deployment-agent-client rename-instance --force <INSTANCE> <INSTANCE>_new
    3. Rename the current Fredhopper installation with the "--force" parameter: 
      bin/deployment-agent-client rename-installation --force FAS_original FAS
    4. Rename the instance with the "--force" parameter: 
      bin/deployment-agent-client rename-instance --force <INSTANCE>_original <INSTANCE>

    On the indexer server, execute then the following commands for the indexer instance

    1. Execute a reindex to load the data: 
      bin/reindex <INSTANCE>
    2. Push the data to all live instances:: 
      bin/fresh-index-to-live <INSTANCE>
    Restore after cleanup
    If you already cleaned up your server, follow steps 1 through 3 on this page but do not make a new capture - use the original capture you made when first upgrading.
    Fredhopper configurations can migrated upwards, but are not guaranteed to be downwards compatible.

    Comments

    0 comments

    Please sign in to leave a comment.