Pt

Processo de instalação do Sherpa Orchestrator#

Instalação do Sherpa Orchestrator#

Extração dos arquivos de cliente#

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

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

# Encontre e extraia o arquivo de atualização (a versão mais recente é selecionada automaticamente)
tar -xvzf "$(ls docker_orchestrator_client_files_*.tgz | sort -V | tail -n 1)"
💡 Notas sobre a extração do arquivo

tar -xvzf "$(ls docker_orchestrator_client_files_*.tgz | sort -V | tail -n 1)" - extrai o arquivo de atualização

  • tar -xvzf - extrai o arquivo com saída detalhada
  • ls docker_orchestrator_client_files_*.tgz - encontra todos os arquivos de atualização
  • sort -V - ordena as versões de forma natural (1.0 < 1.1 < 1.10)
  • tail -n 1 - seleciona o arquivo mais recente

Resultado esperado: Os arquivos e diretórios necessários para a atualização do sistema serão extraídos.

Resultado esperado: Os arquivos de atualização do Sherpa Orchestrator serão extraídos.

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

# Navegue até o diretório sh_scripts
# Torne todos os scripts executáveis
# Retorne ao diretório raiz do projeto
cd sh_scripts && chmod +x *.sh && cd ..
💡 Notas sobre a preparação dos scripts

cd sh_scripts/ - navega para o diretório com os scripts de instalação

*chmod +x .sh - define permissões de execução para todos os scripts shell

  • chmod +x - adiciona permissão de execução
  • *.sh - todos os arquivos com extensão .sh

cd .. - retorna ao diretório raiz do projeto

Carregamento das imagens Docker#

# Execute o script de carregamento de imagens Docker
sudo ./sh_scripts/load_all_docker_images.sh
💡 Notas sobre o carregamento das imagens Docker

sudo ./sh_scripts/load_all_docker_images.sh - executa o script de carregamento de imagens Docker

O que o script faz:

  1. Carrega todas as imagens Docker dos arquivos .tar.gz baixados
  2. Importa as imagens para o registro Docker local
  3. Verifica o carregamento bem-sucedido de todas as imagens do orchestrator

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

# Execute o script de criação de configuração
sudo ./sh_scripts/create_config.sh
💡 Notas sobre a criação de configuração

sudo ./sh_scripts/create_config.sh - executa o script de criação da configuração base

O que o script faz:

  1. Cria os diretórios necessários para a configuração
  2. Define os parâmetros básicos do sistema
  3. Prepara a estrutura para configuração posterior

Cópia dos certificados SSL#

Para garantir uma conexão HTTPS segura, os certificados SSL devem ser copiados:

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

# Renomeie e copie o certificado e a chave para o 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
💡 Notas sobre a cópia dos certificados SSL

mkdir -p ./nginx/config/certs/ - cria o diretório de certificados

  • -p - cria os diretórios pai se não existirem

cp /path/to/your/certificate.crt ./nginx/config/certs/orchestrator.crt - copia e renomeia o certificado cp /path/to/your/private.key ./nginx/config/certs/orchestrator.key - copia e renomeia a chave privada

Requisitos dos certificados:

  • O certificado deve ser renomeado para orchestrator.crt
  • A chave privada deve ser renomeada para orchestrator.key
  • Os nomes dos arquivos devem corresponder exatamente aos especificados
  • Formato do certificado: .crt ou .pem
  • Formato da chave: .key

Importante: Certifique-se de que os certificados têm as permissões corretas:

# Defina as permissões corretas nos certificados (pode ser necessário sudo)
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

ATENÇÃO: Os certificados devem ser obtidos junto ao administrador de rede ou à sua autoridade certificadora corporativa. Caso não disponha desses certificados, pode utilizar as instruções para obter certificados do Let's Encrypt ou de outras autoridades certificadoras.

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

Importante: Se o suporte a LDAPS não for necessário, pule este passo.

Copie o certificado rootCA com o nome ca-certificates.crt para o diretório /opt/SherpaOrchestrator/backend/config/certs/

No arquivo docker-compose.yml, descomente a linha:

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

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

Importante: Se não planeja usar Triggers com lançamento por e-mail ou seu servidor de e-mail não requer certificados, pule este passo.

Copie os certificados IMAP para a pasta /opt/SherpaOrchestrator/backend/config/certs/imap_certs

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

Use o arquivo compose unificado e selecione o banco de dados por perfil:

# Copie o arquivo compose cliente combinado
cp docker-compose.client.yml docker-compose.yml
💡 Notas sobre a seleção da configuração de BD

cp docker-compose.client.yml docker-compose.yml - copia a configuração combinada para lançamento cliente

Recomendações:

  • Para MariaDB, execute o perfil mariadb
  • Para PostgreSQL, execute o perfil pg
  • O diretório de trabalho deve conter o arquivo final docker-compose.yml

Configuração das variáveis de ambiente#

Abra o arquivo .env e configure os parâmetros principais:

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

Certifique-se de configurar as seguintes variáveis:

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

# Nome de domínio que o NGINX utilizará (geralmente coincide com o seu domínio principal)
NGINX_DOMAIN_NAME=your_domain_name

# Senha do banco de dados MySQL (se diferente do padrão "mysql-password")
DB_PASSWORD=mysql-password

# Senha do banco de dados PostgreSQL (se diferente do padrão "postgres-password")
POSTGRES_PASSWORD=postgres-password

# Configurações 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
💡 Notas sobre a configuração das variáveis de ambiente

nano .env - abre o arquivo de variáveis de ambiente

  • .env - arquivo com variáveis de ambiente para Docker Compose

HOST_IP - parâmetro de importância crítica

  • Especifique o endereço IP real ou o nome de domínio do seu servidor
  • Este é o endereço pelo qual o sistema estará acessível externamente
  • Deve ser um IP estático ou um domínio corretamente configurado

