Guia de instalação do STSDATA NexaOrch

O pacote stsagent-bundle-<versão>.tar.gz contém a aplicação já compilada, em imagens de container prontas, mais o script manage.sh, que cobre tanto uma instalação nova quanto a atualização de uma existente. Não há código-fonte aqui dentro e nada é compilado no servidor.

O que vem no pacote

Pré-requisitos

• Um servidor Linux de 64 bits com bash, curl, rsync e Podman (podman + podman compose). O comando de instalação muda conforme a distribuição — veja a seção seguinte.
• Distribuições cobertas por este guia: Debian e Ubuntu; RHEL, Fedora, Rocky Linux e AlmaLinux; SUSE Linux Enterprise e openSUSE.
• Não precisa de .NET no servidor — nem SDK, nem runtime. A aplicação roda dentro das imagens, e as ferramentas de operação são self-contained.
• Espaço em disco: o pacote tem cerca de 1,2 GB e a extração ocupa outro tanto. Reserve ~3 GB livres na pasta onde for extrair.
• O manage.sh precisa de root: rode sempre com sudo.
• 🛑 Um banco de dados já criado, com usuário e senha próprios — o instalador não cria banco nem usuário, e ler e gravar não basta: o NexaOrch aplica as migrations sozinho no primeiro start. Veja Banco de dados: o que preparar antes.

Banco de dados: o que preparar antes

🛑 O instalador não cria o banco, nem o usuário. Ele pede os dados de conexão de um banco que já existe. Se o banco também for rodar em container, suba-o à parte antes (por exemplo via Podman) e aponte o instalador para ele.

Antes de rodar o manage.sh install, prepare três coisas:

1. o banco — no Oracle, o usuário/schema; no Firebird, o arquivo .fdb;
2. um usuário dedicado ao NexaOrch, com senha;
3. os privilégios desse usuário sobre esse banco.

Por que ler e gravar não basta

No primeiro start, e a cada atualização, o NexaOrch aplica as migrations sozinho. Não é opcional e não tem botão: é o passo que cria e evolui o esquema. Estas são as operações que ele executa, levantadas das migrations do próprio produto:

⚠️ Um usuário só com SELECT/INSERT/UPDATE/DELETE instala e quebra no primeiro start. O erro vem de dentro da migration e fala do objeto que ela tentou criar — não do privilégio que faltou.

O privilégio, por fornecedor

Substitua nexaorchdb e nexaorchusr pelos nomes que você vai usar. Execute como administrador do banco, antes da instalação.

• PostgreSQL — o caminho mais simples é o usuário ser dono do banco: CREATE DATABASE nexaorchdb OWNER nexaorchusr; (ou, se o banco já existe, ALTER DATABASE nexaorchdb OWNER TO nexaorchusr;). ⚠️ No PostgreSQL 15 ou mais novo isso deixou de ser detalhe: o schema public não dá mais CREATE a todo usuário. Sem ser dono, o usuário conecta, lê — e falha ao criar a primeira tabela.
• MySQL / MariaDB — GRANT ALL PRIVILEGES ON nexaorchdb.* TO 'nexaorchusr'@'%'; seguido de FLUSH PRIVILEGES;. ⚠️ A primeira migration executa ALTER DATABASE … CHARACTER SET utf8mb4, que é privilégio sobre o banco, não sobre tabela. Um grant montado só com verbos de tabela passa na conexão e falha na primeira migration.
• SQL Server — crie o login e o usuário no banco e dê db_owner; se preferir separar, db_ddladmin + db_datareader + db_datawriter cobrem as operações da tabela acima.
• Oracle — não há “banco” para criar: cria-se o usuário/schema. Ele precisa de CREATE SESSION, CREATE TABLE e CREATE SEQUENCE (as chaves primárias são colunas de identidade, que no Oracle nascem apoiadas numa sequence interna) — e de cota no tablespace: ALTER USER nexaorchusr QUOTA UNLIMITED ON users;. 🛑 Faltando a cota, a criação da primeira tabela falha com ORA-01950 mesmo com todos os privilégios acima concedidos. É o tropeço mais comum aqui.
• Firebird — o banco é um arquivo. Crie o .fdb conectando como o usuário do NexaOrch, para que ele fique dono do banco: quem não é dono nem SYSDBA conecta e lê, mas não altera metadados — e migration é alteração de metadado.

Confira antes de instalar, não durante

Teste a conexão do próprio servidor onde o NexaOrch vai rodar, com o cliente nativo do banco e com o mesmo usuário e senha que você vai informar ao instalador:

