JetPatch 5.X Upgrade Guide (Example: 5.1.60 → 5.1.63)

1. Overview

The --upgrade mode enables safe, non-intrusive updates on running JetPatch microservice stacks.
It minimizes risk by skipping installation-time validations and only redeploys services when configuration drift is not detected.

2. Upgrade Flow

Skipped During Upgrade

• Prerequisite installs

• Environment validation

• SSL/keystore/truststore builds

• Database ensure

Executed During Upgrade

• Configuration synchronization using MD5 + .new drift detection

• Image pulls with retry/backoff

• Service redeployment (only if no drift is detected)

3. Pre-Upgrade Configuration

3.1 Repository Configuration in .env File

Navigate to the extracted deployment directory and edit .env file.

for example:

cd /root/jetpatch-deploy-5.X-XX/config/
ls -la
vi .env

Before running the upgrade, update the .env file located in the config/ directory.
This file defines critical environment variables, including the Docker image repository and service versions.

Ensure the following variables are correctly set:

for example:

# Docker image registry location
REPOSITORY=public.ecr.aws/xxxxxxxx/jetpatch/
# JetPatch service versions
MAIN_VERSION=5.1.xxx   # get the version details from JETPATCH
WORKER_VERSION=5.1.xxx # get the version details from JETPATCH
.............

Explanation of Variables

4. Upgrade Behavior

4.1 Running Upgrade

Navigate to the extracted deployment package and edit .env file.

for example:

cd /root/jetpatch-deploy-5.X-XX/bin/

Run the below command to upgrade 5.0

# Run safe upgrade
./install.sh --upgrade  

On Drift Detected

• .new files are generated (e.g., docker-compose.override.yml.new)

• Affected files are listed in logs

• Action required: Compare changes and merge manually:

diff docker-compose.override.yml docker-compose.override.yml.new
vi docker-compose.override.yml   # apply changes as needed

Once resolved, continue with --finalize.

4.2 Finalizing Upgrade

After resolving drift and merging .new files:

./install.sh --finalize

This pulls the updated images and completes the upgrade to the new version specified in .env.

5. Compatibility & Risk

• Backward compatible: Existing flags (--install, --refresh,  --validate, --finalize) remain unchanged.

• Non-disruptive: No SSL or DB changes during upgrade.