NGINX_DOMAIN_NAME - nome de domínio para a interface web

  • Especifique o domínio que os usuários usarão para acessar o Sherpa Orchestrator (por exemplo, orchestrator.example.com)
  • Geralmente coincide com o domínio especificado no certificado SSL

DB_PASSWORD - senha do banco de dados MySQL

  • Padrão: mysql-password
  • Altere para uma senha forte se necessário

POSTGRES_PASSWORD - senha do banco de dados PostgreSQL

  • Padrão: postgres-password
  • Altere para uma senha forte se necessário

Configuração do banco de dados#

Abra o arquivo de configuração e configure os parâmetros do banco de dados e do servidor de e-mail:

# Abra o arquivo de configuração
sudo nano backend/config/config.ini

Configure os seguintes parâmetros:

# Configurações do banco de dados (para MySQL - padrão)
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

# Configurações do banco de dados (para PostgreSQL - descomente se estiver usando PostgreSQL)
;database_engine=pgsql
;database_host=orchestrator-pg
;database_port=5432
;database_user=postgres
;database_password=postgres-password

Importante: Se você alterou as senhas no arquivo .env (DB_PASSWORD ou POSTGRES_PASSWORD), certifique-se de que as senhas correspondentes no config.ini coincidam!

Configuração do phinx.php (migrações de BD)#

O arquivo backend/config/phinx.php é usado pelo Phinx para executar migrações ao iniciar o contêiner. As senhas nele devem coincidir com as de .env e config.ini:

sudo nano backend/config/phinx.php

Na seção environments, defina as mesmas senhas que no config.ini:

  • Para MySQL: no bloco 'mysql', o parâmetro 'pass' deve coincidir com DB_PASSWORD de .env (padrão mysql-password).
  • Para PostgreSQL: no bloco 'pgsql', o parâmetro 'pass' deve coincidir com POSTGRES_PASSWORD de .env (padrão postgres-password).

Se as senhas não coincidirem, as migrações falharão ao iniciar o contêiner.

💡 Notas sobre a configuração do config.ini

sudo nano backend/config/config.ini - abre o arquivo de configuração

  • sudo - direitos de administrador para edição
  • nano - editor de texto
  • backend/config/config.ini - caminho para o arquivo de configuração

Parâmetros do banco de dados:

  • database_password - a senha deve coincidir com MYSQL_ROOT_PASSWORD do arquivo .env
  • database_engine - selecione 'mysql' ou 'pgsql' dependendo do arquivo docker-compose escolhido
  • database_host - deixe como está (orchestrator-db ou orchestrator-pg)
  • database_port - deixe como está (3306 para MySQL, 5432 para PostgreSQL)

Importante:

  • As senhas do banco de dados devem coincidir exatamente com as senhas no arquivo .env
  • As mesmas senhas devem ser especificadas em backend/config/phinx.php (os campos pass nas seções mysql e pgsql) — caso contrário, as migrações não serão executadas ao iniciar o contêiner
  • Se estiver usando PostgreSQL - descomente as linhas correspondentes e comente as do MySQL
  • Salve o arquivo após fazer as alterações (Ctrl+O, Enter, Ctrl+X)

Inicialização do sistema#

Após concluir todas as etapas preparatórias, o Sherpa Orchestrator pode ser iniciado.

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

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

# Se o Vault for necessário (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
💡 Notas sobre a inicialização do sistema

docker compose --profile <mariadb|pg> up -d - inicia o sistema com o BD selecionado

docker compose --profile <mariadb|pg> --profile vault up -d - inicia o sistema com Vault

  • O perfil vault é opcional e é habilitado apenas quando necessário
  • Para configuração posterior do Vault, use o guia 6) VAULT.md

O que o script faz:

  1. Inicia os serviços do orchestrator via Docker Compose
  2. Ativa apenas o contêiner do banco de dados selecionado por perfil (mariadb ou pg)
  3. Configura a rede e os volumes
  4. Executa migrações de banco de dados se necessário
  5. Inicia os serviços em modo background

Verificação do status de inicialização#

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

# Consulte os logs do sistema
docker compose logs orchestrator

# Monitore os logs em tempo real
docker compose logs -f orchestrator
💡 Notas sobre a verificação do status de inicialização

docker compose ps - exibe o status de todos os contêineres

  • Devem estar em execução: orchestrator, orchestrator-vnc-proxy e um contêiner de BD (orchestrator-db com mariadb ou orchestrator-pg com pg)

docker compose logs orchestrator - exibe os logs do serviço principal

docker compose logs -f orchestrator - acompanha os logs em tempo real

  • -f - follow (acompanhar novas mensagens)

Saída esperada após inicialização bem-sucedida:

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

# Para o perfil pg, orchestrator-pg aparecerá em vez de orchestrator-db

Verificação da disponibilidade do sistema#

Verificação da 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

Gerenciamento do sistema#

Parada do sistema:

# Pare todos os serviços
docker compose down

# Pare com remoção de volumes (cuidado!)
docker compose down -v

Reinicialização dos serviços:

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

# Reinicie todos os serviços
docker compose restart

Visualização de recursos:

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

Possíveis problemas ao iniciar:#

  • Contêineres não iniciam: Verifique os logs com docker compose logs
  • Problemas de rede: Certifique-se de que as portas 443, 5000, 6080-6100 estão livres
  • Erros de conexão ao BD: Verifique as configurações no docker-compose.yml
  • Problemas com o domínio: Certifique-se de que HOST_IP está corretamente configurado

Após iniciar e testar com sucesso o sistema, a instalação do Sherpa Orchestrator está concluída. O sistema estará acessível via HTTPS no domínio ou endereço IP configurado.