Instalação do Sherpa Orchestrator no Linux#

Este guia se destina ao administrador de sistemas que realiza uma nova instalação do Sherpa Orchestrator na infraestrutura da empresa. A instalação usa Docker. A instalação sem Docker não é mais suportada.

A instalação do Orchestrator prepara o servidor de gerenciamento. Os Robôs e o Coordenador são instalados separadamente nas máquinas destinadas a eles, conforme os guias de implantação da plataforma.

Preparação do servidor#

A instalação requer um servidor Linux e uma conta de administrador com permissões de sudo. Antes de começar, é necessário confirmar a compatibilidade da distribuição e o conteúdo do pacote fornecido. Os comandos de instalação do Docker dependem da distribuição.

Antes de obter o pacote de distribuição, é necessário preparar:

• recursos do servidor conforme os requisitos da instalação com Docker: CPU com arquitetura x86-64-v2 e pelo menos dois núcleos, 4 GB de RAM e 20 GB de espaço livre. É necessária capacidade adicional para imagens, bancos de dados, Armazenamento e backups conforme a carga;
• um endereço permanente do servidor e um nome de domínio que resolva para esse endereço nos computadores dos usuários e Robôs. A interface web requer acesso HTTPS pela porta 443;
• um certificado para o nome selecionado, sua cadeia de confiança e uma chave privada. A obtenção e a localização dos arquivos são descritas em Instalação e configuração de certificados SSL;
• a opção de implantação do banco de dados. Para um servidor PostgreSQL separado, o administrador do banco prepara o acesso e os parâmetros de conexão conforme o guia de PostgreSQL externo.

No servidor Linux, é necessário instalar e iniciar o Docker Engine e o plugin Docker Compose v2 conforme as instruções do Docker para a distribuição utilizada. O instalador da Sherpa requer Bash versão 4 ou posterior. A geração de certificados e da chave de criptografia requer openssl.

Para a verificação preliminar, são utilizados os seguintes comandos:

bash --version
sudo docker info
sudo docker compose version
openssl version
df -h
free -h

Se o Docker estiver indisponível ou docker compose version falhar, é necessário resolver primeiro o problema do Docker. O utilitário separado docker-compose versão 1 não substitui o Compose v2.

Exemplo: verifique as versões do Docker e do Compose no servidor preparado. O servidor de teste Ubuntu tem 4 GB de RAM alocada e executa Docker 29.9.2 e Compose 5.6.1. O funcionamento nesse ambiente não substitui a confirmação de um sistema operacional compatível.

Preparação dos arquivos fornecidos#

Para a instalação, é necessário obter com o suporte técnico da Sherpa o arquivo de cliente docker_orchestrator_client_files_VERSION.tgz e os arquivos de imagens da versão acordada. As imagens de backend, nginx, WebSocket e do banco selecionado devem corresponder aos arquivos de cliente. Os componentes adicionais requerem imagens próprias.

É necessário extrair o arquivo em um diretório separado para a nova instalação. O local padrão é /opt/SherpaOrchestrator. Nos comandos, substitua /path/to e VERSION pelo caminho e pela versão do arquivo de cliente recebido:

sudo mkdir -p /opt/SherpaOrchestrator
sudo tar -xzf /path/to/docker_orchestrator_client_files_VERSION.tgz -C /opt/SherpaOrchestrator
cd /opt/SherpaOrchestrator

A raiz do pacote extraído deve conter .env, docker-compose.yml e o diretório sh_scripts. Os arquivos de imagens do Docker também devem ser colocados nesse diretório. Antes de iniciar, verifique os arquivos:

sudo test -f .env
sudo test -f docker-compose.yml
sudo test -f sh_scripts/install.sh
sudo test -f sh_scripts/diagnostics.sh

Quando o arquivo existe, test termina sem saída e com o código 0. Se um arquivo estiver ausente, é necessário verificar o diretório de extração e se o pacote está completo. Não substitua arquivos ausentes por arquivos de outra versão nem extraia uma nova instalação sobre uma instalação em execução.

Exemplo: após extrair o pacote 5.9.5, verifique a presença dos quatro arquivos auxiliares. Para uma instalação com MariaDB, compare as versões dos arquivos orchestrator, orchestrator-nginx, orchestrator-websocket e orchestrator-db. Todos os arquivos estão presentes no servidor de teste e as versões das imagens correspondem.

