Requisitos

Máquina

Para uma instalação de avaliação ou até ~50 endpoints:

Recurso	Mínimo	Observação
CPU	4 vCPU	O gargalo é a CPU do processo da aplicação, não o banco. Ver dimensionamento.
Memória	8 GB	A aplicação usa ~60 MiB em repouso; o resto é banco e armazenamento.
Disco	60 GB SSD	A telemetria de endpoints é o que cresce. Definir retenção é requisito, não ajuste fino.
Sistema	Linux com Docker	Testado em Debian. docker compose v2 ou superior.

Serviços de apoio

Três peças, e só a primeira é do OpenScale.

PostgreSQL

Versão 14 ou superior. A extensão pg_trgm é usada para busca textual em chamados e precisa estar disponível — em imagens oficiais ela vem no pacote padrão e o produto a habilita no banco.

Crie banco e usuário dedicados. Não reaproveite um banco existente: o produto cria e migra o próprio esquema.

CREATE USER openscale WITH PASSWORD 'defina-uma-senha-forte';
CREATE DATABASE openscale OWNER openscale;

Armazenamento compatível com S3

MinIO, ou qualquer serviço com API S3. Serve anexos de chamado, evidências de auditoria, arquivos do File Server e destinos de backup.

Crie as credenciais de acesso e, no mínimo, o bucket de evidências de agente. O nome do bucket é configurável, e o mapa de bucket por cliente é o mecanismo de separação em instalação multi-cliente.

Proxy reverso

Recomendado, e com uma exigência que costuma passar batida: o tempo de leitura do proxy precisa ser de no mínimo 600 segundos.

O produto usa consulta longa para atualizar telas em tempo real. Um proxy com o padrão de 60 segundos corta a conexão no meio, e o sintoma é uma interface que “recarrega sozinha” sem erro visível no log da aplicação.

Variáveis obrigatórias

Toda a configuração vem do ambiente — não há valor de instalação embutido no código. Placeholders do tipo change-me são tratados como ausentes: o produto falha fechado em vez de subir com segredo conhecido.

.env — obrigatórias

# Núcleo
PORT=80
TZ=America/Sao_Paulo
NODE_ENV=production

# PostgreSQL
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DATABASE=openscale
POSTGRES_USER=openscale
POSTGRES_PASSWORD=defina-uma-senha-forte

# HTTP: requestTimeout DEVE ser maior que o tempo máximo da consulta longa (600 s),
# e o proxy reverso precisa de read timeout >= 600 s.
HTTP_REQUEST_TIMEOUT_MS=660000
SESSION_COOKIE_SECURE=true

# Armazenamento de objetos
MINIO_ENDPOINT=http://minio:9000
MINIO_ACCESS_KEY=defina
MINIO_SECRET_KEY=defina
MINIO_REGION=us-east-1

# Base pública que os agentes usam para se conectar de volta.
# Vazio = derivada do cabeçalho Host da requisição, o que quebra atrás de proxy mal configurado.
AGENT_PUBLIC_API_BASE_URL=https://openscale.suaempresa.com.br

POSTGRES_DATABASE, não POSTGRES_DB

O nome lido pelo produto é POSTGRES_DATABASE. Usar POSTGRES_DB não produz erro: a conexão cai no valor padrão interno e a aplicação sobe apontando para o banco errado — sintoma que se manifesta como “instalei e está tudo vazio”.

Variável que você deve definir antes do primeiro dado

.env — antes do primeiro dado

# Cifra em repouso dos segredos do cofre (credenciais de SSH e de destinos de backup) — AES-256-GCM.
# Gere com: openssl rand -hex 32
MANAGER_SECRET_ENC_KEY=

Vazia, os segredos do cofre ficam em texto plano no banco.

Defina antes de cadastrar o primeiro segredo, e não a troque depois. Trocar a chave torna ilegível tudo que foi cifrado com a anterior — não há recuperação.

Variáveis opcionais

Grupo	Quando definir
MANAGER_LDAP_*	Autenticação por Active Directory ou LDAP. Liga apenas quando MANAGER_LDAP_URL está preenchida. Ver Autenticação.
EVOLUTION_*, AUTHENTICATION_API_KEY	Somente se for usar mensageria de WhatsApp.
AGENT_*	Comportamento dos agentes de endpoint: cadência de heartbeat, intervalo de trabalhos, mapa de bucket por cliente.
MANAGER_*_RETENTION_DAYS	Retenção de telemetria, heartbeats, eventos de agente, eventos de impressão, trabalhos e execuções. 0 desliga a poda — não deixe em zero com frota.
MANAGER_WORKERS	Número de processos da aplicação. Ausente ou 1 roda um só; auto distribui entre os núcleos.

O que NÃO é requisito

• Redis — não é exigido pela aplicação.
• Servidor de e-mail — só se for usar chamado por e-mail ou redefinição de senha por link.
• Evolution API — só para mensageria de WhatsApp.
• Volume no contêiner da aplicação — ele não tem estado. Se a sua receita cria um volume para ele, remova: não há o que persistir ali.

Próximo passo

Instalação com Docker