Using Docker#

This section is intended for administrators of the Sherpa Orchestrator Docker distribution. Commands require access to the server and Docker Compose. Client files and images must have the same version. Check that the installed distribution contains the required parameter or script.

Diagnostics after installation and updates#

The installer and update script offer to run diagnostics. To repeat the checks, run this command from the installation directory:

cd /opt/SherpaOrchestrator
sudo bash sh_scripts/diagnostics.sh

Checks cover containers, selected components, versions, free space, database connectivity, migrations, Vault, SIEM, nginx, Storage, the web interface, and logs. Any repairs offered by the script require separate confirmation. Read the action description before confirming.

A result without findings means that the implemented checks passed. It does not replace testing a user workflow or SIEM delivery. On failure, record the check name and message, resolve the cause, and repeat diagnostics. Migration checks in this distribution do not prove that every database schema object matches expectations.

System metrics retention#

The STORE_SYSTEM_METRICS_DAYS parameter in .env sets the number of days to retain system metrics. The default is 30. A value of 0 disables automatic cleanup of these metrics. Use a non-negative integer.

The scheduler deletes expired records. Reducing retention can delete history that cannot be recovered by increasing the value later. This parameter does not set retention for Jobs, audit events, or Robot messages.

Example: to retain the last 14 days of system metrics, set this in .env:

STORE_SYSTEM_METRICS_DAYS=14

Apply the new retention by recreating only the backend container during the agreed maintenance window:

cd /opt/SherpaOrchestrator
sudo docker compose up -d --no-deps --force-recreate orchestrator

Password requirements#

These .env parameters apply to new User and Account passwords when creating an entry or changing its password:

Length is checked in bytes and may differ from the character count for non-ASCII text. Minimum and maximum lengths must be positive integers. If the maximum is below the minimum, the minimum is used. Invalid lengths and an invalid regular expression fall back to defaults. Enter the regular expression without delimiters.

Changing the policy does not change stored passwords. If a new password is rejected, check its length and format. To apply changed environment variables, recreate the backend container during an agreed maintenance window:

cd /opt/SherpaOrchestrator
sudo docker compose up -d --no-deps --force-recreate orchestrator

Simply restarting a container does not reload environment variables from .env.

Backup and migration#

A verified backup is required before updating or migrating. A database dump does not include Storage, configuration, or Vault secrets. Backup contents and limitations are described in Backup and recovery.

Migrating a local distribution to Docker requires the same version, the same server, and the same database engine. Preserve HOST_IP, the encryption key, the main and archive databases, Storage, certificates, and the original installation for rollback. Stop the application and other writers during copying and verification.

Before migration, obtain the local-to-Docker migration procedure for your version and database engine from Sherpa technical support. Changing the server, IP address, version, or database engine requires a separate plan. Do not run the old and new installations against the same production database simultaneously.

Moving to a new server with the existing database may require restoring the license binding. Before starting, obtain the license rebinding procedure for your version and database engine, MariaDB or PostgreSQL, from Sherpa technical support. An administrator performs it after a backup. Remove temporary access to setup.php and temporary files immediately after verification.

Database audit and SIEM#

Database audit may contain SQL queries and sensitive values. Before enabling it, define access permissions, retention, rotation, and free disk space requirements. Enabling audit may require a database restart during a maintenance window. For a separate MariaDB audit source, obtain the plugin setup and monitoring procedures for your version from Sherpa technical support.

Standard SIEM integration requires the complete distribution with orchestrator-siem-exporter. Select the component in the installer for a new installation or in the installation component menu during an update. Before starting, obtain the SIEM installation or update procedure for your version and database engine from Sherpa technical support. The following information covers requirements and verification, not the full installation procedure.

The SIEM receiver must support Syslog over a protected TLS connection, the RFC 5424 format and RFC 6587 octet-counting message framing. These define the event format and transport. The Orchestrator backend establishes the connection.

The SIEM administrator provides:

• the receiver address and port;
• the server name specified in its certificate;
• a trusted certificate authority (CA) certificate so the Orchestrator can verify the receiver;
• a client certificate and private key if the receiver requires mutual certificate verification (mTLS).

The Orchestrator administrator configures:

• SYSLOG_HOST — the receiver address supplied by the SIEM administrator;
• SYSLOG_PORT — the event receiver port;
• SYSLOG_TLS_* — certificate verification and protected connection settings. Check the exact parameter names and values in the installed distribution files;
• service credentials — for the integration component to access the audit source;
• SIEM_DB_FILTER — the filter selecting database audit events to send to SIEM.

An empty SYSLOG_HOST does not enable sending. Data may continue accumulating while audit is enabled. The exporter sends database audit source events accepted by the filter. These are not a copy of every User action in the interface. Detection rules and alerts are configured separately in the SIEM.

To verify delivery, the database administrator runs a safe query using a regular authorized account, and the SIEM administrator searches for the marker in received events:

SELECT 'SHERPA_SIEM_CHECK_001' AS marker;

The filter must allow select. The integration service user is excluded from export. Successful diagnostics without a received test event do not confirm delivery. If the receiver remains unavailable, monitor the queue, logs, and free disk space.