Containers e Docker

Os números desta página vêm de construções reais com Docker, numa aplicação Node pequena com uma dependência de produção e duas de desenvolvimento, e numa API Go mínima. Os tamanhos variam com as versões das imagens base; as proporções são o que importa.

Um Dockerfile para Node: do ingênuo ao cuidadoso

A versão que costuma aparecer primeiro:

FROM node:24
WORKDIR /app
COPY . .
RUN npm install
CMD npm start

A versão cuidadosa:

# Estágio 1: instala só as dependências de produção
FROM node:24-alpine AS dependencias
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

# Estágio 2: a imagem que vai para produção
FROM node:24-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=dependencias /app/node_modules ./node_modules
COPY . .
USER node
EXPOSE 3000
CMD ["node", "server.js"]

O que medimos com as duas:

Cada linha da tabela vem de uma decisão do Dockerfile:

Para TypeScript, acrescente um estágio que instala todas as dependências e roda a compilação, e copie para a imagem final só a pasta gerada.

Um Dockerfile para Go: binário estático

FROM golang:1.24-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /api .

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /api /api
EXPOSE 3000
ENTRYPOINT ["/api"]

CGO_ENABLED=0 gera um binário que não depende de nenhuma biblioteca do sistema, e -ldflags="-s -w" remove informações de depuração. A imagem final ficou com 14 MB e roda como um usuário sem privilégios, já definido pela variante nonroot da base. Não há shell: uma tentativa de executar sh dentro do container falhou.

Para as outras linguagens, a estrutura é a mesma, com estas peças:

A aplicação preparada para container

Um container bem construído também depende de como a aplicação se comporta dentro dele. Três regras resolvem a maior parte:

• Configuração pelo ambiente: a mesma imagem roda em testes e em produção, com variáveis diferentes.
• Falhar logo se faltar configuração: melhor o container não subir do que subir e falhar no primeiro pedido.
• Logs na saída padrão: o Docker e o orquestrador coletam o que sai em stdout. Gravar em arquivos dentro do container perde os logs a cada substituição.

O encerramento gracioso, a quarta regra, está no tópico de escalabilidade.

function obrigatoria(nome: string): string {
  const valor = process.env[nome];
  if (!valor) {
    log("erro", `variável de ambiente ${nome} ausente`);
    process.exit(1);
  }
  return valor;
}

function log(nivel: string, mensagem: string, extra: object = {}) {
  console.log(JSON.stringify({
    hora: new Date().toISOString(),
    nivel,
    mensagem,
    ...extra,
  }));
}

export const config = {
  porta: Number(process.env.PORT ?? 3000),
  bancoUrl: obrigatoria("DATABASE_URL"),
};

log("info", "iniciando", { porta: config.porta });

import json
import logging
import os
import sys


class FormatoJson(logging.Formatter):
    def format(self, registro: logging.LogRecord) -> str:
        return json.dumps({
            "hora": self.formatTime(registro),
            "nivel": registro.levelname.lower(),
            "mensagem": registro.getMessage(),
        }, ensure_ascii=False)


saida = logging.StreamHandler(sys.stdout)
saida.setFormatter(FormatoJson())
logging.basicConfig(level=logging.INFO, handlers=[saida])
log = logging.getLogger("api")


def obrigatoria(nome: str) -> str:
    valor = os.environ.get(nome)
    if not valor:
        log.error("variável de ambiente %s ausente", nome)
        sys.exit(1)
    return valor


PORTA = int(os.environ.get("PORT", "3000"))
BANCO_URL = obrigatoria("DATABASE_URL")

log.info("iniciando na porta %s", PORTA)

package main

import (
	"log/slog"
	"os"
)

type Config struct {
	Porta    string
	BancoURL string
}

func carregarConfig(log *slog.Logger) Config {
	banco := os.Getenv("DATABASE_URL")
	if banco == "" {
		log.Error("variável de ambiente ausente", "nome", "DATABASE_URL")
		os.Exit(1)
	}
	porta := os.Getenv("PORT")
	if porta == "" {
		porta = "3000"
	}
	return Config{Porta: porta, BancoURL: banco}
}