• PostgreSQL — psql -h <host> -p 5432 -U nexaorchusr -d nexaorchdb -c "select 1"
• MySQL / MariaDB — mysql -h <host> -P 3306 -u nexaorchusr -p nexaorchdb -e "select 1"
• SQL Server — sqlcmd -S <host>,1433 -U nexaorchusr -P <senha> -d nexaorchdb -Q "select 1"
• Oracle — sqlplus nexaorchusr/<senha>@<host>:1521/<service-name>
• Firebird — isql-fb -u nexaorchusr -p <senha> <host>/3050:/caminho/nexaorchdb.fdb

⚠️ No Oracle, o campo “Banco de dados” do instalador é o service name, não um nome de catálogo como nos outros fornecedores. É o mesmo valor que vai depois da barra no comando acima.

💡 O teste acima prova credencial e alcance. Ele não prova privilégio de DDL — para isso, CREATE TABLE teste_nexaorch (id INT); DROP TABLE teste_nexaorch; com o mesmo usuário responde em dois comandos o que a migration só responderia no primeiro start.

💡 O instalador refaz esse teste de DDL sozinho, como sexta etapa da conferência de banco, e apaga a tabela em seguida. Fazê-lo aqui serve para descobrir antes, sem depender de chegar até lá com o assistente inteiro respondido.

Pré-requisitos por distribuição

Vá direto ao bloco da família da sua distribuição; não é preciso ler os outros. Cada bloco traz o comando de instalação, a verificação de que ficou pronto e o que confirmar antes de seguir.

⚠️ Faça a verificação antes de continuar. Um pré-requisito que falta em silêncio reaparece três passos adiante, com um erro que não menciona o passo que faltou.

Debian, Ubuntu e derivados

sudo apt update
sudo apt install podman podman-compose uidmap

Confirme que ficou pronto:

podman --version
podman compose version
command -v newuidmap newgidmap

• SELinux: não se aplica — esta família usa AppArmor.
• Rootless: o pacote uidmap traz o newuidmap/newgidmap, de que o Worker precisa para subir sem privilégio. Se o command -v acima não responder os dois caminhos, o container não sobe.
• Firewall (ufw): libere a porta pela qual a tela será acessada. Os padrões são 8081 (HTTPS) e 8080 (HTTP); se você escolher outras na instalação, libere as que escolheu — são portas do host, e podem ser mudadas.

RHEL, Fedora, Rocky Linux e AlmaLinux

Este bloco vale para a família inteira: se você está em Rocky Linux ou em AlmaLinux, é aqui.

sudo dnf install podman podman-compose shadow-utils

⚠️ Em RHEL, Rocky e Alma o podman-compose costuma não estar no repositório base. Se o comando acima não o encontrar, habilite o EPEL e repita:

sudo dnf install epel-release

Confirme que ficou pronto:

podman --version
podman compose version
command -v newuidmap newgidmap

🛑 SELinux — confira antes de seguir. Só esta família vem com SELinux ativo por padrão:

getenforce

• Enforcing é o esperado, e é o modo para o qual o produto está preparado: os volumes dos containers são montados com relabel automático.

• Permissive ou Disabled significa que o SELinux não está barrando nada. A instalação funciona — mas, se você está testando o produto, um resultado assim invalida a verificação do relabel: o teste passaria mesmo se houvesse defeito ali.

• Rootless: o shadow-utils traz o newuidmap/newgidmap.

• Firewall (firewalld): libere a porta pela qual a tela será acessada. Os padrões são 8081 (HTTPS) e 8080 (HTTP); se você escolher outras na instalação, libere as que escolheu — são portas do host, e podem ser mudadas.

SUSE Linux Enterprise e openSUSE

sudo zypper install podman podman-compose shadow

Confirme que ficou pronto:

podman --version
podman compose version
command -v newuidmap newgidmap

• SELinux: não se aplica na configuração padrão — esta família usa AppArmor.
• Rootless: o pacote shadow traz o newuidmap/newgidmap.
• Firewall (firewalld): libere a porta pela qual a tela será acessada. Os padrões são 8081 (HTTPS) e 8080 (HTTP); se você escolher outras na instalação, libere as que escolheu — são portas do host, e podem ser mudadas.

O que este guia não faz. Ele diz o que o NexaOrch precisa que exista na máquina e como conferir que existe. Configurar o firewall, criar contas ou ajustar faixas de subuid/subgid a fundo é administração do servidor, e continua com quem cuida dele.

Instalação nova

Use este caminho se o servidor ainda não tem uma instalação do NexaOrch.

Extraia o pacote em qualquer pasta — não precisa ser o destino final, porque a instalação vai para /opt/nexaorch:

⚠️ Servidor que já tem uma instalação anterior a esta versão continua com o nome antigo. Até esta versão, a conta de serviço, a pasta e os containers se chamavam stsagent, /opt/stsagent e stsagent_ui_1 / stsagent_worker_1. Nada disso é renomeado: um update mantém os nomes que a instalação já tem, de propósito. Este guia usa os nomes NOVOS; se a sua instalação é anterior, troque nexaorch por stsagent nos caminhos. Para conferir sem adivinhar: sudo ./manage.sh runtime-names.

