En

Sherpa Orchestrator Installation Process#

For a new installation based on a separate server, see the external PostgreSQL instructions.

Extracting Client Files#

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

Extracting the Update Archive#

The following command extracts the archive into the installation directory.

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

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.

💡 Automatic Installation After extracting the archive, you can use the interactive script instead of the manual steps below:

sudo ./sh_scripts/install.sh

The script will guide you through all installation stages: database selection, image loading, .env configuration, SSL certificate generation, and container startup.

Preparing Scripts for Execution#

Installation scripts require execution permission.

# Navigate to the sh_scripts directory
# Make all scripts executable
# Return to the project's root directory
cd sh_scripts && chmod +x *.sh && cd ..
💡 Script Preparation Comments

cd sh_scripts/ - navigates to the installation scripts directory

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

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

cd .. - returns to the project's root directory

Loading Docker Images#

The following command loads images from the downloaded archives into the local Docker image store.

# Run the Docker images loading script
sudo ./sh_scripts/load_all_docker_images.sh
💡 Docker Images Loading Comments

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

What the script does:

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

Creating System Configuration#

The following command prepares the base configuration directories and files.

# Run the configuration creation script
sudo ./sh_scripts/create_config.sh
💡 Configuration Creation Comments

sudo ./sh_scripts/create_config.sh - runs the basic configuration creation script

What the script does:

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

Copying SSL Certificates#

To ensure a secure HTTPS connection, you need to copy the SSL certificates:

# Create a directory for certificates (if it does not exist)
mkdir -p ./nginx/config/certs/

# Rename and copy the certificate and key for your domain
# Replace paths with the actual 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
💡 SSL Certificates Copying Comments

mkdir -p ./nginx/config/certs/ - creates a directory for certificates

  • -p - creates parent directories if they do not 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: Ensure that the certificates have the correct permissions:

# Set the correct permissions on the certificates (may require sudo rights)
chmod 644 ./nginx/config/certs/orchestrator.crt
chmod 600 ./nginx/config/certs/orchestrator.key
chown 101:101 ./nginx/config/certs/orchestrator.key ./nginx/config/certs/orchestrator.crt

WARNING: Certificates must be obtained from the network administrator or your corporate certification center. If you do not have these certificates, you can follow the instructions for obtaining certificates from Let's Encrypt or other certification centers.

Configuring TLS for the LDAPS Protocol (optional step)#

This step is required only for LDAPS. The file /opt/SherpaOrchestrator/backend/config/certs/ca-certificates.crt must contain the image’s standard trusted certificates and the certificate authority certificate for the LDAPS server. Building the combined file is described in "Creating the trusted certificate file" under "Configuring Certificates for the IMAP Server (optional step)" in this article. When using both IMAP and LDAPS, add the certificates for both servers.

To mount the combined file, uncomment this line in the orchestrator service of docker-compose.yml:

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

Configuring Certificates for the IMAP Server (optional step)#

Important: This step can be skipped if Triggers started by email will not be used.

When checking email, the Orchestrator connects to the mail server over an encrypted connection and verifies the server certificate. Certificates of public email services are verified without additional configuration.

If the mail server certificate was issued by a corporate certification authority or is self-signed, the root certificate must be added to the Orchestrator's trusted certificates. Otherwise, the Trigger cannot check email, and a message similar to the following appears on the Audit screen:

Schedule:Имя Триггера; Email:robot@company.ru; IMAP connection failed: Certificate failure for mail.company.ru: unable to get local issuer certificate

Important: The certificate is verified even if the "Use SSL" checkbox is not selected in the Trigger settings. If the mail server supports STARTTLS, the Orchestrator enables connection encryption automatically.

Important: The Orchestrator does not use certificates copied to ./backend/config/certs/imap_certs. The steps below must be completed.

All commands are run from /opt/SherpaOrchestrator.

Checking the mail server certificate#

Before configuration, the mail server certificate can be checked against the image's standard list of trusted certificates. In the commands, mail.company.ru must be replaced with the value of the "Mail server" field, and the port must match the Trigger settings. IMAP with "Use SSL" selected usually uses port 993, while STARTTLS uses port 143:

# Выведите цепочку сертификатов почтового сервера
# Замените mail.company.ru на значение поля "Почтовый сервер" из настроек Триггера
docker run --rm --entrypoint openssl orchestrator s_client -connect mail.company.ru:993 -servername mail.company.ru -verify_hostname mail.company.ru -showcerts </dev/null

# Если в поле "Порт" указан порт 143, используйте команду
docker run --rm --entrypoint openssl orchestrator s_client -connect mail.company.ru:143 -servername mail.company.ru -verify_hostname mail.company.ru -starttls imap -showcerts </dev/null
💡 Notes on checking the certificate

docker run --rm --entrypoint openssl orchestrator - runs openssl from the Orchestrator image with its standard list of trusted certificates

s_client -connect mail.company.ru:993 - connects to the mail server and displays its certificates. The parameters are:

  • -servername — sends the mail server name when establishing the TLS connection (SNI), but does not check whether the name matches the certificate
  • -verify_hostname — checks that the certificate was issued for the server name specified in the Trigger settings
  • -starttls imap — enables connection encryption on port 143
  • -showcerts — displays the full certificate chain

The verification result appears at the end of the output in the Verify return code line. Possible values are:

  • 0 (ok) — the image's standard list validates the certificate, and the server name matches the certificate. Adding a certificate can be skipped if no custom trusted certificate file is mounted. A running container with a mounted file also requires the check in the "Checking the connection" section
  • 18, 19, 20 or 21 — the certification authority's root certificate is required. Its name appears in the i: line of the last certificate in the chain
  • 62 (hostname mismatch) — the server name does not match the certificate. Adding a root certificate does not resolve this error

Preparing the certificate#

The root certificate of the certification authority that issued the mail server certificate can be obtained from the network administrator. If the mail server does not send intermediate certificates, these must also be obtained. If the mail server certificate is self-signed, that certificate itself is used.

The certificate must be in PEM text format: the file starts with -----BEGIN CERTIFICATE-----. A certificate in binary DER format, such as a .cer file exported from Windows, must be converted:

# Преобразуйте сертификат из формата DER в формат PEM
# Замените пути на реальные пути к сертификату
docker run --rm -i --entrypoint openssl orchestrator x509 -inform der < /path/to/root-ca.cer > /path/to/root-ca.crt

Important: The Orchestrator certificate orchestrator.crt and private keys are not suitable for this step.

Creating the trusted certificate file#

The trusted certificate file must contain the standard certificate list from the Orchestrator image and the certification authority's root certificate:

Before creating the file, back up any existing ca-certificates.crt under an unused name. The new file must contain the image’s standard certificates and all custom trusted certificates, including those used for LDAPS. The command below overwrites the file, so prepare this complete set beforehand.

# Выгрузите стандартный список доверенных сертификатов из образа Оркестратора
docker run --rm --entrypoint cat orchestrator /etc/ssl/certs/ca-certificates.crt > ./backend/config/certs/ca-certificates.crt

# Добавьте в конец файла корневой сертификат центра сертификации
# Замените путь на реальный путь к сертификату
echo >> ./backend/config/certs/ca-certificates.crt
cat /path/to/root-ca.crt >> ./backend/config/certs/ca-certificates.crt

# Установите права на чтение файла (могут понадобиться sudo права)
chmod 644 ./backend/config/certs/ca-certificates.crt
💡 Notes on creating the trusted certificate file

docker run --rm --entrypoint cat orchestrator /etc/ssl/certs/ca-certificates.crt - saves the standard list of trusted certificates from the Orchestrator image. Without it, the Orchestrator will stop trusting public servers

echo >> ./backend/config/certs/ca-certificates.crt - adds a newline to prevent certificates in the file from being joined together

cat /path/to/root-ca.crt >> ./backend/config/certs/ca-certificates.crt - appends the certificate to the file. If there are several certificates, such as a root and an intermediate certificate, the command must be repeated for each one

