Organizando um laboratório Protheus: boas práticas com Docker Compose

Versão de referência: este artigo foi revisado com base no commit 77562cd , que registra o estado validado da segunda parte do Protheus Docker Lab.

No primeiro artigo da série, Construindo um laboratório Protheus com Docker , montei um ambiente de desenvolvimento composto por PostgreSQL, DBAccess, License Server e AppServer.

Colocar os serviços em execução foi a primeira etapa. A seguinte foi transformar um arquivo Compose funcional em um projeto que eu pudesse entender, validar, recriar e evoluir.

Essa diferença parece pequena, mas é importante:

Um ambiente não se torna reproduzível apenas porque existe um docker-compose.yml.

Também precisamos organizar configuração, dependências, artefatos locais, volumes e procedimentos operacionais.

O problema de concentrar tudo no Compose

Durante uma prova de conceito, é tentador colocar imagens, portas, credenciais, comandos e grandes blocos de configuração diretamente no docker-compose.yml.

O arquivo cresce rapidamente e começa a misturar responsabilidades:

• definição dos serviços;
• valores específicos de cada máquina;
• segredos;
• arquivos obrigatórios do Protheus;
• dados persistentes;
• comandos de preparação;
• procedimentos de validação.

Além de dificultar a leitura, essa mistura torna menos claro o que pode ser versionado e o que precisa permanecer local.

A estrutura adotada no laboratório

O projeto foi separado por finalidade:

protheus-docker-lab/
|-- .dockerignore
|-- .env.example
|-- .gitignore
|-- docker-compose.yml
|-- config/
|   |-- appserver.ini.example
|   |-- odbc.ini.example
|   `-- odbcinst.ini.example
|-- docs/
|   `-- anotacoes-laboratorio.md
|-- files/
|   `-- .gitkeep
|-- scripts/
|   |-- check.sh
|   |-- generate-dbaccess.sh
|   |-- up.sh
|   |-- down.sh
|   `-- logs.sh
|-- volumes/
|   |-- apo/
|   |-- systemload/
|   `-- logs/
`-- README.md

Cada diretório responde a uma pergunta:

• config/: quais configurações os serviços precisam?
• scripts/: como preparar, validar e operar o ambiente?
• files/: onde colocar temporariamente artefatos locais?
• volumes/: quais dados precisam sobreviver ao container?
• docs/: quais evidências, erros e decisões precisam ser preservados?
• README.md: como outra pessoa reproduz o fluxo?

Os artefatos proprietários e arquivos efetivos do ambiente não são publicados no Git. O .gitignore mantém fora do repositório o .env, os arquivos .ini efetivos, o conteúdo de files/ e os dados de execução em volumes/. Arquivos .gitkeep preservam apenas a estrutura vazia necessária para orientar a preparação.

Serviços com responsabilidades explícitas

O Compose mantém quatro serviços:

A separação ajuda a observar logs, reiniciar componentes e entender as dependências sem instalar tudo diretamente no host.

Ela não significa isolamento completo. Os serviços continuam formando um único sistema e precisam de contratos coerentes de rede, portas, arquivos e inicialização.

Variáveis que pertencem ao ambiente

Valores que podem mudar entre máquinas ficam no .env:

COMPOSE_PROJECT_NAME=protheus-docker-lab
LICENSE_IMAGE=totvsengpro/license-dev
POSTGRES_IMAGE=totvsengpro/postgres-dev:12.1.2510_bra
DBACCESS_IMAGE=totvsengpro/dbaccess-postgres-dev
APPSERVER_IMAGE=totvsengpro/appserver-dev
APPSERVER_PORT=1234
WEBAPP_PORT=8080

O repositório publica apenas .env.example, com nomes e valores seguros para servir de referência. O .env efetivo permanece local.

Essa estratégia reduz duplicação e permite atualizar imagens e portas sem reescrever o Compose. No entanto, um arquivo .env não é um cofre de segredos. Em ambientes compartilhados ou corporativos, credenciais precisam de um mecanismo apropriado de gerenciamento.

Configuração de exemplo e configuração efetiva

O laboratório distingue arquivos que podem ser versionados daqueles gerados ou adaptados localmente:

config/appserver.ini.example  -> config/appserver.ini
config/dbaccess.ini          -> gerado localmente
config/odbc.ini              -> gerado localmente
config/odbcinst.ini          -> gerado localmente

