Sherpa Orchestrator Update Process#

⚠️ Before updating: review the release notes for every version from the installed version to the target version. They may contain mandatory upgrade steps. Notes for the latest published release: version 5.9.4.

⚠️ Important: If Sherpa Orchestrator is being updated from a version below 5.9.1 and the built-in Sherpa Orchestrator database is used, the database must be migrated before the update.

For MariaDB, perform the migration according to the instructions in "Migrating MariaDB to the orchestrator-db:v5.9.2+ container".

For PostgreSQL, perform the migration according to the instructions in "Migrating PostgreSQL to the orchestrator-pg:v5.9.2+ container".

If the update is from version 5.9.1 or later, or an external database is used, migration is not required.

💡 Automatic update Instead of the manual steps below, an interactive script can be used:

Copy

sudo ./sh_scripts/update.sh

The script performs a backup, stops containers, downloads new images, updates .env, and starts the system with availability checks.

1. Downloading files#

Download all the latest Sherpa Orchestrator update files using the links in the preparation section

2. Transferring files to the server#

After downloading, transfer all files to the target Linux server using any convenient method:

Via SCP/SFTP#

# Copy files to the server
scp *.tar.gz user@target-server:/path/to/installation/directory/

Via SFTP client#

Use any SFTP client (FileZilla, WinSCP, Cyberduck) to copy files to the server.

Via network share#

If the server is accessible via SMB/CIFS, use Windows Explorer or the copy command.

Verifying the transfer#

# Connect to the server
ssh user@target-server

# Navigate to the directory with files (usually opt/SherpaOrchestrator)
cd /path/to/installation/directory

# Verify all files are present
ls -la *.tar.gz

# Check file sizes
ls -lh *.tar.gz

3. Stopping containers#

# Stop all running services
docker compose down

4. Loading Docker images#

# Create a backup of the .env file (if it exists)
cp .env .env.backup

# Create a backup of the configuration
cp -r ./backend/config ./backend/config_backup

# If custom certificates are used, copy them to a safe location
cp -r ./backend/config/certs ./certs_backup

# Unpack the update files
tar -xvzf "$(ls docker_orchestrator_client_files_*.tgz | sort -V | tail -n 1)"

# Copy the default nginx configuration (if it does not exist)
cp -r ./nginx/config/default ./nginx/config

# Make scripts executable
chmod +x sh_scripts/*.sh

# If a certificate backup was created, restore it
cp -r ./certs_backup/* ./nginx/config/certs/

# Load all Docker images
sudo ./sh_scripts/load_all_docker_images.sh

5. Selecting DB configuration and verifying environment variables#

# Open the .env file for review and updates
nano ./.env

# Check for required variables
grep -E "(HOST_IP|MYSQL_PASSWORD|DB_PASSWORD|POSTGRES_PASSWORD|NGINX_DOMAIN_NAME|DB_ENGINE)" .env

# Verify syntax correctness
cat .env | grep -v '^#' | grep '=' | wc -l

5.1 cache.bin migration (only when updating from version ≤ v141856)#

⚠️ Important: This step is required only if the update is from version v141856 or earlier. If the current orchestrator version is newer than v141856, skip this section.

When updating from version ≤ v141856, the cache.bin file must be mounted inside the orchestrator container.

Add the following line to the volumes section of the orchestrator service in docker-compose.yml:

  orchestrator:
    ...
    volumes:
      - orchestrator-storage:/opt/SherpaOrchestrator/backend/Storage
      - ./backend/config:/opt/SherpaOrchestrator/backend/config:z
      - ./path/to/cache.bin:/opt/SherpaOrchestrator/backend/app/cache.bin  # add this line

Replace ./path/to/cache.bin with the actual path to the cache.bin file on the server.

6. Starting containers#

# Start services with the selected DB profile
# Option 1: MariaDB
docker compose --profile mariadb up -d

# Option 2: PostgreSQL
docker compose --profile pg up -d

# If VNC is needed (optional), add the vnc profile:
# Option 1: MariaDB + VNC
docker compose --profile mariadb --profile vnc up -d

# Option 2: PostgreSQL + VNC
docker compose --profile pg --profile vnc up -d

# If Vault is needed (optional), add the vault profile:
# Option 1: MariaDB + Vault
docker compose --profile mariadb --profile vault up -d

# Option 2: PostgreSQL + Vault
docker compose --profile pg --profile vault up -d

# Profile combination: MariaDB + VNC + Vault
docker compose --profile mariadb --profile vnc --profile vault up -d

Vault initialization and secret migration are covered in a separate guide:

After a successful update, the Sherpa Orchestrator system is ready for use.

Migrating the screenshot indicator in logs#

This section applies to a build containing 20261006120000_add_log_has_file.php. A database backup and maintenance window are required before updating. The migration account needs permissions to alter tables and create triggers. PostgreSQL also requires permission to create the function.

The migration follows this sequence:

1. Application processes must be stopped while the database remains available.

2. Standard Phinx migrations must be run from the new build's container for the selected database engine.

3. After migration, the following query must confirm that no rows lack a screenshot indicator:

   Copy

   SELECT COUNT(*) FROM orchestrator.logs WHERE has_file IS NULL;
   

4. The application can be started when the result is 0.

The migration adds orchestrator.logs.has_file and installs triggers for new and updated records. Existing rows are filled in batches of up to 100. Old screenshots are read once, so duration depends on the data volume. Schema changes may lock the table.

After an interruption, the cause must be resolved and migrations run normally again. Rows already filled are skipped. The --fake option should not be used.

The API response format and screenshot retrieval remain unchanged. The archive table is unchanged. Rollback requires stopping the application and restoring code that does not use has_file first. The migration can then be rolled back. Screenshots themselves are not deleted.