tar -xzf stsagent-bundle-<versão>.tar.gz
cd stsagent-bundle-<versão>

Rode o instalador:

sudo ./manage.sh install

O assistente pergunta tudo que falta para colocar o sistema no ar:

• Banco de dados — os dados de conexão de um banco já existente (host, porta, nome, usuário, senha). O assistente não sobe um banco novo por você: se quiser rodar o banco também em container, suba-o à parte (por exemplo via Podman) antes de rodar o instalador, e aponte para ele aqui.
• Conta de administrador — senha gerada automaticamente ou digitada. Não existe senha padrão: ou você a define aqui, ou o sistema a pede no primeiro acesso à tela (veja Primeiro acesso).
• Empresa, notificação por e-mail (SMTP), execução e integração com IA (Ollama) — as mesmas seções da tela Configurações, já gravadas no banco antes do primeiro login.
• Pastas do host — dados do Worker, downloads públicos, chaves SSH, transferência de arquivos e backups.
• Subir sozinho após reboot — opcionalmente, uma unit systemd. Veja Subir sozinho depois de um reboot.

Ao final, dois containers (ui e worker) sobem via podman compose, todos isolados sob uma conta de serviço dedicada — nexaorch por padrão, e não o usuário que rodou o comando.

Quando a instalação termina, não há nada para rodar depois: os containers já estão no ar e a última linha da tela traz o endereço de acesso. Em especial, não chame podman compose à mão — no servidor ele não funciona com o ambiente do seu usuário, pelo motivo que a seção Falar com o compose sem o manage.sh, no fim deste guia, explica.

Certificado HTTPS

Este pacote não traz certificado. Numa instalação nova, o manage.sh gera um autoassinado no próprio servidor, com senha aleatória: cada instalação fica com a sua chave, e nada secreto trafega pela página de downloads, que é pública.

Ele serve para subir o sistema e conferir que tudo responde. Não serve como certificado de produção, e o navegador vai avisar. Para trocar por um certificado próprio, sem reinstalar:

sudo ./manage.sh set-certificate --pfx meu-certificado.pfx --password SENHA
sudo ./manage.sh set-certificate --crt meu.crt --key minha.key
sudo ./manage.sh set-certificate --self-signed --hosts 10.0.0.180,nexaorch.local

Reinstalando por cima: a senha do certificado que já existe

Numa reinstalação, o certificado que já está no servidor não é substituído: a instalação reaproveita o arquivo e a senha que estão lá, sem perguntar nada.

Ela só pergunta “Password for the existing certificate” quando a senha guardada no .env não abre o arquivo — o caso de quem trocou o .pfx à mão sem atualizar o .env. Essa senha não foi escolhida por você: é aleatória, gerada na instalação anterior, e fica no .env da instalação.

sudo grep HTTPS_CERT_PASSWORD /opt/nexaorch/.env

Se ninguém tiver essa senha, peça para trocar o certificado: a instalação gera um autoassinado novo ali mesmo, no servidor, com o IP e o nome desta máquina no campo SAN — arquivo e senha gravados juntos — e segue até o fim.

Se a instalação já estiver rodando, o mesmo se resolve sem reinstalar nada:

sudo /opt/nexaorch/manage.sh set-certificate --self-signed --hosts 10.0.0.180,nexaorch.local

Atualização

Use este caminho se o servidor já tem uma instalação rodando e você quer levá-la a esta versão.

Copie o pacote para o servidor e extraia:

tar -xzf stsagent-bundle-<versão>.tar.gz
cd stsagent-bundle-<versão>

Rode o update de dentro da pasta extraída — é dela que saem as imagens desta versão:

sudo ./manage.sh update

O update não refaz as perguntas de banco, SMTP, empresa, execução e Ollama, não toca nos bancos já provisionados e preserva .env, certificado e as pastas de dados do Worker. Ele só carrega as imagens novas e recria os containers. Migrations de banco pendentes rodam sozinhas no boot da UI.

Voltar à versão anterior

Antes de recriar os containers, o script marca as imagens em uso com a tag :previous. Se a versão nova não subir corretamente:

sudo /opt/nexaorch/manage.sh rollback

Volta para as imagens anteriores, sem precisar do pacote antigo.

Subir sozinho depois de um reboot

A instalação oferece gravar uma unit systemd que sobe os containers no boot. Se você recusou na hora e mudou de ideia, ou quer desligar depois, não precisa editar /etc/systemd/system à mão:

sudo /opt/nexaorch/manage.sh enable-boot
sudo /opt/nexaorch/manage.sh disable-boot

Por que isto importa mais do que parece. A unit grava quais serviços este host sobe. Sem essa informação ela faria compose up -d puro e subiria todos os serviços do arquivo — inclusive a UI num host que só deveria rodar o Worker, tomando portas que ali pertencem a outra coisa. O deploy sempre respeitou o recorte de serviços; era o boot que não respeitava, e o problema só aparecia depois de um reboot, longe da mudança que o causou.

Host só de Worker

Um servidor pode rodar apenas o Automation Agent, sem o Portal — é o arranjo comum quando a execução precisa acontecer perto de um banco ou de um compartilhamento de arquivos, e o Portal vive em outro lugar.

Esse recorte fica gravado no próprio host, em STS_SERVICES dentro do .env da instalação. Isso é o que faz uma chamada manual (up, rollback, switch-connection) continuar sabendo que aquele host não tem UI — antes, cada invocação manual voltava ao padrão “ui worker” e ia procurar uma imagem que nunca foi enviada para lá.

Licença da instalação

O NexaOrch é licenciado por instalação. Não existe código por Automation Agent: o pacote licencia todos eles.

Como se obtém o arquivo .lic

O código desta instalação não é informado por você: o próprio NexaOrch o gera na primeira vez que sobe, e o exibe em Configurações → Licença, num formato como LIC-FQCH-EGS0-J2GC-GSHQ.

Instalações criadas antes de agosto de 2026 exibem o mesmo código com o prefixo NEXA-, e continuam assim para sempre — não há nada a atualizar. O prefixo faz parte do código: copie sempre o que a tela mostra, inteiro. LIC-ABCD-… e NEXA-ABCD-… são instalações diferentes.

1. Instale — nada é bloqueado sem licença.
2. Abra Configurações → Licença e copie o código da instalação, com o prefixo.
3. Informe esse código ao comprar ou renovar.
4. Você recebe de volta um arquivo .lic amarrado a ele: é válido nesta instalação e em nenhuma outra.
5. Importe o arquivo na mesma tela. Não precisa reinstalar nem parar nada.

O manage.sh install não pergunta nada de licença. Instalar sem licença é o caminho normal — é assim que funcionam avaliações, provas de conceito e laboratórios.

Os Agents se licenciam sozinhos

O .lic diz quantos Agents você comprou, e eles ocupam as vagas por ordem de chegada, sem nenhuma configuração em cada servidor. Importou a licença, os Agents que já existem ficam conformes na hora. Um Agent instalado depois pega uma vaga livre sozinho, no primeiro minuto em que subir.

Precisa de mais um Agent: não existe licença avulsa. Você compra a ampliação e recebe um .lic novo desta mesma instalação, agora com mais Agents incluídos. Importe-o na mesma tela — comprar, renovar e ampliar são o mesmo gesto.

Quando falta vaga: enquanto nenhuma licença tiver sido importada, nada acontece. Havendo licença, um Agent além do número incluído não pega trabalho novo; as execuções em andamento terminam normalmente e os demais Agents não são afetados. A validação é feita no próprio servidor — o NexaOrch nunca precisa de internet para conferir uma licença.

Avaliação e modo restrito

Uma instalação nova nasce com 15 dias de avaliação, com o produto completo: nada é amputado durante o trial, porque produto amputado não permite avaliar. O aviso na tela começa a partir do 10º dia.

A tolerância de 7 dias existe por um motivo operacional: o NexaOrch roda carga noturna. Uma licença que expira à meia-noite com corte imediato significa carga que não roda, sem ninguém acordado para importar um arquivo — e o cliente descobre às 8h com o BI vazio, exatamente no dia em que estava renovando.

No modo restrito a escrita é negada e a interface fica em leitura. Processos, histórico e conexões continuam onde estão; importar a licença destrava na hora.

Instalações que já existiam antes do regime de trial não entram em avaliação: a data de criação nasce vazia nelas, e vazio significa “sem trial”, não “trial começando agora”. O regime vale para quem nasce nele.

Publicação: direta ou atrás de proxy reverso

O NexaOrch funciona dos dois jeitos, escolhido por configuração e trocável depois, sem reinstalar.

Modo direto (padrão)

O próprio sistema serve HTTPS, com o certificado em /opt/nexaorch/https/aspnetapp.pfx. O acesso é por IP.

A instalação gera esse certificado já com o IP e o nome desta máquina no campo SAN — ou seja, o endereço confere. Mesmo assim o navegador avisa, porque ele é autoassinado: ninguém além do próprio servidor o reconhece como emissor. São coisas diferentes, e só a segunda sobra:

• Endereço errado → resolvido pela instalação, ou reemita com --hosts
• Emissor desconhecido → resolvido importando o certificado

