Processo de instalação do Sherpa Orchestrator#

Para uma nova instalação com base em um servidor separado, consulte instruções para PostgreSQL externo.

Descompactação dos arquivos do cliente#

Nesta etapa, você descompactará o arquivo com a atualização do Sherpa Orchestrator e preparará o sistema para a instalação.

Descompactação do arquivo de atualização#

O comando a seguir descompacta o arquivo no diretório de instalação.

# Encontre e descompacte o arquivo de atualização (a versão mais recente é escolhida automaticamente)
tar -xvzf "$(ls docker_orchestrator_client_files_*.tgz | sort -V | tail -n 1)"

💡 Instalação automática Após descompactar o arquivo, você pode usar o script interativo em vez dos passos manuais abaixo:

Copiar

sudo ./sh_scripts/install.sh

O script guiará você por todas as etapas da instalação: seleção do banco de dados, download de imagens, configuração do .env, geração de certificados SSL e inicialização de contêineres.

Preparação dos scripts para execução#

Os scripts de instalação exigem permissão de execução.

# Vá para o diretório sh_scripts
# Torne todos os scripts executáveis
# Volte para o diretório raiz do projeto
cd sh_scripts && chmod +x *.sh && cd ..

Download das imagens Docker#

O comando a seguir carrega as imagens dos arquivos baixados no armazenamento local do Docker.

# Execute o script de download das imagens Docker
sudo ./sh_scripts/load_all_docker_images.sh

Criação da configuração do sistema#

O comando a seguir prepara os diretórios e arquivos da configuração básica.

# Execute o script de criação de configurações
sudo ./sh_scripts/create_config.sh

Cópia dos certificados SSL#

Para garantir uma conexão HTTPS segura, é necessário copiar os certificados SSL:

# Crie o diretório para os certificados (se não existir)
mkdir -p ./nginx/config/certs/

# Renomeie e copie o certificado e a chave para seu domínio
# Substitua os caminhos pelos caminhos reais dos seus certificados
cp /path/to/your/certificate.crt ./nginx/config/certs/orchestrator.crt
cp /path/to/your/private.key ./nginx/config/certs/orchestrator.key

Importante: Certifique-se de que os certificados tenham as permissões corretas:

# Defina as permissões corretas para os certificados (pode ser necessário usar 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

ATENÇÃO: Os certificados devem ser obtidos com o administrador da rede ou no seu centro corporativo de certificação. Caso não tenha esses certificados, você pode seguir as instruções para obter certificados Let's Encrypt ou de outros centros de certificação.

Configuração do TLS para o protocolo LDAPS (opcional)#

Esta etapa é necessária apenas para LDAPS. O arquivo /opt/SherpaOrchestrator/backend/config/certs/ca-certificates.crt deve conter os certificados confiáveis padrão da imagem e o certificado da autoridade do servidor LDAPS. A montagem do arquivo combinado está descrita em "Criação do arquivo de certificados confiáveis", na seção "Configuração dos certificados para o servidor IMAP (opcional)" deste artigo. Ao usar IMAP e LDAPS, adicione os certificados dos dois servidores.

Para montar o arquivo combinado, descomente esta linha no serviço orchestrator de docker-compose.yml:

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

Configuração dos certificados para o servidor IMAP (opcional)#

Importante: Esta etapa pode ser ignorada se não forem utilizados Gatilhos iniciados por e-mail.

Ao verificar o e-mail, o Orquestrador se conecta ao servidor de e-mail por uma conexão criptografada e verifica o certificado do servidor. Os certificados dos serviços públicos de e-mail são verificados sem configuração adicional.

Se o certificado do servidor de e-mail tiver sido emitido por uma autoridade certificadora corporativa ou for autoassinado, será necessário adicionar o certificado raiz aos certificados confiáveis do Orquestrador. Caso contrário, o Gatilho não consegue verificar o e-mail e uma mensagem semelhante à seguinte aparece na tela Auditoria:

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

Importante: O certificado é verificado mesmo quando a caixa de seleção "Use SSL" não está marcada nas configurações do Gatilho. Se o servidor de e-mail oferecer suporte a STARTTLS, o Orquestrador habilitará a criptografia da conexão automaticamente. Os nomes dos elementos de interface nesta seção correspondem à interface em inglês.

Importante: O Orquestrador não utiliza os certificados copiados para ./backend/config/certs/imap_certs. É necessário seguir as etapas descritas abaixo.

Todos os comandos são executados em /opt/SherpaOrchestrator.

Verificação do certificado do servidor de e-mail#

