# 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

```bash
# 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)"
```

<details>

<summary>💡 Notas sobre a extração do arquivo</summary>

**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.

</details>

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

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

```bash
# 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 ..
```

<details>

<summary>💡 Notas sobre a preparação dos scripts</summary>

**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

</details>

### Carregamento das imagens Docker

```bash
# Execute o script de carregamento de imagens Docker
sudo ./sh_scripts/load_all_docker_images.sh
```

<details>

<summary>💡 Notas sobre o carregamento das imagens Docker</summary>

**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

</details>

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

```bash
# Execute o script de criação de configuração
sudo ./sh_scripts/create_config.sh
```

<details>

<summary>💡 Notas sobre a criação de configuração</summary>

**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

</details>

### Cópia dos certificados SSL

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

```bash
# 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
```

<details>

<summary>💡 Notas sobre a cópia dos certificados SSL</summary>

**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`

</details>

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

```bash
# 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:

```yaml
- ./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:

```bash
# Copie o arquivo compose cliente combinado
cp docker-compose.client.yml docker-compose.yml
```

<details>

<summary>💡 Notas sobre a seleção da configuração de BD</summary>

**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`

</details>

### Configuração das variáveis de ambiente

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

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

**Certifique-se de configurar as seguintes variáveis:**

```bash
# 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
```

<details>

<summary>💡 Notas sobre a configuração das variáveis de ambiente</summary>

**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

</details>

#### 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:

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

**Configure os seguintes parâmetros:**

```ini
# 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`:

```bash
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.

<details>

<summary>💡 Notas sobre a configuração do config.ini</summary>

**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)

</details>

### Inicialização do sistema

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

```bash
# 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
```

<details>

<summary>💡 Notas sobre a inicialização do sistema</summary>

**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

</details>

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

```bash
# 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
```

<details>

<summary>💡 Notas sobre a verificação do status de inicialização</summary>

**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)

</details>

**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:**

```bash
# 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:**

```bash
# Pare todos os serviços
docker compose down

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

**Reinicialização dos serviços:**

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

# Reinicie todos os serviços
docker compose restart
```

**Visualização de recursos:**

```bash
# 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.


---

# 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/pt/sherpa-rpa/sherpa-orchestrator/ustanovka-sherpa-orchestrator/s-ispolzovaniem-docker/process-ustanovki-sherpa-orchestrator.md?ask=<question>
```

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.