Se o servidor mudar de IP ou de nome, reemita:

sudo /opt/nexaorch/manage.sh set-certificate --self-signed
sudo /opt/nexaorch/manage.sh set-certificate --self-signed --hosts 10.0.0.180,nexaorch.local

Como tirar o aviso do navegador

A instalação deixa o certificado público em /opt/nexaorch/https/aspnetapp.crt. Distribua esse arquivo — ele não contém chave privada; não envie o .pfx — e importe-o como autoridade confiável nas máquinas que acessam o sistema.

• Windows, máquina a máquina: certlm.msc → Autoridades de Certificação Raiz Confiáveis → Certificados → importar o aspnetapp.crt.
• Windows, domínio inteiro (recomendado quando houver AD): Política de Grupo → Configuração do Computador → Políticas → Configurações do Windows → Configurações de Segurança → Políticas de Chave Pública → Autoridades de Certificação Raiz Confiáveis → Importar.
• Firefox usa o armazenamento próprio dele: Configurações → Privacidade e Segurança → Certificados → Ver certificados → Autoridades → Importar.

Se você tem uma CA corporativa, o caminho melhor é emitir por ela — as máquinas do domínio já confiam nessa CA, e não há nada a distribuir:

sudo /opt/nexaorch/manage.sh set-certificate --pfx /caminho/cert.pfx --password '<senha>'
sudo /opt/nexaorch/manage.sh set-certificate --crt /caminho/cert.crt --key /caminho/cert.key

Modo atrás de proxy reverso (recomendado quando há nome DNS)

Um nginx termina o TLS com um certificado emitido para o nome e encaminha HTTP para o NexaOrch. É o arranjo que elimina o aviso do navegador sem instalar nada nas máquinas dos usuários — certificado de CA pública só existe para nome, nunca para IP privado.

sudo /opt/nexaorch/manage.sh set-proxy-mode --proxy 10.0.0.5
sudo /opt/nexaorch/manage.sh set-proxy-mode --proxy 10.0.1.0/24
sudo /opt/nexaorch/manage.sh set-proxy-mode --proxy off

O IP informado é o do proxy. Sem ele o sistema ignora os cabeçalhos X-Forwarded-*, e o resultado é laço de redirecionamento e login que nunca completa. Nesse modo o sistema passa a escutar só HTTP na 8080.

O trecho entre o proxy e o sistema é em texto claro. Quando o nginx está em outro servidor, esse trecho atravessa a rede — e o cookie de autenticação vai nele. É o mesmo arranjo usado por Gitea, pgAdmin e a maioria das aplicações atrás de proxy, e é aceitável quando os dois estão na mesma rede confiável. Duas providências não são opcionais: libere a 8080 no firewall apenas para o IP do proxy, e mantenha proxy e sistema na mesma VLAN, nunca com a internet ou uma rede de visitantes no meio.

Exemplo de configuração — os três ajustes marcados são exigência deste sistema, não formalidade:

