27 — Instalar app opcional (exemplo: Lorentz Energy)¶

Passo a passo completo para subir um serviço com profile no stack — útil para treino de suporte e demonstrações.

Índice de todos os apps: 28-indice-instalacao-apps.md

Apps opcionais não sobem com deploy-all.sh / deploy-stack.sh (só o core). Cada um tem script dedicado.

1. Visão geral¶

Item	Lorentz Energy
Profile Compose	`energy`
Container	`lorentz-energy`
Porta	8082
Código-fonte	`../lorentz-energy` (repo irmão)
Script	`scripts/deploy-lorentz-energy.sh`
URL exemplo	`http://<IP>:8082/`

Outros apps no mesmo padrão:

App	Script	Porta
Webphone	`deploy-webphone.sh`	8081
Licença API	`deploy-licenca.sh`	8092 (proxy Portal)
Portainer	`deploy-portainer.sh`	9443

2. Pré-requisitos¶

2.1 Stack core já rodando¶

O Energy depende do Docker e do .env do stack (mesmo que o container Energy em si não use SQL):

cd ~/omnichannel/lorentz-vps-stack
docker compose ps
# sqlserver, lorentz-cti, supervisor, lorentz-portal, monitor — healthy ou Up

Se a VPS é nova: 13-maquina-nova-stack-aws-cli.md ou ./scripts/deploy-stack.sh.

2.2 Arquivo `.env` configurado¶

cp .env.example .env
nano .env

Mínimo obrigatório (o Compose valida todo o docker-compose.yml, mesmo subindo só o profile energy):

Variável	Exemplo
`MSSQL_SA_PASSWORD`	senha do SQL Server
`VPS_PUBLIC_IP`	IP público da VPS
`LORENTZ_BASEHISTORICA_API_KEY`	`ChangeMe_BaseHistorica2026!` (se ausente, script usa default)

2.3 Permissão de execução nos scripts¶

Após git clone ou git pull no Windows, scripts podem perder +x:

chmod +x scripts/*.sh

Sem +x, ./scripts/deploy-lorentz-energy.sh retorna Permission denied. Alternativa:

bash scripts/deploy-lorentz-energy.sh

deploy-all.sh, sync-stack-to-vps.sh e prepare-support-install.sh já rodam chmod +x scripts/*.sh automaticamente.

3. Passo a passo — Lorentz Energy¶

Passo 1 — Entrar no stack¶

cd ~/omnichannel/lorentz-vps-stack
chmod +x scripts/*.sh

Passo 2 — Verificar pré-requisitos (opcional)¶

./scripts/deploy-lorentz-energy.sh --check

Saída esperada:

[energy] Codigo-fonte ja presente: /home/ubuntu/omnichannel/lorentz-energy
[energy] AVISO: index.html ausente — container usara placeholder HTML.
[energy] Pre-requisitos OK: ...

AVISO index.html ausente: normal se o repo lorentz-energy ainda não tiver frontend — o nginx serve placeholder.html até o projeto evoluir.

Passo 3 — Deploy (clone + build + start)¶

./scripts/deploy-lorentz-energy.sh

O script automaticamente:

Clona https://github.com/araguaci/lorentz-energy.git em ../lorentz-energy se não existir
Roda render-config.sh (atualiza portal.apps.json)
Executa docker compose --profile energy up -d --build lorentz-energy
Testa HTTP local na porta 8082

Saída esperada ao final:

[energy] Lorentz Energy iniciado.
[energy]   URL publica: http://3.93.232.33:8082/
[energy]   HTTP 8082 OK

Passo 4 — Liberar porta no firewall (se acesso externo falhar)¶

AWS Security Group:

./scripts/deploy-lorentz-energy.sh --open-sg
# ou restrito: ./scripts/open-aws-port-8082.sh SEU_IP/32

Firewalld / ufw na VPS:

./scripts/deploy-lorentz-energy.sh --open-fw

Passo 5 — Validar no navegador¶

http://<IP>:8082/

No hub Orbitall (:8099 ou :8443), o app Energy deve aparecer na órbita se portal.apps.json tiver URL configurada.

Passo 6 — Atualizar código-fonte (quando houver releases)¶

./scripts/deploy-lorentz-energy.sh --pull
./scripts/deploy-lorentz-energy.sh

Passo 7 — Parar (se necessário)¶

./scripts/deploy-lorentz-energy.sh --stop

4. Erros comuns¶

`Permission denied` ao rodar `./scripts/...`¶

chmod +x scripts/*.sh
# ou
bash scripts/deploy-lorentz-energy.sh

`required variable LORENTZ_BASEHISTORICA_API_KEY is missing`¶

O .env está incompleto ou desatualizado. Versões antigas do stack não tinham essa variável.

# Adicione ao .env:
LORENTZ_BASEHISTORICA_API_KEY=ChangeMe_BaseHistorica2026!

# Ou recrie a partir do exemplo:
grep LORENTZ_BASEHISTORICA .env.example >> .env

A partir da v1.9.x o docker-compose.yml usa valor default; o script deploy-lorentz-energy.sh também exporta default se ausente.

`required variable MSSQL_SA_PASSWORD is missing`¶

nano .env   # defina MSSQL_SA_PASSWORD=
./scripts/render-config.sh

`index.html ausente — placeholder`¶

Não é erro. O container sobe com página placeholder até existir index.html em ../lorentz-energy/.

Porta 8082 não abre de fora¶

Security Group AWS + firewalld — ver Passo 4.

5. Estrutura de diretórios¶

omnichannel/
├── lorentz-vps-stack/          ← este repo (compose, scripts)
│   ├── .env
│   ├── docker/lorentz-energy/
│   └── scripts/deploy-lorentz-energy.sh
└── lorentz-energy/             ← clonado automaticamente (repo irmão)
    └── index.html              ← quando existir, substitui placeholder

6. Checklist rápido (demonstração / suporte)¶

#	Ação	Comando
1	Core rodando	`docker compose ps`
2	Scripts executáveis	`chmod +x scripts/*.sh`
3	`.env` OK	`grep MSSQL_SA_PASSWORD .env`
4	Check	`./scripts/deploy-lorentz-energy.sh --check`
5	Deploy	`./scripts/deploy-lorentz-energy.sh`
6	Firewall	`--open-sg` e/ou `--open-fw`
7	Teste	`curl http://127.0.0.1:8082/`
8	Browser	`http://<IP>:8082/`

7. Documentos relacionados¶

Doc	Conteúdo
25-guia-scripts-deploy.md	deploy-all vs profiles
`docker/lorentz-energy/README.md`	Dockerfile/nginx
`portal/energy/README.md`	Link no hub
22-plano-dominio-orbitall-app.md	HTTPS futuro

8. Histórico¶

Data	Notas
2026-07-13	Guia criado — passo a passo Energy + chmod + erro .env