How to Upgrade the SKYVVA Agent on a Linux Server?

1. Overview

This guide explains how to upgrade an existing SKYVVA Integration Agent on a Linux server. The upgrade uses a new Linux installation package while preserving the existing database connection, Agent configuration, and service settings.

The installer verifies the existing PostgreSQL connection, stops the current Agent service, updates the application files, database migrations, configuration properties, and systemd service, and then starts and verifies the upgraded Agent.

1.1 Upgrade Process Diagram

Figure 1: SKYVVA Agent upgrade process on a Linux server

Important: Before selecting Upgrade, make sure you know the current Agent installation folder.

If the installer cannot automatically detect the existing Agent installation during the upgrade, you must manually enter the full absolute installation path.

Example:
/opt/skyvva-agent-9055

2. Upgrade Prerequisites

Before starting the upgrade, confirm all prerequisites below. These checks reduce interruption risk and ensure that the installer can access the existing Agent and database configuration.

1. Have the new-version Linux installation package ready. Example: Agent-Linux-Installation-3-06-09.zip.

2. Stop all processing during the upgrade window. Stop inbound and outbound integrations, schedules, and manual processing before the upgrade begins.

3. Ensure PostgreSQL is running and accessible. The installer must verify the existing database connection before it can continue.

4. Know the existing Agent installation folder. Prepare the full absolute path, for example: /opt/skyvva-agent-9055.

3. Download the Latest Linux Agent Package

You can download the SKYVVA Agent Linux installation package using the link below:

https://help.skyvva.com/#article/new-agent-3-06-09-patch-1-download-link

Click the Download Link in the For Linux section. You will be redirected to Google Drive, where you can download the SKYVVA Agent Linux installation package.

Agent-Linux-Installation-x-xx-xx.zip

Note: Always use the official SKYVVA download page or the download link provided by SKYVVA Support.

4. Copy the Upgrade Package to the Linux Server

Script Summary

# Example using SCP from your local machine
scp -i ~/.ssh/id_xxxxxxxx /folderpath/Agent-Linux-Installation-x-xx-xx.zip username@<linux-server-ip>:/tmp/
   
# Example using SFTP
sftp username@<linux-server-ip>
put Agent-Linux-Installation-x-xx-xx.zip /tmp/
exit

After downloading the SKYVVA Agent Linux installation package to your local computer, copy the ZIP file to the target Linux server.

Example local download folder on macOS:

/Users/deabdahuy-sk-backup-pc/Downloads

You can use SCP or SFTP to transfer the package securely. Before running the command, confirm the local file location, Linux server IP address, login username, SSH key path, and destination folder.

Example destination folder on the Linux server:

/home/ubuntu/Agent-Installer

Example: Copy the Agent installation package to the Linux server using SCP:

scp -i ~/.ssh/id_ed25519 /Users/deabdahuy-sk-backup-pc/Downloads/Agent-Linux-Installation-3-06-09.zip ubuntu@32.236.220.72:/home/ubuntu/Agent-Installer  Enter passphrase for key '/Users/deabdahuy-sk-backup-pc/.ssh/id_ed25519':

Wait until the file transfer is complete. Then connect to the Linux server and verify that the ZIP file exists in the destination folder before continuing.

ssh ubuntu@<linux-server-ip>  
cd /home/ubuntu/Agent-Installer
ls

5. Identify the Existing Agent Installation Folder

Before selecting Upgrade, you must know the full path of the current SKYVVA Agent installation. The path must be an absolute Linux path beginning with /.

Example existing installation path: /opt/skyvva-agent-9055

By default, the SKYVVA Agent is installed under the /opt directory. To find possible existing Agent installation folders in the default location, run:

sudo find /opt -maxdepth 1 -type d -name 'skyvva-agent*' -print

This command displays folders under /opt whose names begin with skyvva-agent.

Important: Enter the path of the existing installed Agent, not the path of the new installer package.

6. Extract the New Agent Package

Go to the folder containing the uploaded package and extract it:

cd /home/ubuntu/Agent-Installer
ls