server {
    listen 443 ssl;
    server_name nexaorch.cliente.com.br;

    ssl_certificate     /etc/letsencrypt/live/nexaorch.cliente.com.br/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/nexaorch.cliente.com.br/privkey.pem;

    # o import de pacote aceita 11 MB; o default do nginx é 1 MB
    client_max_body_size 12m;

    location / {
        proxy_pass http://10.0.0.180:8080;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        # sem esta linha: laço de redirecionamento
        proxy_set_header X-Forwarded-Proto $scheme;
        # sem esta linha (ou com um valor curto): "a tela travou" nas telas de prévia — veja abaixo
        proxy_read_timeout 300s;
    }

    location /downloads/ {
        proxy_pass http://10.0.0.180:8080;
        # a página pública serve o pacote de ~1,2 GB
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

🛑 O timeout do proxy e as telas de prévia (a tela que “trava”)

O proxy_read_timeout do exemplo acima não é formalidade: quatro telas do sistema mandam o servidor abrir uma conexão com um banco de dados de terceiros e ler dele antes de responder. Numa tabela grande — muitas linhas e, principalmente, muitas colunas — isso passa fácil dos 60 segundos que o nginx aceita esperar por padrão.

As rotas, pelo nome:

⚠️ Não adianta criar um location para essas rotas. O ?handler= é query string, e o location do nginx casa só o caminho — por isso o ajuste vai no location /, como no exemplo, e vale para o sistema inteiro. Se você preferir separar, o recorte possível é por página (/SharedCommands/Edit e /Jobs/Step), nunca por handler.

O que acontece sem o ajuste — e é isto que você precisa reconhecer depois. O nginx desiste antes de o sistema responder e devolve a página de erro 504 dele. A tela esperava JSON, recebe HTML, e o que aparece para o operador é algo como:

SyntaxError: Unexpected token '<', "<html> <h"... is not valid JSON

🛑 Nada nessa mensagem aponta para o proxy. Quem opera relata “a tela travou” ou “deu erro de JavaScript”, e o problema é procurado no sistema, no banco, no navegador — nunca no nginx. Se você está vendo esse erro só nas telas de prévia e só com tabelas grandes, o suspeito é este parâmetro, e a confirmação está no error.log do nginx (upstream timed out).

300s é ponto de partida, não medida. Se a leitura da origem legitimamente demora mais que isso, o número sobe; se você prefere que o operador receba o erro rápido, ele desce — mas então a prévia de tabela grande deixa de funcionar, e essa é a escolha que está sendo feita.

⚠️ Instalação que já está no ar. A linha entrou neste guia depois de a maioria das instalações existentes ser configurada — o arquivo que está rodando hoje pode não tê-la. Confira o location / do seu server, acrescente a linha se faltar, e recarregue com nginx -t && systemctl reload nginx. Nada no sistema precisa ser reiniciado.

Primeiro acesso

Quando a instalação é feita pelo assistente (manage.sh install), a conta de administrador e os dados da empresa já são gravados ali, e você entra direto na tela de login.

Uma base que não passou pelo assistente — por exemplo, ao apontar a aplicação para um banco novo com switch-connection, ou ao restaurar um backup numa base limpa — abre no primeiro acesso: a própria tela pede a senha do administrador (se ainda não houver nenhum) e, em seguida, os dados da empresa. Ao final ela mostra o código desta instalação, que é o que você informa à STSDATA para licenciar. O mesmo código fica sempre disponível em Configurações › Licença.

Preencher os dados da empresa é obrigatório: é esse passo que dá identidade à instalação.

Quando a conexão com o banco falha

Vale para todas as distribuições. Os blocos por família, mais abaixo, trazem só o que muda: firewall, SELinux e nome do serviço.

💡 Comece pelo que o instalador já respondeu

Se a falha aconteceu durante a instalação, não comece testando à mão: o instalador já fez o diagnóstico e já escreveu tudo. Ele confere o banco em seis etapas — o nome resolve, a porta aceita TCP, o servidor completa o protocolo, a credencial é aceita, a base é alcançável, e o usuário cria e apaga uma tabela:

  [OK]      host 'db.exemplo.local' resolves (10.0.0.7)
  [OK]      port 5432 accepts TCP
  [FAILED]  credentials accepted for user 'nexaorchusr'
            no pg_hba.conf entry for host "10.0.0.7", user "nexaorchusr"
            -> PostgreSQL refused this origin (pg_hba.conf), not the password. ...
  [SKIPPED] database 'nexaorchdb' is reachable

• a etapa que reprova diz a causa e o que verificar; as seguintes saem como [SKIPPED], e nunca em branco;
• ele escreve um log em arquivo e imprime o caminho na tela, inclusive quando tudo passa. ⚠️ Esse log nunca contém a senha, nem o tamanho dela;
• 🛑 ele imprime como qual usuário do sistema operacional está conectando. O instalador roda como a conta de serviço, não como quem digitou o comando — e com peer ou ident no pg_hba.conf é esse o nome que o banco vê. É por isso que «testei no DBeaver e funciona» pode ser verdade enquanto o instalador falha.

Duas ações respondem sem mudar nada, e são o começo de qualquer conferência:

sudo ./manage.sh runtime-names   # conta de serviço, pasta e prefixo dos containers desta máquina
sudo ./manage.sh pg-hba-path     # onde está o pg_hba.conf (pergunta ao servidor primeiro)

O resto desta seção vale para o que o instalador não alcança: o que acontece depois que ele termina, e o teste manual, quando você quer separar «o banco recusa» de «o NexaOrch recusa».

🛑 O banco está “no mesmo servidor”? Então localhost não serve

O NexaOrch roda dentro de um container. Lá dentro, localhost é o próprio container — não o servidor. Apontar a connection string para localhost com o banco instalado no host dá “conexão recusada” mesmo com o banco no ar e a credencial certa, e é o engano mais comum desta instalação.

Use, no lugar de localhost:

• host.containers.internal, nas versões de Podman que a publicam; ou
• o IP do servidor na rede (o mesmo que você usaria de outra máquina).

💡 Confirme com sudo ./manage.sh logs ui --lines 50 logo depois de subir: o erro de conexão aparece ali, com o host que ele realmente tentou.

Os quatro desfechos, e o que cada um quer dizer

Teste do servidor, com o cliente nativo (comandos na seção Banco de dados: o que preparar antes). O que voltar diz onde está o problema:

⚠️ O quarto é o que não parece problema de conexão. A conexão funcionou; o que faltou foi CREATE TABLE. Se o teste de conexão passa e a instalação quebra em seguida, comece por ali.

💡 Onde fica o pg_hba.conf — pergunte ao servidor, não à distribuição

O caminho muda por família, e a lista envelhece. O próprio PostgreSQL responde:

sudo -u postgres psql -tAc 'SHOW hba_file'

Os caminhos por família, para quando o servidor não estiver no ar:

💡 O instalador tenta abrir esse arquivo sozinho para a rede do Podman, e diz na tela o que fez. Se ele não achar o arquivo, avisa em vez de ficar calado — e sudo ./manage.sh pg-hba-path mostra onde ele procurou.

Debian, Ubuntu e derivados

• Firewall: sudo ufw status. Se estiver ativo, libere a porta do banco para o servidor — por exemplo sudo ufw allow from <ip-do-servidor> to any port 5432 proto tcp.
• Serviço do banco, quando é local: systemctl status postgresql (ou mysql, mariadb, firebird).
• PostgreSQL local: por padrão ele escuta só em localhost. Para aceitar o container, ajuste listen_addresses no postgresql.conf e acrescente a linha correspondente no pg_hba.conf.

RHEL, Fedora, Rocky Linux e AlmaLinux

• Firewall: sudo firewall-cmd --list-all. Para liberar: sudo firewall-cmd --add-port=5432/tcp --permanent && sudo firewall-cmd --reload.
• SELinux: com o SELinux em enforcing, a saída de um container para um serviço do host pode ser negada. Confira com getsebool -a | grep container_connect e veja sudo ausearch -m avc -ts recent depois de uma tentativa — um denied ali aponta o caminho.
• Serviço do banco, quando é local: systemctl status postgresql (ou mariadb).

SUSE Linux Enterprise e openSUSE

• Firewall: sudo firewall-cmd --list-all — o SUSE usa firewalld nas versões atuais. Mesmos comandos do bloco anterior.
• SELinux/AppArmor: o SUSE usa AppArmor por padrão; se ele estiver ativo para o Podman, sudo aa-status mostra os perfis em modo enforce.
• Serviço do banco, quando é local: systemctl status postgresql (ou mariadb).

Se nada acima explicar

Junte estas saídas antes de abrir chamado — elas respondem, juntas, quase toda pergunta que o suporte faria:

sudo ./manage.sh version
sudo ./manage.sh logs ui --lines 200

⚠️ Não cole a saída de comandos do podman rodados à mão: o compose ecoa a linha inteira do podman run, com a senha do banco e a do certificado em texto claro. O manage.sh filtra; comando solto, não.

Perdeu a senha de administrador

O sistema não tem “esqueci minha senha”, e não há como criar um administrador novo num banco que já tem usuários. Se o único administrador perde a senha — ou fica travado por tentativas erradas — o caminho de volta é este comando, no próprio servidor:

sudo /opt/nexaorch/manage.sh reset-password --list
sudo /opt/nexaorch/manage.sh reset-password --user admin
sudo /opt/nexaorch/manage.sh reset-password --user admin --password 'NovaSenha@2026'

A senha nova precisa ter no mínimo 10 caracteres e ao menos um que não seja letra nem número — a mesma regra da tela de usuários. Se não passar, o comando recusa e não altera nada.

Omitindo --password o comando pergunta no terminal, sem mostrar o que você digita. Prefira essa forma: o que vai na linha de comando fica visível para os outros usuários da máquina, via ps.

Ao redefinir, as sessões abertas daquele usuário caem. Um usuário inativo continua sem conseguir entrar mesmo com a senha nova — reative-o pela tela de usuários. Um usuário na Lixeira precisa ser restaurado primeiro; o comando avisa quando é esse o caso.

Outros comandos

sudo /opt/nexaorch/manage.sh version     # versão instalada e estado dos containers
sudo /opt/nexaorch/manage.sh logs ui     # log do container da UI
sudo /opt/nexaorch/manage.sh logs worker # log do container do Worker
sudo /opt/nexaorch/manage.sh up          # (re)sobe os containers já carregados
sudo /opt/nexaorch/manage.sh down        # PARA a instalação (não desinstala)
sudo /opt/nexaorch/manage.sh down worker # para só o Worker (a UI continua no ar)

Parar a instalação

sudo /opt/nexaorch/manage.sh down          # para tudo
sudo /opt/nexaorch/manage.sh down worker   # para só o Worker
sudo /opt/nexaorch/manage.sh down ui       # para só a UI

down para; não desinstala. Nenhum volume e nenhum dado são removidos — para remover a instalação existe o uninstall. No fim, o comando lista o que ficou de pé.

Quando o boot automático está ligado, um down sem argumento para pela unit do systemd, e não por fora dela: assim o systemd não fica achando que a aplicação continua no ar. Parar só um serviço não mexe na unit — depois de um reboot ele sobe de novo (use disable-boot se não for isso que você quer).

Falar com o compose sem o manage.sh

Se precisar chamar o podman compose direto, ele não funciona com o ambiente do seu usuário: este servidor tem o plugin compose do Docker instalado, e o comando tenta um socket que a conta de serviço não expõe, falhando com failed to connect to the docker API at unix:///run/user/<uid>/podman/podman.sock. A invocação correta é:

sudo -u nexaorch env \
  XDG_RUNTIME_DIR=/run/user/$(id -u nexaorch) \
  HOME=/opt/nexaorch \
  PODMAN_COMPOSE_PROVIDER=podman-compose \
  podman compose -p nexaorch -f /opt/nexaorch/docker-compose.prod.yml ps

O manage.sh já faz exatamente isso internamente — prefira ele sempre que houver um comando pronto.

Trocar o banco de lugar

sudo /opt/nexaorch/manage.sh switch-connection --provider <P> --connection '<string>'

Aponta a instalação para outro banco. Não migra dado nenhum — use quando o banco continua sendo o mesmo, mas mudou de IP, porta ou senha.

Migrar para outro fornecedor de banco

sudo /opt/nexaorch/manage.sh migrate-provider

Copia os dados desta instalação para outro banco (por exemplo, Firebird → PostgreSQL). Interativo: pergunta origem e destino, e a origem só é lida, nunca alterada.

Para os containers antes de copiar e os deixa parados ao final — com o Automation Agent no ar a origem seria alvo móvel, e uma execução que comece depois da cópia da tabela dela não chegaria ao destino.

Não reaponta a instalação. Ao terminar, rode o switch-connection para passar a usar o banco novo, ou up para voltar ao de hoje.

Remover a instalação

sudo /opt/nexaorch/manage.sh uninstall

Remove esta instalação: containers, imagens, a rede e a conta de serviço, nessa ordem — invertê-la trava a máquina. E pergunta antes de remover pasta de dados que esteja fora do diretório de instalação.

🛑 O banco de dados NÃO é tocado. Nada em uninstall apaga dados: as definições de Job, o histórico de execuções, as conexões, as credenciais cifradas e os usuários continuam onde estão. O próprio comando avisa isso na tela, antes de pedir confirmação.

É o comportamento desejado na maioria dos casos — reinstalar por cima reencontra tudo. Se você quer mesmo descartar os dados, isso é um passo à parte, no fim deste guia: Remover também o banco de dados.

Ajuste os caminhos se STS_INSTALL_DIR foi customizado na instalação original.

Remover também o banco de dados

Esta seção está fora da sequência de instalação de propósito, e nada aqui é necessário para remover o produto: o uninstall já resolveu isso e não tocou no banco. Leia esta parte apenas se a decisão for descartar os dados.

🛑 Não há volta

Apagar o banco é a ação mais destrutiva ligada a este produto. Não existe desfazer, e não existe lixeira. O que se perde:

• as definições de Job e suas etapas — todo o trabalho de quem montou as automações;
• o histórico de execuções, com logs e estatísticas;
• as conexões e as credenciais cifradas;
• os usuários, papéis e permissões;
• a licença importada e a identidade desta instalação.

⚠️ Um detalhe que costuma pegar: o usuário que a aplicação usa normalmente não tem permissão para criar banco. Quem apaga geralmente não consegue recriar sozinho — vai precisar de alguém com privilégio de administração no servidor de banco. Confirme isso antes, não depois.

O comando, por fornecedor

Os comandos abaixo estão em texto, e não em bloco de código, de propósito: eles não devem ser copiados de enfiada, junto com os comandos de instalação. Digite o seu, substituindo <nome-do-banco> pelo nome real — que está em DEFAULT_CONNECTION_STRING, no arquivo .env da instalação, antes de você remover a instalação.

• MySQL / MariaDB — conecte com mysql -u <admin> -p e execute: DROP DATABASE <nome-do-banco>;
• PostgreSQL — conecte com psql -U <admin> e execute: DROP DATABASE <nome-do-banco>;
• SQL Server — conecte com sqlcmd -S <host> -U <admin> e execute: DROP DATABASE <nome-do-banco>;
• Oracle — não se apaga um “banco”: remove-se o usuário/schema, com DROP USER <usuario> CASCADE; executado por alguém com privilégio de DBA.
• Firebird — não há DROP DATABASE remoto: o banco é um arquivo. Pare o serviço e apague o .fdb indicado na connection string (por padrão /opt/firebird/data/nexaorchdb.fdb).

⚠️ Antes de qualquer um deles, um backup resolve o arrependimento que o DROP não resolve.