func main() {
	log := slog.New(slog.NewJSONHandler(os.Stdout, nil))
	config := carregarConfig(log)
	log.Info("iniciando", "porta", config.Porta)
	// ... iniciar o servidor
}

import java.time.Instant;

public class Config {
    public final int porta;
    public final String bancoUrl;

    private Config(int porta, String bancoUrl) {
        this.porta = porta;
        this.bancoUrl = bancoUrl;
    }

    public static Config doAmbiente() {
        String banco = System.getenv("DATABASE_URL");
        if (banco == null || banco.isBlank()) {
            log("erro", "variável de ambiente DATABASE_URL ausente");
            System.exit(1);
        }
        String porta = System.getenv().getOrDefault("PORT", "3000");
        return new Config(Integer.parseInt(porta), banco);
    }

    // Em projetos reais, use o Logback ou o Log4j2 com um codificador JSON
    static void log(String nivel, String mensagem) {
        System.out.printf("{\"hora\":\"%s\",\"nivel\":\"%s\",\"mensagem\":\"%s\"}%n",
            Instant.now(), nivel, mensagem.replace("\"", "\\\""));
    }
}

var builder = WebApplication.CreateBuilder(args);

// Logs em JSON na saída padrão
builder.Logging.ClearProviders();
builder.Logging.AddJsonConsole();

// As variáveis de ambiente já fazem parte da configuração do ASP.NET
var bancoUrl = builder.Configuration["DATABASE_URL"]
    ?? throw new InvalidOperationException("variável de ambiente DATABASE_URL ausente");

var porta = builder.Configuration["PORT"] ?? "3000";
builder.WebHost.UseUrls($"http://0.0.0.0:{porta}");

var app = builder.Build();
app.Logger.LogInformation("iniciando na porta {Porta}", porta);
app.Run();

O que muda de uma linguagem para outra

Um detalhe que pega muita gente: a aplicação dentro do container precisa escutar em 0.0.0.0, e não em localhost. Escutando em localhost, ela só aceita conexões vindas de dentro do próprio container, e o mapeamento de porta do Docker não funciona.

Ambiente local com Docker Compose

Para desenvolver, o Docker Compose sobe a aplicação e as dependências com um comando:

# compose.yaml
services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://loja:loja@banco:5432/loja
      REDIS_URL: redis://cache:6379
    depends_on:
      banco:
        condition: service_healthy

  banco:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: loja
      POSTGRES_PASSWORD: loja
    volumes:
      - dados:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "loja"]
      interval: 2s
      retries: 15

  cache:
    image: redis:7-alpine

volumes:
  dados:

docker compose up --build

Três detalhes do arquivo:

• Os serviços se encontram pelo nome: a aplicação conecta em banco:5432, e não em localhost. O Compose cria uma rede com DNS interno.
• O healthcheck com condition: service_healthy faz a aplicação esperar o banco aceitar conexões, e não apenas o container do banco iniciar.
• O volume dados guarda os dados do PostgreSQL fora do container, e eles sobrevivem a um docker compose down. Com docker compose down -v, o volume é apagado.

As senhas do exemplo servem só para desenvolvimento local. Em produção, segredos vêm do orquestrador ou de um cofre de segredos, nunca de arquivos versionados.

Lista de revisão

Construção

• A imagem usa construção em estágios, sem ferramentas de construção na imagem final?
• As dependências são instaladas antes da cópia do código, com o arquivo de trava?
• Existe um .dockerignore que exclui .git, dependências locais, testes e .env?
• A imagem base tem versão fixada?
• Nenhum segredo está em nenhuma camada da imagem?

Execução

• O processo roda com um usuário sem privilégios?
• O CMD ou ENTRYPOINT está em forma de lista, ou o script termina com exec?
• A aplicação escuta em 0.0.0.0?
• A configuração vem de variáveis de ambiente, e a aplicação falha logo se faltar alguma?
• Os logs vão para a saída padrão?
• Dados que precisam sobreviver ficam fora do container?

Publicação

• Cada imagem tem uma etiqueta imutável, por versão ou commit?
• As imagens passam por varredura de vulnerabilidades?
• Existe uma rotina para reconstruir com a base atualizada?