Es

Proceso de instalación de Sherpa Orchestrator#

Para una nueva instalación con base en un servidor separado, consulte instrucciones para PostgreSQL externo.

Descompresión de archivos del cliente#

En esta etapa, descomprimirá el archivo con la actualización de Sherpa Orchestrator y preparará el sistema para la instalación.

Descompresión del archivo de actualización#

El siguiente comando descomprime el archivo en el directorio de instalación.

# Encuentre y descomprima el archivo de actualización (se selecciona automáticamente la versión más reciente)
tar -xvzf "$(ls docker_orchestrator_client_files_*.tgz | sort -V | tail -n 1)"
💡 Comentarios sobre la descompresión del archivo

tar -xvzf "$(ls docker_orchestrator_client_files_*.tgz | sort -V | tail -n 1)" - descomprime el archivo de actualización

  • tar -xvzf - descomprime el archivo con salida detallada
  • ls docker_orchestrator_client_files_*.tgz - encuentra todos los archivos de los archivos de actualización
  • sort -V - ordena las versiones de manera natural (1.0 < 1.1 < 1.10)
  • tail -n 1 - selecciona el archivo más reciente

Resultado esperado: Se descomprimirán los archivos y directorios necesarios para actualizar el sistema.

💡 Instalación automática Después de descomprimir el archivo, puede utilizar el script interactivo en lugar de los pasos manuales a continuación:

sudo ./sh_scripts/install.sh

El script lo guiará a través de todas las etapas de la instalación: selección de la base de datos, descarga de imágenes, configuración de .env, generación de certificados SSL y lanzamiento de contenedores.

Preparación de scripts para su ejecución#

Los scripts de instalación requieren permisos de ejecución.

# Vaya al directorio sh_scripts
# Haga que todos los scripts sean ejecutables
# Regrese al directorio raíz del proyecto
cd sh_scripts && chmod +x *.sh && cd ..
💡 Comentarios sobre la preparación de scripts

cd sh_scripts/ - entra en el directorio con los scripts de instalación

chmod +x *.sh - establece permisos de ejecución para todos los scripts de shell

  • chmod +x - agrega el derecho de ejecución
  • *.sh - todos los archivos con la extensión .sh

cd .. - regresa al directorio raíz del proyecto

Descarga de imágenes de Docker#

El siguiente comando carga las imágenes de los archivos descargados en el almacenamiento local de Docker.

# Ejecute el script de descarga de imágenes de Docker
sudo ./sh_scripts/load_all_docker_images.sh
💡 Comentarios sobre la descarga de imágenes de Docker

sudo ./sh_scripts/load_all_docker_images.sh - ejecuta el script de descarga de imágenes de Docker

Qué hace el script:

  1. Descarga todas las imágenes de Docker de los archivos .tar.gz descargados
  2. Importa las imágenes en el almacenamiento local de Docker
  3. Verifica el éxito de la descarga de todas las imágenes del orquestador

Creación de la configuración del sistema#

El siguiente comando prepara los directorios y archivos de configuración básica.

# Ejecute el script de creación de configuraciones
sudo ./sh_scripts/create_config.sh
💡 Comentarios sobre la creación de la configuración

sudo ./sh_scripts/create_config.sh - ejecuta el script para crear la configuración básica

Qué hace el script:

  1. Crea los directorios necesarios para la configuración
  2. Configura los parámetros básicos del sistema
  3. Prepara la estructura para una configuración posterior

Copia de certificados SSL#

Para garantizar una conexión HTTPS segura, es necesario copiar los certificados SSL:

# Cree un directorio para los certificados (si no existe)
mkdir -p ./nginx/config/certs/

# Renombre y copie el certificado y la clave para su dominio
# Reemplace las rutas por las rutas reales a sus certificados
cp /path/to/your/certificate.crt ./nginx/config/certs/orchestrator.crt
cp /path/to/your/private.key ./nginx/config/certs/orchestrator.key
💡 Comentarios sobre la copia de certificados SSL

mkdir -p ./nginx/config/certs/ - crea un directorio para los certificados

  • -p - crea directorios padres si no existen

cp /path/to/your/certificate.crt ./nginx/config/certs/orchestrator.crt - copia y renombra el certificado cp /path/to/your/private.key ./nginx/config/certs/orchestrator.key - copia y renombra la clave privada

