Migrating from JetPatch 4.2.8 Monolithic Deployment to JetPatch 5.0 Microservices

1. Purpose and Goals

This guide provides a structured plan to migrate from the monolithic JetPatch 4.2.8 deployment to the Docker-based microservices architecture introduced in JetPatch 5.0.

Migration Objectives

• Transition from monolith to containerized microservices.

• Preserve configuration, data, SSL certificates, and integrations

2. Pre-Migration Requirements

2.1 Infrastructure & Compatibility

3. Migration Steps

3.1 Create a New Connector Service

Set up a new Connector Service (via the JetPatch UI) using the existing 4.2.x connector images.

Steps:

1. Navigate to:
   Agents → Managed Agents → JetPatch → Services

2. Create a new Connector Service (do not edit the existing one).

3. Configure the connector URLs in the new service:

    

   • Primary URL → Use the future 5.0 server address that endpoints should connect to after the upgrade.

     https://<Planned_5.0_Server_IP>:8443

   • Secondary URL → Keep the current 4.2.x server address so endpoints remain connected until migration is complete.

     https://<Current_4.2.x_Server_IP>/vmanage-server/

4. When the Copy Service window pops up, select the current URL as the primary URL.

Note:

At this stage, the JetPatch 5.0 server has not yet been migrated. This Connector Service is created in advance to prepare for the migration. Its purpose is to allow existing connectors to stay connected to the current 4.2.x server (via the Secondary URL) while also being ready to connect to the upcoming 5.0 server (via the Primary URL) once the migration is complete.

3.2 Reconfigure Endpoints

To connect clients to the new Connector Service (and prepare them for the 5.0 migration):

1. Navigate to:
   Platform Configuration → Servers

2. Select the clients that need to be reconfigured.

3. Go to:
   Server Actions → Manage Intigua on Server

4. In the pop-up window:

   • Enable the checkbox Manage Intigua on Server

   • Select the newly created connector service (from step 3.1)

   • Click Apply

Behavior after reconfiguration:

• Clients will continue to stay connected to the existing 4.2.x server via the Secondary URL.

• Once the JetPatch 5.0 server is migrated and becomes available, clients will automatically switch over to the Primary URL (5.0 server) without additional manual changes

3.3 Switch to Elevated Privileges

Run the following to elevate to root (or a sudo-enabled account):

sudo su

This switches the current user to a root shell (superuser), giving unrestricted system access.

You can now execute privileged commands without typing sudo before each one.

3.4 Stop and Disable NGINX (Free Ports 80/443)

In JetPatch 5.0, microservices expose services via Docker containers, often binding to port 80 (HTTP) and 443 (HTTPS).
If an existing NGINX service is running (typically used in the 4.2.8 monolith or other apps), it may conflict with these ports and prevent the containers from starting.

systemctl stop nginx 
systemctl disable nginx
systemctl status nginx

3.5 Stop and Disable Tomcat (Free Ports 8080/9090)

JetPatch 4.2.8 uses Apache Tomcat to serve the application (usually on ports 8080 and 9090).
Since the new JetPatch 5.0 runs in Docker containers and may use these same ports, the legacy Tomcat service must be shut down to avoid port binding conflicts.

systemctl stop tomcat
systemctl disable tomcat
systemctl status tomcat

3.6 Unzip the Deployment Package

Deployment package should already be downloaded from the FTP or repository link provided by JetPatch.

1. Download the deployment package to /home or any path

  2. untar the files

tar -xvzf jetpatch-deploy-5.0-59.tar.gz

After extraction, this structure will appear:

/root/jetpatch-deploy-5.0-59/
├── bin/                  # Helper scripts
├── compose/              # Docker Compose YAMLs
├── config/               # .env, service-vars.env, config templates

3.7 Repository Configuration in .env File

Before running the environment validation or deployment, ensure that the .env file located in the config/ directory is properly configured. This file defines critical environment variables used during the installation process, including the Docker image repository for pulling JetPatch services.

Key Fields to Review in .env

Open the .env file:

for example:

cd /root/jetpatch-deploy-5.0-59/config/
ls -la
vi .env

Ensure the following variables are correctly set:

# Docker image registry location
REPOSITORY=public.ecr.aws/xxxxxxxx/jetpatch/

# JetPatch service versions
MAIN_VERSION=5.0.248
WORKER_VERSION=5.0.248

Explanation of Variables

3.8 Make all script files executable :

go to the downloaded deployment package path and give the executable permission to all files