Antes da configuração, é possível verificar o certificado do servidor de e-mail com a lista padrão de certificados confiáveis da imagem. Nos comandos, é necessário substituir mail.company.ru pelo valor do campo "Mail server" e indicar a porta configurada no Gatilho. O IMAP com a caixa "Use SSL" marcada geralmente utiliza a porta 993, enquanto o STARTTLS utiliza a porta 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

Preparação do certificado#

O certificado raiz da autoridade certificadora que emitiu o certificado do servidor de e-mail pode ser obtido com o administrador da rede. Se o servidor de e-mail não enviar os certificados intermediários, também será necessário obtê-los. Se o certificado do servidor de e-mail for autoassinado, será utilizado o próprio certificado.

O certificado deve estar no formato de texto PEM: o arquivo começa com -----BEGIN CERTIFICATE-----. Um certificado no formato binário DER, como um arquivo .cer exportado do Windows, precisa ser convertido:

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

Importante: O certificado do Orquestrador orchestrator.crt e as chaves privadas não são adequados para esta etapa.

Criação do arquivo de certificados confiáveis#

O arquivo de certificados confiáveis deve conter a lista padrão de certificados da imagem do Orquestrador e o certificado raiz da autoridade certificadora:

Antes de criar o arquivo, salve uma cópia do ca-certificates.crt existente com um nome ainda não utilizado. O novo arquivo deve conter os certificados padrão da imagem e todos os certificados confiáveis personalizados, incluindo os usados para LDAPS. O comando abaixo sobrescreve o arquivo; prepare antes o 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

Importante: Se a etapa de configuração de TLS para LDAPS já tiver sido concluída, o comando de exportação sobrescreverá ca-certificates.crt. Nesse caso, também será necessário adicionar ao arquivo o certificado raiz do servidor LDAPS.

Montagem do arquivo no Orquestrador#

Em docker-compose.yml, é necessário descomentar a seguinte linha do serviço orchestrator:

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

Se a linha já tiver sido descomentada durante a configuração de LDAPS, esta etapa poderá ser ignorada. Não é necessário alterar as linhas que contêm imap_certs.

Se o Orquestrador ainda não tiver sido iniciado, a instalação poderá continuar na próxima etapa. Se já estiver em execução, será necessário recriar o contêiner:

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

Importante: O comando docker compose restart e a reinicialização do servidor não aplicam as alterações de docker-compose.yml.

Verificação da conexão#

Após iniciar o Orquestrador, é possível verificar o certificado e o nome do servidor de e-mail utilizando o arquivo montado de certificados confiáveis. É necessário escolher o comando correspondente ao modo de conexão do Gatilho e substituir o nome do servidor e a porta pelos valores das configurações:

# 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

A saída deve conter a linha Verify return code: 0 (ok). Isso confirma a verificação do certificado e do nome do servidor, mas não verifica as credenciais da caixa de correio. Se a conexão não for estabelecida, será necessário verificar a mensagem de erro, o endereço, a porta e a acessibilidade do servidor a partir do contêiner. O utilitário openssl s_client pode terminar com o código 0 mesmo quando a verificação do certificado falha, portanto é necessário verificar a linha Verify return code.

Em seguida, nas configurações do Gatilho, na aba "Email", é possível clicar no botão "Test getting email". Se a conexão for bem-sucedida, será exibida a notificação "Test succeeded, received N messages".

Importante: O valor de "Mail server" deve corresponder ao certificado do servidor, por exemplo mail.company.ru. Se o certificado tiver sido emitido apenas para um domínio, a conexão pelo endereço IP resulta em hostname mismatch.

Possíveis erros#

Os erros de conexão com o servidor de e-mail aparecem na tela Auditoria. Os erros de certificado mais comuns são:

• unable to get local issuer certificate, unable to verify the first certificate, self-signed certificate — o certificado necessário não está em ca-certificates.crt, ou o arquivo não está montado no contêiner do Orquestrador
• hostname mismatch — o valor de "Mail server" nas configurações do Gatilho não corresponde ao nome no certificado

Seleção da configuração do banco de dados#

Para um banco integrado, escolha MariaDB (DB_ENGINE=mysql, perfil mariadb) ou PostgreSQL (DB_ENGINE=pgsql, perfil pg). Configure apenas o mecanismo selecionado. Para um banco externo, informe o endereço do servidor separado e não habilite os perfis locais do banco.

Configuração das variáveis de ambiente#

Configure o endereço do servidor, o domínio e os parâmetros do banco selecionado. Os valores your_server_ip, your_domain_name e as senhas abaixo são exemplos e devem ser substituídos pelos dados da instalação. Os parâmetros do VNC são necessários apenas ao usar esse perfil.

# Abra o arquivo .env em um editor de texto
nano .env

Parâmetros do servidor, do banco selecionado e do VNC:

# Endereço IP do servidor (substitua pelo seu endereço IP real ou domínio)
HOST_IP=your_server_ip