Requisitos para los certificados:

  • El certificado debe ser renombrado a orchestrator.crt
  • La clave privada debe ser renombrada a orchestrator.key
  • Los nombres de los archivos deben coincidir exactamente con los indicados
  • Formato del certificado: .crt o .pem
  • Formato de la clave: .key

Importante: Asegúrese de que los certificados tengan los permisos de acceso correctos:

# Establezca los permisos correctos en los certificados (puede necesitar permisos sudo)
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

ATENCIÓN: Debe obtener los certificados del administrador de red o de su centro de certificación corporativo. Si no tiene estos certificados, puede seguir las instrucciones para obtener certificados de Let's Encrypt u otros centros de certificación.

Configuración de TLS para el protocolo LDAPS (punto opcional)#

Este paso solo es necesario para LDAPS. El archivo /opt/SherpaOrchestrator/backend/config/certs/ca-certificates.crt debe contener los certificados de confianza estándar de la imagen y el certificado de la autoridad del servidor LDAPS. La creación del archivo combinado se describe en "Creación del archivo de certificados de confianza", dentro de "Configuración de certificados para el servidor IMAP (punto opcional)" de este artículo. Si utiliza IMAP y LDAPS, agregue los certificados de ambos servidores.

Para montar el archivo combinado, descomente esta línea en el servicio orchestrator de docker-compose.yml:

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

Configuración de certificados para el servidor IMAP (punto opcional)#

Importante: Este paso se puede omitir si no se van a utilizar Disparadores iniciados por correo electrónico.

Al comprobar el correo, el Orquestador se conecta al servidor de correo mediante una conexión cifrada y verifica su certificado. Los certificados de los servicios públicos de correo se verifican sin configuración adicional.

Si el certificado del servidor de correo fue emitido por una autoridad de certificación corporativa o es autofirmado, es necesario agregar el certificado raíz a los certificados de confianza del Orquestador. De lo contrario, el Disparador no puede comprobar el correo y en la pantalla Auditoría aparece un mensaje similar al siguiente:

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

Importante: El certificado se verifica incluso si la casilla "Use SSL" no está marcada en la configuración del Disparador. Si el servidor de correo admite STARTTLS, el Orquestador activa automáticamente el cifrado de la conexión. Los nombres de los elementos de la interfaz de esta sección corresponden a la interfaz en inglés.

Importante: El Orquestador no utiliza los certificados copiados en ./backend/config/certs/imap_certs. Es necesario realizar los pasos que se describen a continuación.

Todos los comandos se ejecutan desde /opt/SherpaOrchestrator.

Comprobación del certificado del servidor de correo#

Antes de realizar la configuración, se puede comprobar el certificado del servidor de correo con la lista estándar de certificados de confianza de la imagen. En los comandos es necesario sustituir mail.company.ru por el valor del campo "Mail server" e indicar el puerto configurado en el Disparador. IMAP con la casilla "Use SSL" marcada suele utilizar el puerto 993, mientras que STARTTLS utiliza el puerto 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
💡 Notas sobre la comprobación del certificado

docker run --rm --entrypoint openssl orchestrator - ejecuta openssl desde la imagen del Orquestador con su lista estándar de certificados de confianza

s_client -connect mail.company.ru:993 - se conecta al servidor de correo y muestra sus certificados. Se utilizan los siguientes parámetros:

  • -servername — envía el nombre del servidor de correo al establecer la conexión TLS (SNI), pero no comprueba si coincide con el certificado
  • -verify_hostname — comprueba que el certificado se haya emitido para el nombre del servidor indicado en la configuración del Disparador
  • -starttls imap — activa el cifrado de la conexión en el puerto 143
  • -showcerts — muestra la cadena completa de certificados

El resultado de la verificación aparece al final de la salida, en la línea Verify return code. Los valores posibles son:

  • 0 (ok) — la lista estándar de la imagen permite validar el certificado y el nombre del servidor coincide con el certificado. Se puede omitir la adición de un certificado si no hay un archivo personalizado de certificados de confianza montado. Si el contenedor está en ejecución con un archivo montado, también es necesaria la comprobación de la sección "Comprobación de la conexión"
  • 18, 19, 20 o 21 — se necesita el certificado raíz de la autoridad de certificación. Su nombre aparece en la línea i: del último certificado de la cadena
  • 62 (hostname mismatch) — el nombre del servidor no coincide con el certificado. Agregar un certificado raíz no resuelve este error