File requirements:

  • The file must be named ca-certificates.crt
  • The file must be located in ./backend/config/certs/
  • The file completely replaces the trusted certificate list in the Orchestrator container

Important: If the "Configuring TLS for the LDAPS Protocol" step has been completed, the export command will overwrite ca-certificates.crt. In this case, the LDAPS server's root certificate must also be added to the file.

Mounting the file in the Orchestrator#

In docker-compose.yml, the following line must be uncommented in the orchestrator service:

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

If the line was already uncommented when configuring LDAPS, this step can be skipped. Lines containing imap_certs do not need to be changed.

If the Orchestrator has not been started yet, installation can continue with the next step. If it is already running, the container must be recreated:

# Пересоздайте контейнер orchestrator, чтобы подключить файл доверенных сертификатов
docker compose up -d --no-deps --force-recreate orchestrator

Important: The docker compose restart command and a server reboot do not apply changes to docker-compose.yml.

Checking the connection#

After the Orchestrator starts, the mail server certificate and name can be checked using the mounted trusted certificate file. The command must match the Trigger's connection mode, and the server name and port must be replaced with the values from its settings:

# IMAP с SSL, обычно порт 993
docker exec orchestrator openssl s_client -connect mail.company.ru:993 -servername mail.company.ru -verify_hostname mail.company.ru </dev/null

# IMAP с STARTTLS, обычно порт 143
docker exec orchestrator openssl s_client -connect mail.company.ru:143 -servername mail.company.ru -verify_hostname mail.company.ru -starttls imap </dev/null

The output should contain Verify return code: 0 (ok). This confirms verification of the certificate and server name, but does not verify the mailbox credentials. If the connection cannot be established, the error message, address, port and server accessibility from the container must be checked. The openssl s_client utility may exit with code 0 even when certificate verification fails, so the Verify return code line must be checked.

Then, in the Trigger settings on the "Email" tab, the "Test getting email" button can be clicked. A successful connection displays the notification "Test succeeded, received N messages".

Important: The "Mail server" value must match the server certificate, for example mail.company.ru. If the certificate is issued only for a domain name, connecting by IP address results in hostname mismatch.

Possible errors#

Mail server connection errors appear on the Audit screen. Typical certificate errors are:

  • unable to get local issuer certificate, unable to verify the first certificate, self-signed certificate — the required certificate is missing from ca-certificates.crt, or the file is not mounted in the Orchestrator container
  • hostname mismatch — the "Mail server" value in the Trigger settings does not match the name in the certificate

Selecting Database Configuration#

For an embedded database, choose MariaDB (DB_ENGINE=mysql, profile mariadb) or PostgreSQL (DB_ENGINE=pgsql, profile pg). Configure only the selected database engine below. For an external database, specify the separate server address and do not enable local database profiles.

Setting Environment Variables#

Set the server address, domain, and selected database parameters. The values your_server_ip, your_domain_name, and passwords below are examples and must be replaced with installation values. VNC settings are required only when using that profile.

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

Server, selected database, and VNC parameters:

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

# Domain name that will be used by NGINX
NGINX_DOMAIN_NAME=your_domain_name

# 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

# Database type: mysql or pgsql
DB_ENGINE=mysql

# MySQL settings (used when DB_ENGINE=mysql)
MYSQL_HOST=orchestrator-db
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=mysql-password
MYSQL_DB=orchestrator

# Also set the password for the MariaDB container (must match MYSQL_PASSWORD)
DB_PASSWORD=mysql-password

# PostgreSQL settings (used when DB_ENGINE=pgsql)
POSTGRES_HOST=orchestrator-pg
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres-password
POSTGRES_DBNAME=postgres
POSTGRES_SCHEMA_NAME=orchestrator
💡 Environment Variables Configuration Comments

HOST_IP — The IP address or domain name of the server, by which the system is accessible externally. It should be a static IP or a correctly configured domain.

NGINX_DOMAIN_NAME — The domain for the web interface (e.g., orchestrator.example.com). Usually matches the domain in the SSL certificate.

