En

Sherpa Orchestrator Installation Process#

Installing Sherpa Orchestrator#

Extracting client files#

At this stage, you will extract the Sherpa Orchestrator update archive and prepare the system for installation.

Extracting the update archive#

# Find and extract the update archive (the latest version is selected automatically)
tar -xvzf "$(ls docker_orchestrator_client_files_*.tgz | sort -V | tail -n 1)"
💡 Notes on archive extraction

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

  • tar -xvzf - extracts the archive with detailed output
  • ls docker_orchestrator_client_files_*.tgz - finds all update archive files
  • sort -V - sorts versions naturally (1.0 < 1.1 < 1.10)
  • tail -n 1 - selects the latest file

Expected result: The necessary files and directories for the system update will be extracted.

Expected result: The Sherpa Orchestrator update files will be extracted.

Preparing scripts for execution#

# Navigate to the sh_scripts directory
# Make all scripts executable
# Return to the root project directory
cd sh_scripts && chmod +x *.sh && cd ..
💡 Notes on script preparation

cd sh_scripts/ - navigates to the directory with installation scripts

*chmod +x .sh - sets execution rights for all shell scripts

  • chmod +x - adds execution permission
  • *.sh - all files with .sh extension

cd .. - returns to the root project directory

Loading Docker images#

# Run the Docker image loading script
sudo ./sh_scripts/load_all_docker_images.sh
💡 Notes on loading Docker images

sudo ./sh_scripts/load_all_docker_images.sh - runs the Docker image loading script

What the script does:

  1. Loads all Docker images from the downloaded .tar.gz files
  2. Imports images into the local Docker registry
  3. Verifies the successful loading of all orchestrator images

Creating system configuration#

# Run the configuration creation script
sudo ./sh_scripts/create_config.sh
💡 Notes on configuration creation

sudo ./sh_scripts/create_config.sh - runs the script for creating the base configuration

What the script does:

  1. Creates the necessary directories for configuration
  2. Sets up the basic system parameters
  3. Prepares the structure for further configuration

Copying SSL certificates#

To ensure a secure HTTPS connection, SSL certificates must be copied:

# Create the certificates directory (if it doesn't exist)
mkdir -p ./nginx/config/certs/

# Rename and copy the certificate and key for your domain
# Replace the paths with the real paths to your certificates
cp /path/to/your/certificate.crt ./nginx/config/certs/orchestrator.crt
cp /path/to/your/private.key ./nginx/config/certs/orchestrator.key
💡 Notes on copying SSL certificates

mkdir -p ./nginx/config/certs/ - creates the certificates directory

  • -p - creates parent directories if they don't exist

cp /path/to/your/certificate.crt ./nginx/config/certs/orchestrator.crt - copies and renames the certificate cp /path/to/your/private.key ./nginx/config/certs/orchestrator.key - copies and renames the private key

Certificate requirements:

  • The certificate must be renamed to orchestrator.crt
  • The private key must be renamed to orchestrator.key
  • File names must exactly match those specified
  • Certificate format: .crt or .pem
  • Key format: .key

Important: Make sure the certificates have the correct permissions:

# Set correct permissions on certificates (sudo may be required)
chmod 644 ./nginx/config/certs/orchestrator.crt
chmod 600 ./nginx/config/certs/orchestrator.key
chown 65532:65532 ./nginx/config/certs/orchestrator.key ./nginx/config/certs/orchestrator.crt

WARNING: Certificates must be obtained from the network administrator or your corporate certification authority. If these certificates are not available, you can use the Let's Encrypt or other certification authority instructions to obtain certificates.

Configuring TLS for LDAPS protocol (optional step)#

Important: If LDAPS support is not required, skip this step.

Copy the rootCA certificate named ca-certificates.crt to the /opt/SherpaOrchestrator/backend/config/certs/ directory

In the docker-compose.yml file, uncomment the line:

- ./backend/config/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro

Configuring certificates for IMAP server (optional step)#

Important: If you do not plan to use Triggers with email-based launches or your mail server does not require certificates, skip this step.

Copy the IMAP certificates to the /opt/SherpaOrchestrator/backend/config/certs/imap_certs folder

Selecting database configuration#

Use the unified compose file and select the database via profile:

# 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 - copies the combined configuration for client launch

Recommendations:

  • For MariaDB, run with the mariadb profile
  • For PostgreSQL, run with the pg profile
  • The working directory must contain the final docker-compose.yml file

Configuring environment variables#

Open the .env file and configure the main parameters:

# Open the .env file in a text editor
nano .env

Be sure to configure the following variables:

# Server IP address (change to your actual IP address or domain)
HOST_IP=your_server_ip

# Domain name that NGINX will use (usually matches your primary domain)
NGINX_DOMAIN_NAME=your_domain_name

# MySQL database password (if different from the default "mysql-password")
DB_PASSWORD=mysql-password

# PostgreSQL database password (if different from the default "postgres-password")
POSTGRES_PASSWORD=postgres-password

# VNC settings
VNC_HOST=your_server_ip
VNC_PORT=5900
VNC_LOG_LEVEL=INFO
VNC_START_PORT=6080
VNC_MAX_PORTS=21
VNC_WEBSOCKIFY_WEB_ROOT=/opt/noVNC
💡 Notes on environment variable configuration