Unzip the file for the Agent-Linux-Installation-3-xx-xx.zip:

unzip Agent-Linux-Installation-3-06-09.zip

7. Open the New Installer Folder

Open the extracted SKYVVA Agent installation folder and verify that install.sh is available: After extracting the ZIP package, open the SKYVVA Agent installation folder:

ls
cd Agent-Linux-Installation-3-06-09  
ls
cd cd Skyvva-Agent-3.06.09  
ls

The folder should contain the install.sh script and the other Agent installation files.

Helpful Tips During Installation

You may find the following tips useful while completing the installation:

💡 Tip: Enter < at any prompt to return to the previous field and edit its value.  
💡 Tip: At the first field, such as the PostgreSQL username, enter < again to return to the Install/Upgrade/Exit menu.  
💡 Tip: Press Enter without typing anything to accept the value shown in (default: ...).  
💡 Tip: If an error occurs, you can retry your input up to three times. After the maximum number of attempts is reached, the SKYVVA Agent Installer will exit automatically.

Start the Installation

Run the installer with administrator privileges:

sudo ./install.sh

Note: If the installer starts successfully and no permission error appears, skip the permission setup steps below and continue with the installation.

Troubleshooting: Permission Denied

The installer may display the following error if install.sh does not have execute permission:

sudo: cannot execute './install.sh': Permission denied

Check the current file permissions:

ls -l install.sh
Grant execute permission to the script:

sudo chmod +x install.sh

Verify that execute permission was added:

ls -l install.sh

The permissions should now include x, for example:

-rwxr-xr-x 1 ubuntu ubuntu ... install.sh

Run the installer again:

sudo ./install.sh

Note: The x permission allows Linux to execute the file as a shell script.

8. Start the Installer

Run the installer with administrator privileges:

sudo ./install.sh

The setup menu appears. After running install.sh, the installer first displays the SKYVVA Integration Agent Setup menu. From this menu, you can create a new Agent installation, upgrade an existing Agent installation, or exit the installer.

For an Upgrade, select Upgrade. The installer will then display the Terms of Service and request the PostgreSQL connection details, Agent credentials, and installation folder.

8.1. Select the Installation Mode

The following setup menu appears when the installer starts:

_____ _                               ___                   _    ______
/  ___| |                             / _ \                 | |   \ \ \ \
\ `--.| | ___   ___   ____   ____ _  / /_\ \ __ _  ___ _ __ | |_   \ \ \ \
 `--. \ |/ / | | \ \ / /\ \ / / _` | |  _  |/ _` |/ _ \ '_ \| __|   > > > >