DB_ENGINE — Choose mysql for MariaDB or pgsql for PostgreSQL. This value determines which set of connection variables will be used.

MYSQL_PASSWORD / DB_PASSWORD — Password for MySQL/MariaDB. Both values must match: MYSQL_PASSWORD is used by the application, DB_PASSWORD is used by the database container.

POSTGRES_PASSWORD — Password for PostgreSQL. Used by both the DB container and the application.

All configuration parameters (database, mail, LDAP, proxy, etc.) are read directly by the application from the environment variables in the .env file. Editing backend/config/config.ini or backend/config/phinx.php is not required — they are already configured to work through .env.

If necessary, configure additional parameters in .env:

# Mail server settings (SMTP)
SMTP_SERVER=smtp.example.com
SMTP_PORT=25
SMTP_SECURE=tls
SMTP_LOGIN=
SMTP_PASSWORD=
SMTP_FROM=Orchestrator
SMTP_FROM_EMAIL=

# LDAP settings (optional)
LDAP_SERVER=
LDAP_PORT=389
LDAP_ENCRYPTION=tls
LDAP_BASE_DN=dc=mydomain,dc=local
LDAP_GROUP=Group
LDAP_UID_KEY=uid
LDAP_USER=
LDAP_USERNAME=
LDAP_PASSWORD=
LDAP_FILTER=
LDAP_NETWORK_TIMEOUT=5
LDAP_OPERATION_TIMEOUT=10

# Other settings
SESSION_LAST_ACTIVITY_TIMEOUT=30
STORE_LOGS_DAYS=180
STORE_AUDIT_DAYS=180

LDAP parameters, StartTLS and LDAPS modes, as well as the required HTTPS callback for OpenID are described in the user authorization instructions. For OpenID, use the address /api/v1/system/oauth_hook; the old path /api/gui/system/oAuthHook is not suitable.

Starting the system#

Run one command for the selected database and additional services. For an external database, use docker compose up -d without the mariadb or pg profiles.

# 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 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

# Combination of profiles: MariaDB + VNC + Vault
docker compose --profile mariadb --profile vnc --profile vault up -d
💡 Comments on starting the system

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

--profile vnc - the VNC profile is optional, it starts the service orchestrator-vnc-proxy

  • Only necessary if robots use VNC for desktop management
  • Add to any combination of profiles

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

  • The vault profile is optional and is included only when needed
  • Further configuration is described in Using Vault.

What the script does:

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

Checking the startup status#

Use the following commands to check service status and startup messages.

# Check the status of all running containers
docker compose ps

# View the system logs
docker compose logs orchestrator

# Monitor logs in real-time
docker compose logs -f orchestrator
💡 Comments on checking the status

docker compose ps - shows the status of all containers

docker compose logs orchestrator - shows logs of the main service

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

  • -f - follow (monitor new messages)

After successful startup, orchestrator, orchestrator-nginx, and orchestrator-websocket have the Up status. An embedded database also starts orchestrator-db or orchestrator-pg; an external database does not require a local database container. Additional services depend on the selected profiles. The HTTPS port is published by orchestrator-nginx, not the orchestrator backend container.

Checking system availability#

Checking the web interface:

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

# Expected response: HTTP/2 200 or redirection

Managing the system#

Stopping the system:

# Stop all services
docker compose down

The docker compose down command preserves named data volumes. The -v option deletes those volumes and their contents, so it must not be used for a normal shutdown.

Restarting services:

# Restart a specific service
docker compose restart orchestrator

# Restart all services
docker compose restart

Viewing resources:

# Check resource usage by containers
docker stats

Possible issues during startup:#

To diagnose a failure, check:

  • Containers do not start — messages from docker compose logs.
  • Network issues — availability of ports 80 and 443, plus 5000 and 6080–6100 when using VNC.
  • Database connection errors — connection parameters in .env and database accessibility.
  • Domain issues — HOST_IP and DNS settings.

After successful startup and testing of the system, the installation of Sherpa Orchestrator is complete. The system will be available via HTTPS at the configured domain or IP address.