Configuração do Motor e do Orquestrador Local

A preparação do ambiente começa pela instalação do daemon e da ferramenta de composição de serviços. Em distribuições baseadas em Debian, o processo pode ser realizado via gerenciador de pacotes oficial, seguido da habilitação do serviço no systemd.

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker.service

Para o gerenciamento de múltiplos contêineres, o binário do Compose pode ser obtido diretamente do repositório oficial. O exemplo abaixo demonstra o download, a atribuição de permissão de execução e a criação de um link simbólico para acesso global.

COMPOSE_URL="https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64"
sudo curl -SL "$COMPOSE_URL" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
sudo ln -sf /usr/local/bin/docker-compose /usr/bin/docker-compose
docker-compose version

Em sistemas RHEL/CentOS, o mesmo binário é compatível. Alternativamente, a instalação via pip (pip3 install docker-compose) ou a execução como contêiner efêmero são estratégias válidas para ambientes com restrições de pacotes.

Ciclo de Vida e Resolução de Conflitos de Nomenclatura

Após reinicializações do host, o daemon deve ser ativado antes de qualquer interação com os recursos. A listagem de instâncias ativas e inativas permite auditoria rápida do estado atual.

sudo systemctl start docker
docker container ls              # Exibe apenas processos em execução
docker container ls --all        # Inclui instâncias paradas ou com falha

Caso ocorra o erro Conflict. The container name "/xyz" is already in use, significa que um recurso com o mesmo identificador já está registrado no banco de dados local. A correção exige a parada e remoção explícita do conflito antes da recriação.

docker container stop legacy_app_01
docker container rm legacy_app_01
# Ou remoção direta pelo hash curto:
docker container rm --force a1b2c3d4e5f6

Para limpeza geral de recursos órfãos (imagens não taggeadas, volumes desconectados e redes não utilizadas), o comando de poda libera espaço em disco de forma segura.

docker system prune --all --volumes --force

Inicialização, Mapeamento e Execução Interna

O comando run é responsável por criar e iniciar uma nova instância. A combinação de flags define isolamento, rede, armazenamento e limites de hardware. Abaixo, uma estrutura reorganizada para inicialização com variáveis de ambiente, limites de recursos e script de entrada personalizado.

docker run -d \
  --name api_gateway_v2 \
  -p 9090:8080 \
  -e APP_ENV="production" \
  -e DB_CONN_STRING="postgres://admin:secret@db.local:5432/main" \
  -v /opt/gateway/config:/etc/app/conf:ro \
  -v /opt/gateway/data:/var/lib/app/data \
  --memory="1g" \
  --cpuset-cpus="0,2" \
  --dns 1.1.1.1 \
  registry.internal/gateway:3.4.1 \
  sh -c "/scripts/preload.sh && exec /bin/server --port 8080"

Principais parâmetros aplicados:

• -d: Execução desacoplada do terminal atual.
• -p: Roteamento estático de porta do host para o processo interno.
• -v: Montagem de diretórios com opção de leitura exclusiva (:ro) quando necessário.
• --memory / --cpuset-cpus: Restrição de consumo de RAM e afinidade de núcleos de processamento.
• sh -c: Encadeamento de comandos de inicialização antes da execução do processo principal.

Para diagnóstico ou execução de tarefas pontuais em instâncias já ativas, utilize exec. Diferente do run, ele não cria um novo contêiner, mas injeta um processo no namespace existente.

# Acesso interativo ao shell
docker exec -it api_gateway_v2 /bin/bash

# Execução única de verificação sem TTY
docker exec api_gateway_v2 cat /var/lib/app/data/health.status
docker exec api_gateway_v2 /bin/server --version | grep build_id

Controle, Rotação e Limpeza de Registros

O acompanhamento em tempo real é feito via docker logs -f <id_ou_nome>. Contudo, a ausência de política de rotação pode consumir partições inteiras. Os arquivos brutos residem em /var/lib/docker/containers/<container_id>/ com sufixo -json.log.

Para truncamento manual sem reiniciar o serviço, utilize redirecionamento seguro ou o utilitário truncate:

CONTAINER_HASH=$(docker inspect --format='{{.Id}}' api_gateway_v2)
sudo truncate -s 0 /var/lib/docker/containers/${CONTAINER_HASH}/${CONTAINER_HASH}-json.log

A abordagem recomendada para ambientes produtivos é definir limites no nível do orquestrador ou no daemon. No Compose, a configuração de driver de log previne acúmulo excessivo:

services:
  backend_worker:
    image: registry.internal/worker:latest
    logging:
      driver: "json-file"
      options:
        max-size: "15m"
        max-file: "4"
        compress: "true"

Essa estrutura garante que, ao atingir 15MB, o arquivo seja compactado e rotacionado, mantendo no máximo quatro arquivos históricos por instância.