How to Upgrade Oxygen Feedback to a New Version

Prerequisites

Docker and Docker Compose are required. See the official installation documentation.

Consider the current Linux user to be feedback.

Upgrade

To upgrade Oxygen Feedback Enterprise to a new version on Linux, follow this procedure:

Note:

$OLD_OXYGEN_FEEDBACK_INSTALL_DIR refers to the path of the directory where the current version of Oxygen Feedback Enterprise is installed.

Stop the current Oxygen Feedback instance - Stop the containers running the Oxygen Feedback Service and Oxygen Text Search Service:
```
cd $OLD_OXYGEN_FEEDBACK_INSTALL_DIR
docker compose down
```
Backup the Installation Directory - Create a backup of the current installation directory to ensure you can restore it if needed.
Backup the Databases - Backup the databases used by the Oxygen Feedback Service and Oxygen Text Search Service.
- For MySQL, see: https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html.
- For PostgreSQL, see: https://www.postgresql.org/docs/14/app-pg-dumpall.html.
Download the New Version - Create a directory for the new version (e.g. /home/feedback/oxygen-feedback-download) and navigate to it:
```
mkdir -p /home/feedback/oxygen-feedback-download
cd /home/feedback/oxygen-feedback-download
```
Download the latest Oxygen Feedback Enterprise installation kit:
```
wget https://www.oxygenxml.com/InstData/Feedback/oxygen-feedback-enterprise.zip
```
Extract the Installation Kit - Extract the content of the downloaded archive to the user's home directory:
```
unzip oxygen-feedback-enterprise.zip -d /home/feedback
```
The extracted folder (e.g. oxygen-feedback-5.1) becomes the installation directory for the new version:
```
export NEW_OXYGEN_FEEDBACK_INSTALL_DIR=/home/feedback/oxygen-feedback-5.1
sudo chown feedback: $NEW_OXYGEN_FEEDBACK_INSTALL_DIR
```
Update docker-compose.yml - Compare the docker-compose.yml files from the old and new installations. Update the new file based on the configuration in the old file, considering any updates or changes in the new version and make sure you read the information in the following note.
Important:
Starting with version 5.4, the Oxygen Text Search Service was renamed to Oxygen Feedback Text Search Service to align with the naming convention of the other Oxygen Feedback modules.

As a result of this rename, the docker-compose.yml file included in the Oxygen Feedback distribution package contains the following changes for the Text Search Service container that you must account for when updating it:
- The Docker image name changed from oxygenxml/oxygen-text-search-service to oxygenxml/oxygen-feedback-text-search-service.
- The container name changed from oxygen-text-search-service to oxygen-feedback-text-search-service.
- The volume mount target paths inside the container changed from /oxygen-text-search-service/workspace/ and /oxygen-text-search-service/logs/ to /oxygen-feedback-text-search-service/workspace/ and /oxygen-feedback-text-search-service/logs/.
The source paths on the host machine (./workspace and ./logs) are unchanged. No data needs to be moved.
The relevant section of the updated docker-compose.yml file looks like this:
text-search-service: image: oxygenxml/oxygen-feedback-text-search-service:<version> container_name: oxygen-feedback-text-search-service ... volumes: - type: bind source: ./workspace target: /oxygen-feedback-text-search-service/workspace/ - type: bind source: ./logs target: /oxygen-feedback-text-search-service/logs/
Update Configuration Files - Update the properties files in [NEW_OXYGEN_FEEDBACK_INSTALL_DIR]/oxygen-feedback-home/config using the data from [OLD_OXYGEN_FEEDBACK_INSTALL_DIR]/oxygen-feedback-home/config.

Perform a directory diff comparison to identify changes and merge necessary properties. Refer to the Oxygen Feedback Installation - Step 6: Configure Oxygen Feedback for details.

Copy Data Folders:

Copy the data folder from the old installation:

cp -r $OLD_OXYGEN_FEEDBACK_INSTALL_DIR/oxygen-feedback-home/data $NEW_OXYGEN_FEEDBACK_INSTALL_DIR/oxygen-feedback-home/data

Copy the workspace folder:

cp -r $OLD_OXYGEN_FEEDBACK_INSTALL_DIR/workspace $NEW_OXYGEN_FEEDBACK_INSTALL_DIR/workspace

Copy License Key - Copy the licensekey.txt file from the old installation:

cp $OLD_OXYGEN_FEEDBACK_INSTALL_DIR/oxygen-feedback-home/licensekey.txt $NEW_OXYGEN_FEEDBACK_INSTALL_DIR/oxygen-feedback-home/

MySQL JDBC Driver (if applicable) - If using MySQL for the Oxygen Feedback Service, copy the MySQL JDBC driver to the new installation:
```
cp $OLD_OXYGEN_FEEDBACK_INSTALL_DIR/lib/mysql-connector-java*.jar $NEW_OXYGEN_FEEDBACK_INSTALL_DIR/lib/
```
Load Docker Images - Load the Docker images for the Oxygen Feedback Service and Oxygen Text Search Service:
```
cd $NEW_OXYGEN_FEEDBACK_INSTALL_DIR/docker-images
sh load-docker-images.sh
```

Start the New Version - Start Oxygen Feedback Enterprise:

cd $NEW_OXYGEN_FEEDBACK_INSTALL_DIR
docker-compose up -d

Verification

Once the services are up and running, verify that the new version is functioning correctly by accessing the application and checking logs for any errors.

Upgrading reCAPTCHA from v2 to v3

The reCAPTCHA v2 and v3 site/secret key pairs are not interchangeable. Thus, existing v2 keys will stop working after upgrading Feedback. New keys must be generated and deployed before restarting the application.

Generate new reCAPTCHA v3 keys - Go to https://www.google.com/recaptcha/admin and sign in with the Google account that owns the existing reCAPTCHA registration.

Update the properties file - Open ${FEEDBACK_HOME}/config/feedback-recaptcha.properties and replace the existing key values:

# Replace these with the new v3 keys obtained in step 1
  google.recaptcha.key.site=<your-new-v3-site-key>
  google.recaptcha.key.secret=<your-new-v3-secret-key>

Set the score threshold (optional) - The google.recaptcha.score.threshold property controls the minimum acceptable risk score. Add it to the same file if you want a value other than the default:
```
# Minimum acceptable reCAPTCHA v3 score. Range: 0.0 (allow all) to 1.0 (block all).
  # Default: 0.5 — this value is used automatically if the property is absent.
  google.recaptcha.score.threshold=0.5
```
Scores closer to 1.0 indicate a higher confidence that the interaction is human. Scores closer to 0.0 indicate likely bot traffic. Start with the default 0.5 and adjust it based on observed scores in the application logs.