O repositório também mantém exemplos de ODBC para consulta. No fluxo recomendado, entretanto, os três arquivos efetivos do DBAccess e do ODBC são produzidos localmente pelo script e continuam ignorados pelo Git.

O DBAccess merece cuidado especial. A senha precisa ser codificada no formato esperado pela ferramenta dbaccesscfg. Editar manualmente o resultado pode produzir um arquivo aparentemente correto, mas inválido para o serviço.

Por isso, o script generate-dbaccess.sh executa a ferramenta da própria imagem e gera a configuração efetiva:

./scripts/generate-dbaccess.sh

O script carrega as variáveis do .env, executa o dbaccesscfg da imagem configurada e grava dbaccess.ini, odbc.ini e odbcinst.ini. Com isso, a senha codificada fica no formato produzido pela própria ferramenta, sem precisar ser copiada ou editada manualmente.

Dependência não é prontidão

O PostgreSQL possui um healthcheck:

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB} -h localhost -p ${POSTGRES_PORT}"]
  interval: 5s
  timeout: 3s
  retries: 20
  start_period: 10s

O DBAccess aguarda o banco ficar saudável:

depends_on:
  postgres-iniciado:
    condition: service_healthy

Isso é melhor do que depender apenas da ordem de criação dos containers, mas possui um limite: pg_isready confirma que o PostgreSQL aceita conexões; ele não garante que o banco esteja completamente preparado para o Protheus.

Da mesma forma, condition: service_started informa que um container iniciou, não que sua função de negócio está pronta.

Essa distinção orienta a próxima etapa do lab: criar validações funcionais além do estado dos containers.

Volumes e artefatos locais

O AppServer precisa acessar RPO, systemload e logs:

volumes:
  - ./volumes/apo/tttm120.rpo:/opt/totvs/protheus/apo/tttm120.rpo
  - ./volumes/systemload:/opt/totvs/protheus/protheus_data/systemload
  - ./volumes/logs:/opt/totvs/appserver/logs

Os bind mounts deixam explícita a origem de cada arquivo no host, o que ajuda em um laboratório local. Eles também criam responsabilidades:

• preparar os diretórios antes da subida;
• conferir permissões;
• manter uma origem limpa do RPO;
• evitar que artefatos proprietários entrem no Git;
• entender quais dados podem ser descartados.

Durante os testes iniciais, o diretório systemload precisou permanecer gravável. Esse tipo de descoberta deve fazer parte da documentação, pois não aparece apenas pela leitura do Compose.

Nomes e caminhos previsíveis

Dentro da rede do Compose, os serviços podem se localizar pelo nome. Assim, o DBAccess usa postgres-iniciado como host e o AppServer usa dbaccess-postgres.

Os caminhos internos também foram padronizados:

Essa tabela reduz o conhecimento implícito e facilita conferir os mounts.

Validando a configuração antes de subir

O Docker Compose consegue renderizar e validar sua configuração consolidada:

docker compose config

O laboratório envolve essa validação em scripts/check.sh, que também verifica Docker e arquivos obrigatórios:

./scripts/check.sh

Essa verificação antecipa erros como ausência de .env, RPO, arquivos de systemload ou configurações geradas.

Ela ainda é uma validação de preparação, não uma prova de que o Protheus responde corretamente depois da subida.

O que melhorou

Com a separação, o ambiente passa a ter:

• um Compose focado na topologia;
• variáveis externas para imagens e portas;
• configurações versionáveis como exemplos;
• arquivos sensíveis ou proprietários fora do repositório;
• diretórios explícitos para persistência;
• validação antes da execução;
• documentação conectada à estrutura real.

Evidências da etapa

As evidências documentam, entre outros pontos, a conexão do DBAccess com PostgreSQL, o carregamento do ambiente PROTHEUS_DOCKER, o acesso pelo WebApp e a necessidade de manter systemload gravável neste laboratório. Elas também deixam claros os limites do healthcheck e das condições de inicialização usadas pelo Compose.

Próximo passo

Organização reduz ambiguidade, mas o processo ainda possui comandos manuais. Na próxima parte, vamos consolidar a automação e a configuração local. Dados, manutenção e a validação final do laboratório ficam para as partes seguintes da série.

O repositório do projeto está disponível em:

github.com/dirleiflsilva/protheus-docker-lab

Referências

• Docker Docs: Compose
• Docker Docs: controle de inicialização no Compose
• Protheus Docker — TOTVS Engineering Pro
• Protheus Docker Lab — commit de referência