These pages contain important information about upgrading between FAS versions. See the child pages for version-specific notes.

Upgrade with Fredhopper Deployment Package
The Fredhopper Deployment Package can be used for simplifying a FAS deployment. The instructions below are mostly intended for a stand-alone deployment, and the deployment package instructions will be linked in note boxes similar to this one.

Please see Upgrading for general upgrade instructions specific to the Fredhopper Deployment Package.

Upgrade Notes Glossary

Prerequisites

Starting with FAS 7.2 the use of the Fredhopper Deployment Agent is required for all production deployments.

The upgrade procedure of FAS is a complex task, and any upgrade should be planned carefully. In particular make sure to review the release notes of the version you're upgrading to, and all release notes of intermediate versions. Upgrades across multiple major versions are not explicitly supported, and you should contact Fredhopper if you want to execute such upgrades.

Additional Modules
FAS can be extended with additional modules such as Fredhopper Suggest Search. These modules will require matching updates when updating the Fredhopper FAS version.

Steps

Step 1: Upgrade Deployment Agent

Every FAS version requires a matching deployment-agent version. Installations using earlier versions of the deployment agent will require an upgrade. You can check the version of your deployment agent by pointing your browser to http://<host>:8177. The version is specified as variable deployment-core.version.

FAS Version	Minimum Required Deployment Agent version
7.2	1.1-beta-2
7.5	1.1-beta-6

Fredhopper Deployment Package
Please follow Upgrade the Deployment Agent included in the platform to upgrade the deployment agent installed in the deployment package.

Upgrading the deployment agent is done in the following steps:

Note down the base deployment data directory
Shutdown all running processes

Stop the deployment agent

bin/deployment-agent-client stop-agent --force

Install the new deployment agent by unzipping the distribution archive
```
unzip deployment-agent-distribution-1.1-beta-6.zip
```

Start the new deployment from the installation directory using

bin/deployment-agent --directory /directory/of/step/1 [additional options]

Start all processes

Step 2: Upgrade FAS

Fredhopper Deployment Package
Please see Upgrade the Fredhopper version included in the deployment package for additional instructions when upgrading FAS included in the Fredhopper Deployment Package.

The deployment agent will take care of executing required migration steps. When upgrading a cluster of multiple FAS instances you will need to upgrade each instance separately. While the upgrade is ongoing all replication processes (syncserver and syncclient) must be stopped.

Please make sure to review the FAS version specific notes below before starting the upgrade to avoid common issues.

The instructions below assume that the FAS instance to upgrade is called 'INSTANCE'. Adjust the commands to match your environment accordingly.

Install the new FAS version in the deployment agent

bin/deployment-agent-client create-installation --name FAS7_5_0 /path/to/fas-assembly-7.5.0.zip

Rename the old instance (this will stop all processes of the instance automatically)
```
bin/deployment-agent-client rename-instance --force INSTANCE INSTANCE.old
```

Create a new instance using the settings of the old instance

Determine the preset of the old instance
```
bin/deployment-agent-client describe-instance INSTANCE.old
```
This will print all instance settings as key=value pairs. The preset is printed under the key "preset", for example preset=2.

Create the new instance using the same preset

bin/deployment-agent-client create-instance --preset PRESET INSTANCE FAS7_5_0

Import capture from the old instance

bin/deployment-agent-client import-capture INSTANCE http://localhost:8177/instance/INSTANCE.old/capture?include=config

Configure replication ports and memory settings to match the old instance
You need to copy the value of the following settings of the old instance if you modified the defaults:

Setting	Description
syncclient_server	Hostname/IP address of the syncserver that the syncclient should connect to
syncclient_serverport	Port on which the syncclient will connect to the syncserver
syncserver_serverport	Port on which the syncserver is listening for requests
qserver_memory	Memory assigned to the qserver
xmlloader_memory	Memory assigned to the xmlloader
treebuilder_memory	Memory assigned to the treebuilder
searchindexer_memory	Memory assigned to the searchindexer
syncserver_memory	Memory assigned to the syncserver
syncclient_memory	Memory assigned to the syncclient

Use bin/deployment-agent-client get-option INSTANCE.old SETTING to determine the value of the setting in the old instance, and use bin/deployment-agent-client set-option INSTANCE SETTING=VALUE to configure the setting in the new instance.

Review system settings of the new instance
Use bin/deployment-agent-client describe-instance INSTANCE to show all settings, and then bin/deployment-agent-client set-option INSTANCE KEY=VALUE to modify values if needed.

The options shown will also contain the settings from config/system.xml. You should always use the set-option deployment agent command to modify config/system.xml.

Review and migrate locally modified configuration files in the new instance
config/log4j.xml, config/log4j-cmdline.xml and other logging configuration files should be removed so that the defaults are used.

The logging configuration of FAS might change with each version, and keeping old logging configuration from previous versions may prevent important information from getting logged.

If you have applied local changes to the logging configuration you should re-generate the logging configuration config/log4j.xml, config/log4j-cmdline.xml and other config/log4j*xml based on the versions in the etc directory inside the FAS distribution.

Install custom components if required

Custom Components
Custom components are used to extend the functionality of FAS for special use cases. These components are provided by the technical consultant, and are always specific to a particular FAS version. Custom components extend/implement internal interfaces that may change with each FAS version (even minor releases), and if a component is not available for a particular FAS version you should file a request in JIRA to provide the custom component for the new FAS version and additional instructions needed when upgrading.

New FAS versions may make existing custom components obsolete, or provide better general solutions to use cases that required a custom component.

When upgrading you should review carefully which custom components are really needed, and remove the components that are no longer needed.

(Indexer instances only) Import input XML

Upgrades of FAS require reindexing of the input XML in all cases.
Start all required processes