En

Sherpa Orchestrator Update Process#

Updating Sherpa Orchestrator#

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/
💡 Notes on SCP/SFTP transfer

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

  • scp - secure copy
  • *.tar.gz - pattern for selecting update files
  • user@target-server - connection credentials
  • /path/to/installation/directory/ - destination path on the server

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
💡 Notes on transfer verification

ssh user@target-server - connects to the remote server via SSH

  • ssh - secure shell
  • user@target-server - connection credentials

cd /path/to/installation/directory - navigates to the directory with files

*ls -la .tar.gz - shows detailed information about the downloaded files

  • -l - long format
  • -a - shows hidden files

*ls -lh .tar.gz - shows file sizes in human-readable format

  • -h - human readable (KB, MB, GB)

3. Stopping containers#

# Stop all running services
docker compose down
💡 Notes on stopping containers

docker compose down - stops all Docker Compose services

  • Stops and removes containers and networks
  • Preserves volumes and images

Checking stop status: docker ps -a | grep orchestrator - checks container status

  • docker ps -a - shows all containers (including stopped ones)
  • | grep orchestrator - filters by orchestrator name

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 doesn't exist)
cp -r ./nginx/config/default/. ./nginx/config

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

# Copy the orchestrator configuration (files are replaced with new ones)
cp -af ./backend/config/default/. ./backend/config/

# Copy the vault configuration (files are replaced with new ones)(if you will use vault)
cp -af ./vault/config/default/. ./vault/config

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

# Load all Docker images
sudo ./sh_scripts/load_all_docker_images.sh
💡 Notes on loading Docker images

Creating backups:

  • cp .env .env.backup - backup of the configuration file
  • cp -r ./backend/config ./backend/config_backup - backup of the config directory
  • cp -r ./backend/config/certs ./certs_backup - backup of SSL certificates

Unpacking and preparation:

  • tar -xvzf "$(ls orchestrator_docker_update_*.tgz | sort -V | tail -n 1)" - unpacks the latest update files
  • chmod +x sh_scripts/*.sh - makes scripts executable
  • cp -r ./certs_backup/* ./backend/config/certs/ - restores certificates

sudo ./sh_scripts/load_all_docker_images.sh - loads all Docker images

Verifying load: docker images | grep orchestrator - shows loaded orchestrator images

5. Selecting DB configuration and verifying environment variables#

# Copy the combined client compose file
cp docker-compose.client.yml docker-compose.yml
💡 Notes on DB configuration selection

cp docker-compose.client.yml docker-compose.yml - selects the combined client configuration

  • The working directory must contain the final docker-compose.yml file
  • For MariaDB, run with the mariadb profile
  • For PostgreSQL, run with the pg profile
# Open the .env file to review
nano ./.env

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

# Verify syntax correctness
cat .env | grep -v '^#' | grep '=' | wc -l
💡 Notes on environment variable verification

nano ./.env - opens the configuration file in editor

grep -E "(HOST_IP|DB_PASSWORD|POSTGRES_PASSWORD|NGINX_DOMAIN_NAME)" .env - checks for key variables

  • -E - extended regular expressions
  • Lists required variables separated by |

cat .env | grep -v '^#' | grep '=' | wc -l - counts the number of variables

  • cat .env - outputs file content
  • grep -v '^#' - excludes comments
  • grep '=' - retains only lines with variables
  • wc -l - counts the number of lines

Checking config.ini and phinx.php#

Make sure the same passwords are specified as in the .env file:

  • backend/config/config.ini — database_password parameter (and when using PostgreSQL — the corresponding settings);
  • backend/config/phinx.php — in the environments section, the 'pass' parameter in the 'mysql' or 'pgsql' block (must match the passwords from .env and config.ini).

Otherwise, migrations on container startup may fail with an error.

# Edit the configuration if necessary
nano backend/config/config.ini
nano backend/config/phinx.php

IF THE CURRENT VERSION OF THE ORCHESTRATOR FROM WHICH YOU ARE UPDATING IS LESS THAN OR EQUAL TO v141856, YOU MUST MOUNT THE cache.bin FILE INSIDE THE orchestrator CONTAINER IN docker-compose.yml

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

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 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
💡 Notes on starting containers

docker compose --profile <mariadb|pg> up -d - starts services in background mode with the selected database

  • -d - detached mode (background mode)

docker compose --profile <mariadb|pg> --profile vault up -d - starts the system with Vault

  • The vault profile is optional and is only connected when a secret store and Vault migration are needed

Verifying startup:

  • docker compose ps - shows the status of all containers
  • docker compose logs -f orchestrator - shows startup logs in real time

Vault initialization and secret migration are described in a separate guide: 6) VAULT.md.

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