Preparación del certificado#

El certificado raíz de la autoridad de certificación que emitió el certificado del servidor de correo se puede obtener del administrador de la red. Si el servidor de correo no envía los certificados intermedios, también es necesario obtenerlos. Si el certificado del servidor de correo es autofirmado, se utiliza ese mismo certificado.

El certificado debe estar en formato de texto PEM: el archivo comienza con -----BEGIN CERTIFICATE-----. Es necesario convertir los certificados en formato binario DER, por ejemplo, un archivo .cer exportado desde Windows:

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

Importante: El certificado del Orquestador orchestrator.crt y las claves privadas no son adecuados para este paso.

Creación del archivo de certificados de confianza#

El archivo de certificados de confianza debe contener la lista estándar de certificados de la imagen del Orquestador y el certificado raíz de la autoridad de certificación:

Antes de crear el archivo, guarde una copia del ca-certificates.crt existente con un nombre libre. El nuevo archivo debe incluir los certificados estándar de la imagen y todos los certificados de confianza personalizados, incluidos los de LDAPS. El comando siguiente sobrescribe el archivo; prepare antes el conjunto completo.

# Выгрузите стандартный список доверенных сертификатов из образа Оркестратора
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
💡 Notas sobre la creación del archivo de certificados de confianza

docker run --rm --entrypoint cat orchestrator /etc/ssl/certs/ca-certificates.crt - guarda la lista estándar de certificados de confianza de la imagen del Orquestador. Sin ella, el Orquestador dejará de confiar en los servidores públicos

echo >> ./backend/config/certs/ca-certificates.crt - agrega un salto de línea para evitar que los certificados del archivo queden unidos

cat /path/to/root-ca.crt >> ./backend/config/certs/ca-certificates.crt - agrega el certificado al final del archivo. Si hay varios certificados, como uno raíz y otro intermedio, es necesario repetir el comando para cada uno

Requisitos del archivo:

  • El archivo debe llamarse ca-certificates.crt
  • El archivo debe encontrarse en ./backend/config/certs/
  • El archivo sustituye por completo la lista de certificados de confianza del contenedor del Orquestador

Importante: Si ya se realizó el paso de configuración de TLS para LDAPS, el comando de exportación sobrescribirá ca-certificates.crt. En este caso, también es necesario agregar al archivo el certificado raíz del servidor LDAPS.

Montaje del archivo en el Orquestador#

En docker-compose.yml, es necesario descomentar la siguiente línea del servicio orchestrator:

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

Si la línea ya se descomentó al configurar LDAPS, este paso se puede omitir. No es necesario modificar las líneas que contienen imap_certs.

Si el Orquestador aún no se ha iniciado, se puede continuar con el siguiente paso de la instalación. Si ya está en ejecución, es necesario volver a crear el contenedor:

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

Importante: El comando docker compose restart y el reinicio del servidor no aplican los cambios de docker-compose.yml.

Comprobación de la conexión#

Después de iniciar el Orquestador, se pueden comprobar el certificado y el nombre del servidor de correo utilizando el archivo montado de certificados de confianza. Es necesario elegir el comando correspondiente al modo de conexión del Disparador y sustituir el nombre del servidor y el puerto por los valores de su configuración:

# 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

La salida debe contener la línea Verify return code: 0 (ok). Esto confirma la verificación del certificado y del nombre del servidor, pero no comprueba las credenciales del buzón. Si no se establece la conexión, es necesario comprobar el mensaje de error, la dirección, el puerto y la accesibilidad del servidor desde el contenedor. La utilidad openssl s_client puede terminar con el código 0 incluso si falla la verificación del certificado, por lo que es necesario comprobar la línea Verify return code.

A continuación, en la configuración del Disparador, en la pestaña "Email", se puede hacer clic en el botón "Test getting email". Si la conexión se establece correctamente, aparece la notificación "Test succeeded, received N messages".

Importante: El valor de "Mail server" debe coincidir con el certificado del servidor, por ejemplo mail.company.ru. Si el certificado solo está emitido para un dominio, la conexión por dirección IP produce hostname mismatch.