/\__/ /   <| |_| |\ V /  \ V / (_| | | | | | (_| |  __/ | | | |_   / / / /
\____/|_|\_\\__, | \_/    \_/ \__,_| \_| |_/\__, |\___|_| |_|\__| /_/_/_/
             __/ |                           __/ |
            |___/                           |___/

🚀 Starting installer..........

============================================================
               SKYVVA INTEGRATION AGENT SETUP
============================================================
  [1] Install  - Set up a new SKYVVA Agent
  [2] Upgrade  - Upgrade an existing SKYVVA Agent installation
  [3] Exit     - Cancel and close the installer

👉 Select an option [1/2/3]:

Enter 2 to select the upgrade process.

Select an option [1/2/3]: 2

8.2 Select the Existing Agent Installation

After selecting Upgrade, the installer detects the existing SKYVVA Agent services and displays their associated installation folders.

Each detected installation shows:

The systemd service name
The associated Agent installation folder

If your existing Agent installation is not listed, you can manually type or paste the full installation directory path.
Example:

Enter a number above, or the install path if it's not listed (or '<' to go back): /opt/skyvva-agent-9055
Enter

If your existing Agent installation is listed, enter the corresponding number from the list and press Enter.
In this example, enter 1 to upgrade the Agent installed in /opt/skyvva-agent-9055, or enter 2 to upgrade the Agent installed in /opt/skyvva-agent-9056.

============================================================
            DETECTED SKYVVA AGENT SERVICE(S)
============================================================
	[1] skyvva-agent@3.06.08-9055.service      /opt/skyvva-agent-9055
	[2] skyvva-agent@3.06.08-9056.service      /opt/skyvva-agent-9056
------------------------------------------------------------
💡 Tip: Enter a number above, or type/paste the install path directly
------------------------------------------------------------
👉 Enter a number above, or the install path if it's not listed (or '<' to go back):

The installer asks for the path of the existing SKYVVA Agent installation:

Now we just show your previous installation in the list and press 1 and then enter

Enter a number above, or the install path if it's not listed (or '<' to go back): 1  
Enter

9. Review the Existing Installation

After a valid path is entered, the installer detects the current configuration and displays a summary. Review it carefully before confirming the upgrade.

👉 Enter a number above, or the install path if it's not listed (or '<' to go back): 1`
------------------------------------------------------------ 
             ℹ️  Existing installation detected  
------------------------------------------------------------  
  Version         : 3.06.08 -> 3.06.09  
  DB Host         : localhost 
  DB Port         : 5432
  DB Database     : postgres
  DB Schema       : skyvva_9055
  DB Username     : postgres  
  DB Password     : ARyVMAnrXjrXQhyPynlHJg==  
  Agent Port      : 9055  
------------------------------------------------------------`  
🔍 Verifying database connection...  
✅ Database connection verified.

11. Confirm the Upgrade

After the installer detects the existing SKYVVA Agent installation and verifies the database connection, it asks for confirmation before starting the upgrade.

Continue with upgrade from version 3.06.08 to 3.06.09? (yes/no/back):

This confirmation step allows you to decide whether to continue, cancel, or return to the previous step.

Option	Description
yes	Continue with the upgrade from version 3.06.08 to 3.06.09. The installer will proceed with the upgrade process.
no	Cancel the upgrade process. The installer will stop without upgrading the existing Agent installation.
back	Return to the previous step. Use this option if you selected the wrong Agent installation or want to review/change the installation path before continuing.

Example:

Continue with upgrade from version 3.06.08 to 3.06.09? (yes/no): yes  
Enter

After entering yes, the installer starts upgrading the selected SKYVVA Agent installation to the new version.

12. Automatic Upgrade Process

After confirmation, the installer performs the upgrade automatically. The process includes:

Detecting and stopping the existing SKYVVA Agent service.
Replacing the Agent application JAR file and release notes.
Updating the systemd service definition.
Updating Flyway migration scripts and applying required database migrations.
Adding new configuration properties required by the target version.
Starting the upgraded Agent service.
Waiting until the Agent and Spring Boot are ready on the configured port.

Continue with upgrade from version 3.06.08 to 3.06.09? (yes/no/back): yes

############## Upgrade starting ################

Detected service unit: skyvva-agent@3.06.08-9055.service
Stopping existing service...
Stopping Skyvva Agent service 'skyvva-agent@3.06.08-9055.service'...
✅ Skyvva Agent service stopped successfully.
Replacing application jar...
Replacing release note...
Updating systemd service definition...
Renaming versioned service unit 'skyvva-agent@3.06.08-9055.service' -> 'skyvva-agent@9055.service'...
Created symlink '/etc/systemd/system/multi-user.target.wants/skyvva-agent@9055.service' → '/etc/systemd/system/skyvva-agent@9055.service'.
Refreshing shutdown.sh/startup.sh/uninstall.sh for this install...
✅ uninstall.sh has been created successfully.
restart.sh not found — generating it...
Updating Flyway migration scripts...
🚀 Running migration...
A more recent version of Flyway is available. Find out more about Flyway 13.7.0 at https://rd.gt/3rXiSlV

Flyway OSS Edition 10.11.0 by Redgate

See release notes here: https://rd.gt/416ObMi
Database: jdbc:postgresql://localhost:5432/postgres (PostgreSQL 18.6)
WARNING: Flyway upgrade recommended: PostgreSQL 18.6 is newer than this version of Flyway and support has not been tested. The latest supported version of PostgreSQL is 16.
Successfully validated 24 migrations (execution time 00:00.037s)
Current version of schema "skyvva_9055": 22
Migrating schema "skyvva_9055" to version "23 - 30609"
Successfully applied 1 migration to schema "skyvva_9055", now at version v23 (execution time 00:00.016s)
✅ Migration completed successfully.
Checking for new configuration properties...
  + added new property: new.propery
🚀 Starting service...
Starting Skyvva Agent service 'skyvva-agent@9055.service'...

==================================================
⚙️  SKYVVA AGENT SYSTEMD INTERFACE
» Action : START
» Service: skyvva-agent@9055.service
==================================================

Waiting for Skyvva Agent to become ready...

✅ Skyvva Agent is READY.
   Port : 9055

Waiting for Spring Boot to accept connections on port 9055...

✅ Spring Boot is ready on port 9055.
============================================================
         📋 SERVICE MANAGEMENT COMMANDS
============================================================
  🔹 THIS AGENT ONLY  (skyvva-agent@9055.service)
    [1] start   sudo skyvva-systemctl start skyvva-agent@9055.service
    [2] stop    sudo skyvva-systemctl stop skyvva-agent@9055.service
    [3] restart sudo skyvva-systemctl restart skyvva-agent@9055.service
    [4] status  sudo skyvva-systemctl status skyvva-agent@9055.service
    [5] logs    sudo journalctl -u skyvva-agent@9055.service -f
    [6] disable sudo systemctl disable skyvva-agent@9055.service
------------------------------------------------------------
  🔸 ALL AGENTS ON THIS HOST  (* = every skyvva-agent service)
    [1] start   sudo systemctl start skyvva-agent*.service
    [2] stop    sudo systemctl stop skyvva-agent*.service
    [3] restart sudo systemctl restart skyvva-agent*.service
    [4] status  sudo systemctl status skyvva-agent*.service
    [5] logs    sudo journalctl -u skyvva-agent*.service -f
    [6] disable sudo systemctl disable skyvva-agent*.service
============================================================

############## Upgrade completed: 3.06.08 -> 3.06.09 ################

13. Systemd Service Name Update

This service name update applies only when upgrading from the old version 3.06.08 to a newer version.

During this example upgrade, the installer renames the version-specific service unit to a stable port-based service name:

skyvva-agent@3.06.08-9055.service
                ↓
skyvva-agent@9055.service

After the rename, use the new service name for all Agent service-management commands.

Note: If your current Agent version is already 3.06.09 or later, the service name may already use the stable port-based format. In that case, the upgrade does not need to rename the service again.

Why is the service name changed?

The service name is changed to make Agent installation and upgrade more stable and easier to maintain. Previously, the service name included the Agent version. After each upgrade, the version number changed, so the service name also changed. This could make service management more difficult and could cause confusion when starting, stopping, or checking the Agent service. By using a stable port-based service name, such as skyvva-agent@9055.service, the service name remains the same even after upgrading to a new Agent version. This makes future upgrades smoother and ensures that service-management commands remain consistent.

14. Verify the Upgrade Result

When the upgrade is successful, the installer waits for the Agent and Spring Boot to accept connections on the configured port.

==================================================
⚙️  SKYVVA AGENT SYSTEMD INTERFACE
» Action : START
» Service: skyvva-agent@9055.service
==================================================

Waiting for Skyvva Agent to become ready...

✅ Skyvva Agent is READY.
   Port : 9055

Waiting for Spring Boot to accept connections on port 9055...

✅ Spring Boot is ready on port 9055.
============================================================
         📋 SERVICE MANAGEMENT COMMANDS
============================================================
  🔹 THIS AGENT ONLY  (skyvva-agent@9055.service)
    [1] start   sudo skyvva-systemctl start skyvva-agent@9055.service
    [2] stop    sudo skyvva-systemctl stop skyvva-agent@9055.service
    [3] restart sudo skyvva-systemctl restart skyvva-agent@9055.service
    [4] status  sudo skyvva-systemctl status skyvva-agent@9055.service
    [5] logs    sudo journalctl -u skyvva-agent@9055.service -f
    [6] disable sudo systemctl disable skyvva-agent@9055.service
------------------------------------------------------------
  🔸 ALL AGENTS ON THIS HOST  (* = every skyvva-agent service)
    [1] start   sudo systemctl start skyvva-agent*.service
    [2] stop    sudo systemctl stop skyvva-agent*.service
    [3] restart sudo systemctl restart skyvva-agent*.service
    [4] status  sudo systemctl status skyvva-agent*.service
    [5] logs    sudo journalctl -u skyvva-agent*.service -f
    [6] disable sudo systemctl disable skyvva-agent*.service
============================================================

############## Upgrade completed: 3.06.08 -> 3.06.09 ################

15. Verify the Upgraded Agent Version in the Local Web App

After the upgrade is complete, open the SKYVVA Agent Local Web App in a browser.

Example: http://32.236.220.72:9055

If the Local Web App opens successfully, the SKYVVA Agent service is running and accessible on the configured port.

In the Local Web App, go to: Setup → System Information

Under Agent Runtime, check the Agent Instance Version and confirm that it matches the upgraded version.

Example: Agent Instance Version: 3.06.09

Also confirm that the Database Runtime section displays: Database Status: Running

Expected result: The Local Web App is accessible, the new Agent version is displayed, and the PostgreSQL database status is Running.

16. Service Management Commands

Use the following commands after the upgrade:

Action	Command
Start	sudo skyvva-systemctl start skyvva-agent@9055.service
Stop	sudo skyvva-systemctl stop skyvva-agent@9055.service
Restart	sudo skyvva-systemctl restart skyvva-agent@9055.service
Status	sudo skyvva-systemctl status skyvva-agent@9055.service
Logs	sudo journalctl -u skyvva-agent@9055.service -f
Disable auto-start	sudo systemctl disable skyvva-agent@9055.service

============================================================
         📋 SERVICE MANAGEMENT COMMANDS
============================================================
  🔹 THIS AGENT ONLY  (skyvva-agent@9055.service)
    [1] start   sudo skyvva-systemctl start skyvva-agent@9055.service
    [2] stop    sudo skyvva-systemctl stop skyvva-agent@9055.service
    [3] restart sudo skyvva-systemctl restart skyvva-agent@9055.service
    [4] status  sudo skyvva-systemctl status skyvva-agent@9055.service
    [5] logs    sudo journalctl -u skyvva-agent@9055.service -f
    [6] disable sudo systemctl disable skyvva-agent@9055.service
------------------------------------------------------------
  🔸 ALL AGENTS ON THIS HOST  (* = every skyvva-agent service)
    [1] start   sudo systemctl start skyvva-agent*.service
    [2] stop    sudo systemctl stop skyvva-agent*.service
    [3] restart sudo systemctl restart skyvva-agent*.service
    [4] status  sudo systemctl status skyvva-agent*.service
    [5] logs    sudo journalctl -u skyvva-agent*.service -f
    [6] disable sudo systemctl disable skyvva-agent*.service

17. Troubleshooting Checklist

The new package version is newer than the installed Agent version.
The existing installation path is correct and begins with /.
The PostgreSQL service is running.
The database host, port, database, schema, username, and password are correct.
The Linux user has sudo permission.
The Agent port is available and not used by another process.
The new systemd service is enabled and running after the upgrade.
The Agent logs do not contain startup or database migration errors.

18. Upgrade Process Summary

Download the new Linux Agent package
                    ↓
Copy the package to the Linux server
                    ↓
Identify the existing Agent installation folder
                    ↓
Extract the new package
                    ↓
Run sudo ./install.sh
                    ↓
Select [2] Upgrade
                    ↓
Enter the existing absolute installation path or select DETECTED SKYVVA AGENT SERVICE(S) 
                    ↓
Review the detected configuration
                    ↓
Verify the PostgreSQL connection
                    ↓
Confirm the upgrade
                    ↓
Update the application, migrations, configuration, and service
                    ↓
Start and verify the upgraded SKYVVA Agent