for example

cd /root/jetpatch-deploy-5.0-59/
chmod +x ./bin/*

3.9 Configuring DB's When Databases Are on Separate Servers

use the below link for the steps to follow:
Configuring DB's When Databases Are on Separate Servers

Additional Requirement: When Databases Are on Two Different Machines

If IntiguaDB and PatchRepositoryDB are hosted on two separate database servers, ensure the below 3.10 step  is completed on both database machines:

3.10 PostgreSQL Database Configuration for Container Access

In JetPatch Microservices architecture, each service runs in its own isolated Docker container.

Although PostgreSQL may already be installed on the host system, containers access it over the host network — not through localhost from within the container. This means PostgreSQL must be explicitly configured to allow remote connections, even from the same machine using either the host IP (e.g., 192.168.x.x) or the Docker bridge network (172.x.x.x).

3.10.1 Configure postgresql.conf to Listen on Host IP

Edit the PostgreSQL configuration file:

vi /var/lib/pgsql/16/data/postgresql.conf

Locate and update the following line:

listen_addresses = 'HostIP' # for ex: ip of Jetpatch Server(10.0.10.11)
port = 5432

This ensures PostgreSQL accepts connections from any reachable network interface — not just localhost.

3.10.2 Configure pg_hba.conf to Allow MD5 Authentication

Edit the PostgreSQL authentication configuration:

vi /var/lib/pgsql/16/data/pg_hba.conf

Edit the following lines to allow incoming authenticated connections from containers:

# Allow connections from Docker containers (IPv4)
host    all             all             0.0.0.0/0               md5

These settings enable password-based (MD5) authentication for any host IP — which is essential for Docker containers to connect to the database.

3.10.3 Restart PostgreSQL for Changes to Take Effect

Run the following command to reload the configuration:

systemctl restart postgresql-16

Summary

4. Deploy Microservices

As part of the migration from JetPatch 4.2.8 (monolithic) to 5.0 (microservices), you must transfer critical configuration files, executables, packages, and certificates to new directory structures expected by the microservices architecture.

JetPatch provides an automated migrate_monolith_to_microservices.sh script for this purpose.

Note:
If your environment uses SSL certificates, follow sections 4.1 to 4.3.
If SSL certificates are not used, skip directly to section 4.4.
The verification steps in section 4.4 apply to both SSL and non-SSL environments.

4.1 Option A – Use --config Environment File (Recommended) (SSL environments)

Use this option when SSL certificates are stored in custom locations or when you prefer not to edit the migration script directly.

This is the preferred and recommended approach for most customer environments.

4.1.1 Create Configuration File for Certificate Overrides

Create a configuration file in KEY=VALUE format to define certificate locations and filenames.

cat > /root/migrate.env <<'EOF'
CERT_CRT_SRC_DIR=/opt/customer/tls/public
CERT_CRT_SRC_FILE=mycompany_tls_cert.pem
CERT_KEY_SRC_DIR=/opt/customer/tls/private
CERT_KEY_SRC_FILE=mycompany_tls_key.pem
EOF

Ensure the paths and filenames exactly match the customer environment.

4.1.2 Validate Configuration

Run the migration script in validation mode using the configuration file:

navigate to /root/jetpatch-deploy-5.0-59/bin/ and then run the below command

./migrate_monolith_to_microservices.sh --validate-only --config /root/migrate.env

This step verifies:

• Certificate files exist and are readable

• Paths and filenames are correct

• Migration can proceed safely

No files are copied or modified during validation.

4.1.3 Run Migration Using Configuration File

Once validation succeeds, run the migration using the same configuration file:

./migrate_monolith_to_microservices.sh --config /root/migrate.env

The script will copy and normalize certificates to:

• intigua.crt

• intigua.key

and place them in all required JetPatch 5.0 directories.

Note: Ensure the same --config file used during validation is also used during migration.

4.2 Option B – Edit Script Defaults (Manual) (SSL environments)

Use this option when SSL certificates already exist on the system and you want to hardcode their paths and filenames directly in the migration script.

This option should be used only when configuration files cannot be externalized.

This approach is suitable when:

• Certificate paths are stable

• You are comfortable editing the script

• No external config file is required

4.2.1 Identify Certificate Locations

Determine the exact directories and filenames where the SSL certificate and private key are stored.

The certificate and key can have any filename (they are not required to be named intigua.crt or intigua.key).
Use the actual existing filenames and reference the same names in section 4.2.2.

Example:

Certificate directory:

/etc/nginx/intigua-sslcert

Certificate file (example):

mycompany_tls_cert.pem

Key file (example):

mycompany_tls_key.pem

Ensure the files are readable by the user running the migration.

4.2.2 Edit Migration Script Defaults

Open the migration script:

navigate to /root/jetpatch-deploy-5.0-59/bin/ and edit the below file

vi migrate_monolith_to_microservices.sh

At the top of the script, update the certificate default variables to match the environment:

CERT_CRT_SRC_DIR_DEFAULT="/etc/nginx/intigua-sslcert"
CERT_CRT_SRC_FILE_DEFAULT="mycompany_tls_cert.pem"

CERT_KEY_SRC_DIR_DEFAULT="/etc/nginx/intigua-sslcert"
CERT_KEY_SRC_FILE_DEFAULT="mycompany_tls_key.pem"

Save and exit the file.

4.2.3 Validate Configuration

navigate to  /root/jetpatch-deploy-5.0-59/bin/ and then 
Run the migration script in validation mode:

./migrate_monolith_to_microservices.sh --validate-only

This step verifies:

• Certificate files exist and are readable

• Paths and filenames are correct

• Migration prerequisites are satisfied

No files are copied or modified during validation.

navigate to  /root/jetpatch-deploy-5.0-59/bin/ and 

Run the following script to ensure that the SSL certificates are copied into the Java truststore:

./ensure_truststore.sh

Expected output:

Trust this certificate? [no]: Certificate was added to keystore

If this step is skipped, or if the certificate files are missing, the script will fail with a missing certificate files error during runtime.

4.2.4 Run the Migration Script 

navigate to  /root/jetpatch-deploy-5.0-59/bin/ and then 

Run the migration script after completing the validation

./migrate_monolith_to_microservices.sh

4.3 SSL Certificate Verification (SSL environments only)

After migration, verify that SSL certificates are present in both required locations:

ls -l /usr/share/intigua/services/data/intigua-main/sslcert/
ls -l /usr/share/intigua/services/data/certs/files/

Both directories must contain:

• intigua.crt

• intigua.key

Missing or incorrect SSL certificates may result in browser SSL / HSTS access failures to the Web UI.

navigate to  /root/jetpatch-deploy-5.0-59/bin/ and then 

Run the following script to ensure that the SSL certificates are copied into the Java truststore:

./ensure_truststore.sh

Expected output:

Trust this certificate? [no]: Certificate was added to keystore

If this step is skipped, or if the certificate files are missing, the script will fail with a missing certificate files error during runtime.

4.4 Run the Migration Script (Applicable only for non-SSL environments)

navigate to /root/jetpatch-deploy-5.0-59/bin/ and then 
Run the migration script after completing Option A or Option B (for SSL environments), or directly if SSL is not used:

./migrate_monolith_to_microservices.sh

What the Script Does

• Copies essential files from the legacy monolithic setup (usually under /usr/share/intigua/) into the appropriate 5.0 microservices structure (/usr/share/intigua/services/data/)

• Preserves file permissions and paths

• Ensures consistency for critical components such as agents, package files, service configuration, and SSL certificates (if applicable)

4.5 Post-Migration: Verify File Locations (Applicable to all environments)

Verify that files have been correctly migrated to the following locations:

Important Notes

If the destination folders already contained older versions of files, .new files will be created (for example, intigua.properties.new) and must be manually reviewed and merged before finalizing the deployment.

These files are critical for the correct behavior of the microservices and agent communication.

4.6 Modify DB Connection in intigua.properties

During the upgrade, services must connect to PostgreSQL using the host IP address, not localhost.
If it localhost:5432 is used, containers will fail to reach the database.

Steps:

1. Open the configuration file:

   vi /usr/share/intigua/services/data/intigua-main/conf/intigua.properties

2. Locate the database connection string:

   jdbc:postgresql://localhost:5432/intiguadb

3. Replace localhost with the actual HOST_IP

   jdbc:postgresql://<HOST_IP>:5432/intiguadb #for ex: ip of Jetpatch Server(10.0.10.11)

4. Save and exit.

4.7 Run Validation Script (./install.sh --validate)

Before modifying any configuration, it is recommended to run the validation step provided by the installer script:

./install.sh --validate

Purpose:

• Performs an environment validation to check prerequisites such as OS compatibility, required packages, and available resources (CPU, memory, and disk space).

• Ensures that the system is properly set up before applying configuration changes.

• Prevents deployment errors during migration.

Output & Logs:

• The script prints INFO and ERROR messages directly to the console.

• Users should carefully review these messages to confirm all checks have passed.

• If any ERROR appears, it must be resolved before continuing to the next step.

4.8 Initial Deployment

After verifying that all files have been copied to the correct locations, you can proceed with deploying the JetPatch microservices.

JetPatch Microservices Installer – install.sh Usage

Execute the following command to begin the deployment process:

./install.sh --auto

This script performs the following actions:

• Validates your environment setup

• Protects existing configuration files by creating .new versions if conflicts exist

• Builds and applies SSL certificates

• Initializes and verifies required PostgreSQL databases

• Deploys core services, worker services, and runtime components via Docker containers

This step may take several minutes to complete, depending on system performance and download speeds.

4.9 Check and Merge Any Files as Needed

During the migration or initial deployment, the installer script is designed to protect existing files by not overwriting them silently. If it detects that a file already exists in the target directory, it will:

• Skip overwriting the original file

• Create a .new version of the file instead

• Prompt you with a message indicating manual review is required

Why This Happens

To prevent accidental loss of custom configurations, scripts, or binaries from an earlier version (e.g., 4.2.8), the system takes a conservative approach:

For example:

• Existing file: intigua.properties, log4j2.xml, *.conf.json

• New version from the deployment package: intigua.properties.new,log4j2.xml.new,*.conf.json.new

You now have both files and must compare/merge them manually before proceeding.

4.10 Finalize Deployment

After merging all .new files and cleaning up:

Finalize and Commit Configuration

./install.sh --finalize

This will:

• Record hash signatures of final configuration files

• Register and re-deploy all containers with confidence

• Complete the deployment

This flow ensures your existing configuration is preserved and your new JetPatch microservices deployment is fully aligned with production standards.

5. Post-Migration Validation

Once the JetPatch microservices are deployed and finalized, it's important to validate that all services are running correctly and behaving as expected.

Below are the key steps to verify your deployment:

5.1. Check Running Docker Containers

Ensure all JetPatch microservices are up and running:

docker ps

You should see containers like (10 total):

• log-collector  
• javamelody-collector
• jp-rabbitmq

Each container should show a status like Up X minutes.

If any of the containers are not started, then docker start container-id or do install --refresh

5.2. Check Individual Container Logs

Inspect the logs of any specific container to confirm successful startup or troubleshoot issues:

docker logs <container-name>

Examples:

docker logs log-collector

Look for:

• “Started Successfully” or similar boot messages

• Errors related to DB connectivity, configuration, or file paths

5.3. View JetPatch Application Logs

Application-specific logs are written to the following host directory:

/usr/share/intigua/services/data/logs/

You can tail, cat, or less These log files to inspect service behavior:

tail -n 100 /usr/share/intigua/services/data/logs/intigua-main.log

5.4. Access Container Shell and View Environment Variables

To check inside a running container (e.g., to validate environment variables injected from .env or service-vars.env):

1. Enter a container's shell:

   docker exec -it <container-name> /bin/sh

2. Print environment variables:

   printenv

Look for key variables like:

• INTIGUA_DOCKER_HOST

• INTIGUA_MAIN_SERVICE_HOST

• DB_URL, DB_USERNAME, etc.

5.5. Re-Assign Service Accounts

1. Navigate to:
   Platform Configuration → Settings → Service Accounts → Edit Credentials

2. Add or update the domain group account credentials.

   1. A domain group account is typically used for both Windows and Linux endpoints, ensuring centralized authentication and policy enforcement.

   2. This eliminates the need to manage local accounts or individual passwords.

3. Ensure the account has the required privileges for Connector installation, upgrade, and management on all endpoints.

4. Click Save to apply the changes.

5.6 Upgrade Endpoint Connectors to 5.0.x

1. Navigate to:
   Platform Configuration → Servers

2. Select the endpoints that need to be upgraded.

3. Go to:
   Server Actions → Manage Intigua on Server

4. In the pop-up window:

   • Enable the checkbox Manage Intigua on Server.

   • Select the 5.0 Connector Service.

   • Click Apply.

5. The selected endpoints will:

   • Upgrade to 5.0.x Connector installer.

5.7. Validate Web UI and API

After container validation:

• Access the JetPatch UI in your browser:

  https://<host-ip>:<port>

• Log in and confirm that:

  • The dashboard loads

  • Endpoints and connectors are visible

  • Service accounts and patch settings are intact
     

6. Common Issues