Posibles errores#

Los errores de conexión al servidor de correo aparecen en la pantalla Auditoría. Los errores de certificado más habituales son:

  • unable to get local issuer certificate, unable to verify the first certificate, self-signed certificate — falta el certificado necesario en ca-certificates.crt, o el archivo no está montado en el contenedor del Orquestador
  • hostname mismatch — el valor de "Mail server" en la configuración del Disparador no coincide con el nombre del certificado

Selección de la configuración de la base de datos#

Para una base integrada, seleccione MariaDB (DB_ENGINE=mysql, perfil mariadb) o PostgreSQL (DB_ENGINE=pgsql, perfil pg). Configure solo el motor seleccionado. Para una base externa, indique la dirección del servidor separado y no active los perfiles locales de base de datos.

Configuración de variables de entorno#

Configure la dirección del servidor, el dominio y los parámetros de la base seleccionada. Los valores your_server_ip, your_domain_name y las contraseñas siguientes son ejemplos y deben sustituirse por los datos de la instalación. Los parámetros de VNC solo son necesarios al utilizar ese perfil.

# Abra el archivo .env en un editor de texto
nano .env

Parámetros del servidor, la base seleccionada y VNC:

# Dirección IP del servidor (cámbielo por su dirección IP real o dominio)
HOST_IP=your_server_ip

# Nombre de dominio que utilizará NGINX
NGINX_DOMAIN_NAME=your_domain_name

# Configuraciones de VNC
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

# Tipo de base de datos: mysql o pgsql
DB_ENGINE=mysql

# Configuraciones de MySQL (se utiliza cuando DB_ENGINE=mysql)
MYSQL_HOST=orchestrator-db
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=mysql-password
MYSQL_DB=orchestrator

# También establezca la contraseña para el contenedor de MariaDB (debe coincidir con MYSQL_PASSWORD)
DB_PASSWORD=mysql-password

# Configuraciones de PostgreSQL (se utiliza cuando DB_ENGINE=pgsql)
POSTGRES_HOST=orchestrator-pg
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres-password
POSTGRES_DBNAME=postgres
POSTGRES_SCHEMA_NAME=orchestrator
💡 Comentarios sobre la configuración de variables de entorno

HOST_IP — Dirección IP o nombre de dominio del servidor, por el cual el sistema es accesible desde el exterior. Debe ser una IP estática o un dominio correctamente configurado.

NGINX_DOMAIN_NAME — Dominio para la interfaz web (por ejemplo, orchestrator.example.com). Generalmente coincide con el dominio en el certificado SSL.

DB_ENGINE — seleccione mysql para MariaDB o pgsql para PostgreSQL. Este valor determina qué conjunto de variables de conexión se utilizará.

MYSQL_PASSWORD / DB_PASSWORD — contraseña para MySQL/MariaDB. Ambos valores deben coincidir: MYSQL_PASSWORD es utilizado por la aplicación, DB_PASSWORD — por el contenedor de la base de datos.

POSTGRES_PASSWORD — contraseña para PostgreSQL. Es utilizada tanto por el contenedor de la base de datos como por la aplicación.

Todos los parámetros de configuración (base de datos, correo, LDAP, proxy, etc.) son leídos directamente por la aplicación desde las variables de entorno del archivo .env. No es necesario editar backend/config/config.ini o backend/config/phinx.php — ya están configurados para trabajar a través de .env.

Si es necesario, configure parámetros adicionales en .env:

# Configuración del servidor de correo (SMTP)
SMTP_SERVER=smtp.example.com
SMTP_PORT=25
SMTP_SECURE=tls
SMTP_LOGIN=
SMTP_PASSWORD=
SMTP_FROM=Orchestrator
SMTP_FROM_EMAIL=

# Configuración de LDAP (opcional)
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

# Otras configuraciones
SESSION_LAST_ACTIVITY_TIMEOUT=30
STORE_LOGS_DAYS=180
STORE_AUDIT_DAYS=180

Los parámetros de LDAP, los modos StartTLS y LDAPS, así como el callback HTTPS obligatorio de OpenID se describen en instrucciones sobre la autorización de usuarios. Para OpenID, utilice la dirección /api/v1/system/oauth_hook; la antigua ruta /api/gui/system/oAuthHook no es adecuada.