nano .env - opens the environment variables file

  • .env - file with environment variables for Docker Compose

HOST_IP - critically important parameter

  • Specify the actual IP address or domain name of your server
  • This is the address from which the system will be accessible externally
  • Must be a static IP or a correctly configured domain

NGINX_DOMAIN_NAME - domain name for the web interface

  • Specify the domain that users will use to access Sherpa Orchestrator (e.g., orchestrator.example.com)
  • Usually matches the domain specified in the SSL certificate

DB_PASSWORD - MySQL database password

  • Default: mysql-password
  • Change to a strong password if needed

POSTGRES_PASSWORD - PostgreSQL database password

  • Default: postgres-password
  • Change to a strong password if needed

Configuring the database#

Open the configuration file and set the database and mail server parameters:

# Open the configuration file
sudo nano backend/config/config.ini

Configure the following parameters:

# Database settings (for MySQL - default)
database_engine=mysql
database_host=orchestrator-db
database_port=3306
database_user=root
database_password=mysql-password
database_dbname=orchestrator
database_dbname_archive=orchestrator_archive

# Database settings (for PostgreSQL - uncomment if using PostgreSQL)
;database_engine=pgsql
;database_host=orchestrator-pg
;database_port=5432
;database_user=postgres
;database_password=postgres-password

Important: If you changed the passwords in the .env file (DB_PASSWORD or POSTGRES_PASSWORD), make sure the corresponding passwords in config.ini match!

Configuring phinx.php (DB migrations)#

The backend/config/phinx.php file is used by Phinx to perform migrations when the container starts. The passwords in it must match those in .env and config.ini:

sudo nano backend/config/phinx.php

In the environments section, set the same passwords as in config.ini:

  • For MySQL: in the 'mysql' block, the 'pass' parameter must match DB_PASSWORD from .env (default mysql-password).
  • For PostgreSQL: in the 'pgsql' block, the 'pass' parameter must match POSTGRES_PASSWORD from .env (default postgres-password).

If the passwords do not match, migrations will fail at container startup.

💡 Notes on config.ini configuration

sudo nano backend/config/config.ini - opens the configuration file

  • sudo - administrator rights for editing
  • nano - text editor
  • backend/config/config.ini - path to the configuration file

Database parameters:

  • database_password - password must match MYSQL_ROOT_PASSWORD from the .env file
  • database_engine - select 'mysql' or 'pgsql' depending on the chosen docker-compose file
  • database_host - leave as is (orchestrator-db or orchestrator-pg)
  • database_port - leave as is (3306 for MySQL, 5432 for PostgreSQL)

Important:

  • Database passwords must exactly match the passwords in the .env file
  • The same passwords must be specified in backend/config/phinx.php (the pass fields in the mysql and pgsql sections) — otherwise, migrations will not execute at container startup
  • If using PostgreSQL - uncomment the corresponding lines and comment out MySQL
  • Save the file after making changes (Ctrl+O, Enter, Ctrl+X)

Starting the system#

After completing all preparatory steps, Sherpa Orchestrator can be started.

# Start the system with the desired 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 the system

docker compose --profile <mariadb|pg> up -d - starts the system with the selected DB

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

  • The vault profile is optional and is enabled only when needed
  • For further Vault configuration, use the 6) VAULT.md guide

What the script does:

  1. Starts the orchestrator services via Docker Compose
  2. Activates only the selected database container by profile (mariadb or pg)
  3. Configures the network and volumes
  4. Performs database migrations if needed
  5. Starts the services in background mode

Checking startup status#

# Check the status of all running containers
docker compose ps

# View system logs
docker compose logs orchestrator

# Monitor logs in real time
docker compose logs -f orchestrator
💡 Notes on startup status verification

docker compose ps - shows the status of all containers

  • Should be running: orchestrator, orchestrator-vnc-proxy, and one DB container (orchestrator-db with mariadb or orchestrator-pg with pg)

docker compose logs orchestrator - shows logs for the main service

docker compose logs -f orchestrator - follows logs in real time

  • -f - follow (watch for new messages)

Expected output after successful startup:

NAME                    STATUS              PORTS
orchestrator            Up 2 minutes        0.0.0.0:443->443/tcp
orchestrator-db         Up 2 minutes        3306/tcp
orchestrator-vnc-proxy  Up 2 minutes        0.0.0.0:5000->5000/tcp, 0.0.0.0:6080-6100->6080-6100/tcp

# For the pg profile, orchestrator-pg will appear instead of orchestrator-db

Checking system availability#

Web interface check:

# Check HTTPS availability (replace with your domain/IP)
curl -I https://your-domain-or-ip

# Expected response: HTTP/2 200 or redirect

System management#

Stopping the system:

# Stop all services
docker compose down

# Stop with volume removal (caution!)
docker compose down -v

Restarting services:

# Restart a specific service
docker compose restart orchestrator

# Restart all services
docker compose restart

Viewing resources:

# Check container resource usage
docker stats

Possible issues during startup:#

  • Containers not starting: Check logs with docker compose logs
  • Network issues: Make sure ports 443, 5000, 6080-6100 are free
  • DB connection errors: Check settings in docker-compose.yml
  • Domain issues: Make sure HOST_IP is correctly configured

After successfully starting and testing the system, the Sherpa Orchestrator installation is complete. The system will be accessible via HTTPS at the configured domain or IP address.