# Nome de domínio que será usado pelo NGINX
NGINX_DOMAIN_NAME=your_domain_name

# Configurações do 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 banco de dados: mysql ou pgsql
DB_ENGINE=mysql

# Configurações do MySQL (usado quando DB_ENGINE=mysql)
MYSQL_HOST=orchestrator-db
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=mysql-password
MYSQL_DB=orchestrator

# Também defina a senha para o contêiner MariaDB (deve coincidir com MYSQL_PASSWORD)
DB_PASSWORD=mysql-password

# Configurações do PostgreSQL (usado quando DB_ENGINE=pgsql)
POSTGRES_HOST=orchestrator-pg
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres-password
POSTGRES_DBNAME=postgres
POSTGRES_SCHEMA_NAME=orchestrator

Se necessário, configure parâmetros adicionais no .env:

# Configurações do servidor de e-mail (SMTP)
SMTP_SERVER=smtp.example.com
SMTP_PORT=25
SMTP_SECURE=tls
SMTP_LOGIN=
SMTP_PASSWORD=
SMTP_FROM=Orchestrator
SMTP_FROM_EMAIL=

# Configurações 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

# Outras configurações
SESSION_LAST_ACTIVITY_TIMEOUT=30
STORE_LOGS_DAYS=180
STORE_AUDIT_DAYS=180

Os parâmetros LDAP, os modos StartTLS e LDAPS, bem como o callback HTTPS obrigatório do OpenID estão descritos na instrução sobre autorização de usuários. Para OpenID, use o endereço /api/v1/system/oauth_hook; o caminho antigo /api/gui/system/oAuthHook não é adequado.

Iniciando o sistema#

Execute um comando para o banco selecionado e os serviços adicionais. Para um banco externo, use docker compose up -d sem os perfis mariadb ou pg.

# Inicie o sistema com o perfil de banco de dados desejado
# Opção 1: MariaDB
docker compose --profile mariadb up -d

# Opção 2: PostgreSQL
docker compose --profile pg up -d

# Se precisar de VNC (opcional), adicione o perfil vnc:
# Opção 1: MariaDB + VNC
docker compose --profile mariadb --profile vnc up -d

# Opção 2: PostgreSQL + VNC
docker compose --profile pg --profile vnc up -d

# Se precisar de Vault (opcional), adicione o perfil vault:
# Opção 1: MariaDB + Vault
docker compose --profile mariadb --profile vault up -d

# Opção 2: PostgreSQL + Vault
docker compose --profile pg --profile vault up -d

# Combinação de perfis: MariaDB + VNC + Vault
docker compose --profile mariadb --profile vnc --profile vault up -d

Verificando o status da inicialização#

Os comandos a seguir verificam o status dos serviços e as mensagens de inicialização.

# Verifique o status de todos os contêineres em execução
docker compose ps

# Veja os logs do sistema
docker compose logs orchestrator

# Monitoramento dos logs em tempo real
docker compose logs -f orchestrator

Após uma inicialização bem-sucedida, orchestrator, orchestrator-nginx e orchestrator-websocket apresentam o status Up. Um banco integrado também inicia orchestrator-db ou orchestrator-pg; um banco externo não exige um contêiner local do banco. Os serviços adicionais dependem dos perfis selecionados. A porta HTTPS é publicada por orchestrator-nginx, não pelo contêiner backend orchestrator.

Verificando a disponibilidade do sistema#

Verificando a interface web:

# Verifique a disponibilidade HTTPS (substitua pelo seu domínio/IP)
curl -I https://your-domain-or-ip

# Resposta esperada: HTTP/2 200 ou redirecionamento

Gerenciando o sistema#

Parando o sistema:

# Pare todos os serviços
docker compose down

O comando docker compose down preserva os volumes de dados nomeados. A opção -v exclui esses volumes e seu conteúdo, portanto não deve ser usada em uma parada normal.

Reiniciando os serviços:

# Reinicie um serviço específico
docker compose restart orchestrator

# Reinicie todos os serviços
docker compose restart

Visualizando recursos:

# Verifique o uso de recursos pelos contêineres
docker stats

Possíveis problemas ao iniciar:#

Para diagnosticar uma falha, verifique:

• Contêineres não iniciam — mensagens de docker compose logs.
• Problemas de rede — disponibilidade das portas 80 e 443, além de 5000 e 6080–6100 ao usar VNC.
• Erros de conexão com o banco — parâmetros do .env e disponibilidade do banco.
• Problemas com o domínio — HOST_IP e configurações de DNS.

Após a inicialização e teste bem-sucedidos do sistema, a instalação do Sherpa Orchestrator está concluída. O sistema estará disponível via HTTPS no domínio ou endereço IP configurado.