Inicio del sistema#

Ejecute un comando para la base seleccionada y los servicios adicionales. Para una base externa, utilice docker compose up -d sin los perfiles mariadb ni pg.

# Inicie el sistema con el perfil de base de datos deseado
# Opción 1: MariaDB
docker compose --profile mariadb up -d

# Opción 2: PostgreSQL
docker compose --profile pg up -d

# Si se necesita VNC (opcional), agregue el perfil vnc:
# Opción 1: MariaDB + VNC
docker compose --profile mariadb --profile vnc up -d

# Opción 2: PostgreSQL + VNC
docker compose --profile pg --profile vnc up -d

# Si se necesita Vault (opcional), agregue el perfil vault:
# Opción 1: MariaDB + Vault
docker compose --profile mariadb --profile vault up -d

# Opción 2: PostgreSQL + Vault
docker compose --profile pg --profile vault up -d

# Combinación de perfiles: MariaDB + VNC + Vault
docker compose --profile mariadb --profile vnc --profile vault up -d
💡 Comentarios sobre el inicio del sistema

docker compose --profile <mariadb|pg> up -d - inicia el sistema con la base de datos seleccionada

--profile vnc - el perfil VNC es opcional, inicia el servicio orchestrator-vnc-proxy

  • Solo es necesario si los robots utilizan VNC para controlar el escritorio
  • Agregue a cualquier combinación de perfiles

docker compose --profile <mariadb|pg> --profile vault up -d - inicia el sistema con Vault

  • El perfil vault es opcional y se incluye solo si es necesario
  • La configuración posterior se describe en Uso de Vault.

Qué hace el script:

  1. Inicia los servicios del orquestador a través de Docker Compose
  2. Activa solo el contenedor de la base de datos seleccionada según el perfil (mariadb o pg)
  3. Configura la red y los volúmenes
  4. Realiza migraciones de la base de datos si es necesario
  5. Inicia los servicios en segundo plano

Verificación del estado de inicio#

Los siguientes comandos comprueban el estado de los servicios y los mensajes de inicio.

# Verifique el estado de todos los contenedores en ejecución
docker compose ps

# Vea los registros del sistema
docker compose logs orchestrator

# Monitoreo de registros en tiempo real
docker compose logs -f orchestrator
💡 Comentarios sobre la verificación del estado

docker compose ps - muestra el estado de todos los contenedores

docker compose logs orchestrator - muestra los registros del servicio principal

docker compose logs -f orchestrator - sigue los registros en tiempo real

  • -f - follow (seguir nuevos mensajes)

Tras un inicio correcto, orchestrator, orchestrator-nginx y orchestrator-websocket tienen el estado Up. La base integrada también inicia orchestrator-db u orchestrator-pg; una base externa no requiere un contenedor local de base de datos. Los servicios adicionales dependen de los perfiles seleccionados. El puerto HTTPS lo publica orchestrator-nginx, no el contenedor backend orchestrator.

Verificación de la disponibilidad del sistema#

Verificación de la interfaz web:

# Verifique la disponibilidad de HTTPS (reemplace con su dominio/IP)
curl -I https://your-domain-or-ip

# Respuesta esperada: HTTP/2 200 o redirección

Gestión del sistema#

Detener el sistema:

# Detenga todos los servicios
docker compose down

El comando docker compose down conserva los volúmenes de datos con nombre. La opción -v elimina estos volúmenes y su contenido, por lo que no debe utilizarse para una parada normal.

Reiniciar servicios:

# Reinicie un servicio específico
docker compose restart orchestrator

# Reinicie todos los servicios
docker compose restart

Ver recursos:

# Verifique el uso de recursos por los contenedores
docker stats

Posibles problemas al iniciar:#

Para diagnosticar un error, compruebe:

  • Los contenedores no se inician — mensajes de docker compose logs.
  • Problemas de red — disponibilidad de los puertos 80 y 443, además de 5000 y 6080–6100 al utilizar VNC.
  • Errores de conexión a la base de datos — parámetros de .env y accesibilidad de la base.
  • Problemas con el dominio — HOST_IP y configuración de DNS.

Después de un inicio y prueba exitosos del sistema, la instalación de Sherpa Orchestrator está completa. El sistema estará disponible a través de HTTPS en el dominio o dirección IP configurada.