Execução do instalador e configuração das conexões#

Para iniciar a instalação guiada, execute os seguintes comandos a partir da raiz do pacote:

cd /opt/SherpaOrchestrator
sudo chmod +x sh_scripts/*.sh
sudo bash sh_scripts/install.sh

O instalador verifica o ambiente, permite selecionar o banco de dados e os componentes adicionais, verifica os arquivos, carrega as imagens e prepara a configuração. Em seguida, configura .env, prepara o HTTPS e inicia os serviços selecionados.

A opção de banco de dados é escolhida conforme o desenho da implantação:

• MariaDB no Docker — o banco é executado no servidor do Orchestrator com o perfil mariadb;
• PostgreSQL no Docker — o banco é executado no servidor do Orchestrator com o perfil pg;
• MySQL externo — é utilizado um servidor de banco separado, sem contêiner local de banco de dados;
• PostgreSQL externo — é utilizado um servidor PostgreSQL separado, sem contêiner local de banco de dados.

Para conectar os componentes do servidor, é necessário definir os seguintes parâmetros:

• HOST_IP — endereço IP permanente do servidor do Orchestrator acessível pelas máquinas cliente;
• NGINX_DOMAIN_NAME — nome de domínio da interface web coberto pelo certificado;
• ORCHESTRATOR_ENCRYPTION_KEY — chave de criptografia dos dados. Para uma nova instalação, é necessário gerá-la pelo instalador e guardá-la com a configuração protegida e os backups;
• DB_ENGINE — tipo de banco de dados. O instalador define mysql para MariaDB/MySQL ou pgsql para PostgreSQL conforme a opção selecionada;
• MYSQL_PASSWORD — senha de conexão com MariaDB/MySQL. O instalador também grava o valor correspondente de DB_PASSWORD para o contêiner do MariaDB;
• POSTGRES_PASSWORD — senha de conexão com PostgreSQL. Este parâmetro é preenchido apenas quando o PostgreSQL é selecionado;
• MYSQL_HOST — endereço do servidor separado para MySQL externo;
• POSTGRES_HOST — endereço do servidor separado para PostgreSQL externo;
• POSTGRES_PORT — porta do servidor PostgreSQL externo;
• POSTGRES_USER — nome da função de conexão com PostgreSQL externo;
• POSTGRES_DBNAME — nome do banco de destino no servidor PostgreSQL externo.

Os parâmetros do banco selecionado são preenchidos com os valores fornecidos por seu administrador. Para PostgreSQL externo, também é necessário verificar se a função e o banco existem. As permissões necessárias e as opções de preparação são descritas no guia de PostgreSQL externo. Senhas e a chave de criptografia não devem ser incluídas em capturas de tela ou solicitações de suporte.

Na instalação com Docker, a configuração da aplicação vem de .env. Para essa opção, não é necessário editar separadamente backend/config/config.ini ou backend/config/phinx.php.

Os componentes adicionais são selecionados conforme sua finalidade: VNC-proxy para conexões VNC com Robôs, Vault para armazenar segredos e SIEM para enviar eventos de auditoria a um sistema externo. O Vault requer a configuração do armazenamento de segredos. Os componentes do SIEM e a verificação de entrega são descritos em Uso do Docker.

Para HTTPS, são necessários o certificado e a chave privada do domínio selecionado. O instalador prevê a localização de orchestrator.crt e orchestrator.key em nginx/config/certs. As máquinas cliente também devem confiar na autoridade certificadora corporativa.

Exemplo: selecione MariaDB no Docker e desative os perfis opcionais que a implantação escolhida não exige. Conclua o assistente e valide a configuração do Compose. O registro da instalação de teste contém as etapas 0–8 e a mensagem de conclusão, a validação retorna o código 0 e os quatro contêineres estão em execução. Isso não substitui a aceitação funcional.

Verificação da inicialização e primeiro acesso#

Após o término do instalador, é necessário verificar a configuração e o estado dos serviços a partir do diretório de instalação:

cd /opt/SherpaOrchestrator
sudo docker compose config --quiet
sudo docker compose ps
sudo bash sh_scripts/diagnostics.sh

A configuração não deve apresentar erros. Os serviços orchestrator, orchestrator-nginx e orchestrator-websocket devem estar em execução. A composição do banco e dos serviços adicionais depende das opções selecionadas. Com banco externo, a ausência de um contêiner local de banco corresponde ao desenho escolhido.

O diagnóstico verifica os componentes instalados e informa os problemas encontrados. É necessário ler as correções propostas antes de confirmá-las. Um diagnóstico bem-sucedido não substitui a verificação de acesso, Licenças e execução de um Trabalho.

O diagnóstico termina com o código 0 quando os componentes verificados não apresentam observações. O código 1 exige investigação dos resultados. Os registros podem conter erros da primeira inicialização mesmo depois de a causa ter sido corrigida. É necessário comparar o horário da mensagem com o estado atual do serviço. Antes de confirmar uma correção proposta das permissões do Storage, é necessário verificar a política de acesso aos arquivos.

Antes de alterar as permissões de backend/Storage, é necessário identificar o usuário do backend que precisa de acesso de gravação. O usuário do Nginx pode ter outro UID. Verifique o usuário configurado para executar comandos no contêiner com:

sudo docker exec orchestrator id

Na imagem 5.9.5 testada, o comando retorna uid=82(www-data) gid=82(www-data). Esses valores correspondem a essa imagem. Após corrigir as permissões, é necessário verificar o envio e a leitura de um arquivo de teste separado pelo aplicativo. Verificar apenas o modo do diretório não substitui esse teste.

Para o primeiro acesso, é necessário abrir no navegador o endereço HTTPS do domínio selecionado, verificar o certificado e usar as credenciais de administrador fornecidas para a nova instalação. Por exemplo, com NGINX_DOMAIN_NAME=orchestrator.example.org, o endereço da interface web é https://orchestrator.example.org. Substitua o domínio de exemplo pelo nome real do servidor.

Exemplo: entre com a conta de administrador da nova instalação e abra Robôs. O nome do Usuário conectado aparece no canto superior direito. No servidor de teste, essa seção está disponível após a autenticação bem-sucedida.

Após o acesso, é necessário configurar as Licenças conforme Criação de uma nova Licença no Orchestrator. A configuração dos Robôs e a verificação de um Trabalho de teste são realizadas após a preparação do servidor. Abrir a página de acesso, por si só, não confirma que toda a plataforma está pronta.

A aceitação funcional exige uma Licença ativa, um Robô de teste conectado e um Processo de teste publicado. Consulte Criação de um Trabalho com Robô e Processo selecionados. A aceitação inclui um estado final de sucesso do Trabalho e a verificação do resultado esperado do Processo. Salvar um Trabalho ou deixá-lo na fila não confirma sua execução.

Se um serviço terminar ou reiniciar continuamente, use os registros para identificar a causa:

sudo docker compose logs --tail 100 orchestrator orchestrator-nginx orchestrator-websocket

Em caso de erro do banco de dados, é necessário verificar a opção de implantação e os parâmetros de conexão. Em caso de erro de HTTPS, verifique o domínio, o certificado, a chave e a confiança na máquina cliente. Antes de enviar registros ao suporte, é necessário excluir senhas, chaves e outros segredos.

Verificação da inicialização automática e configuração posterior#

Para retomar a operação após a reinicialização do servidor, devem estar configuradas a inicialização automática do Docker e as políticas de reinicialização dos contêineres. O estado do serviço Docker é verificado no servidor Linux:

sudo systemctl is-enabled docker
sudo systemctl is-active docker

As políticas dos contêineres devem ser verificadas com o docker-compose.yml do pacote recebido e as regras de reinicialização do Docker. Após uma reinicialização programada do servidor, é necessário repetir a verificação dos serviços, HTTPS e acesso.

Exemplo: repita as verificações após uma reinicialização programada do servidor. No servidor de teste, o Docker está ativo, os quatro contêineres estão em execução e o HTTPS retorna 200. Isso confirma a recuperação dos componentes do servidor.

Para continuar preparando a plataforma, use os seguintes materiais:

• Autenticação de usuários — configuração dos métodos de acesso após a instalação;
• Backup e recuperação — preservação de bancos de dados, configuração, Armazenamento e segredos;
• Processo de instalação do Sherpa Orchestrator — operações manuais detalhadas da instalação com Docker.