# 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash # 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: ```bash # 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: ```yaml - ./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: ```bash # 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: ```bash # Open the .env file in a text editor nano .env ``` **Be sure to configure the following variables:** ```bash # 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: ```bash # Open the configuration file sudo nano backend/config/config.ini ``` **Configure the following parameters:** ```ini # 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`: ```bash 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. ```bash # 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 \ up -d** - starts the system with the selected DB **docker compose --profile \ --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 ```bash # 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:** ```bash # 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:** ```bash # Stop all services docker compose down # Stop with volume removal (caution!) docker compose down -v ``` **Restarting services:** ```bash # Restart a specific service docker compose restart orchestrator # Restart all services docker compose restart ``` **Viewing resources:** ```bash # 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sherparpa.ru/en/sherpa-rpa/sherpa-orchestrator/ustanovka-sherpa-orchestrator/s-ispolzovaniem-docker/process-ustanovki-sherpa-orchestrator.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.