Tudo começa na imagem

Usar docker manifest inspect para enxergar, num registry real, exatamente as peças da tabela acima: o índice multi-plataforma, o manifest de cada plataforma e as camadas. Depois, olhar por dentro da sua própria imagem para ver o mesmo formato Docker gravado em disco, e rodar localmente, via QEMU, cada uma das plataformas do índice inspecionado.

Parte 1 · O índice multi-plataforma

1. Peça o manifesto de uma imagem multi-plataforma do Docker Hub. Sem --verbose, o Docker resolve para a plataforma do seu host e mostra só aquele manifest:

   terminal

   docker manifest inspect nginx:stable-alpine

   Repare no mediaType do manifest (…docker.distribution.manifest.v2+json) e na lista layers, cada uma com seu próprio mediaType (…docker.image.rootfs.diff.tar.gzip) e digest.

2. Agora peça o manifesto sem resolver a plataforma: o --verbose mostra o índice completo, com um manifest por arquitetura:

   terminal

   docker manifest inspect --verbose nginx:stable-alpine

   O conjunto dessas entradas, uma por Platform.architecture, é a manifest list — o equivalente Docker do image index da OCI. Conte quantas plataformas aparecem.

Parte 2 · Sua imagem, o mesmo formato, gravado em disco

1. A imagem do exercício 1.1 ainda não foi para um registry, então docker manifest inspect não a alcança — ele só lê de registries. Para ver o formato Docker local, exporte-a com docker save:

   terminal

   docker save "$IMAGE:1.0.0" -o /tmp/site.tar

   Agora liste o conteúdo do tar:

   terminal

   tar -tvf /tmp/site.tar

   Aparecem um manifest.json, um repositories e um arquivo por camada — exatamente a linha "Em disco" da tabela para o formato Docker, sem oci-layout nem index.json.

2. Abra o manifest.json e confira que ele referencia o Config e a lista de Layers da sua imagem, descritos no mesmo vocabulário do formato Docker que você viu na Parte 1:

   terminal

   tar -xOf /tmp/site.tar manifest.json | python3 -m json.tool

Parte 3 · Rodando as duas plataformas do índice, via QEMU

1. Registre os emuladores QEMU no host (uma vez por Codespace):

   terminal

   docker run --privileged --rm tonistiigi/binfmt --install all

2. Emular a imagem de uma arquitetura ARM64 — o manifest linux/arm64 do índice, traduzido instrução a instrução pelo QEMU:

   terminal

   docker run --rm --platform linux/arm64 alpine:3.22 uname -m   # → aarch64, emulado

3. Emular a imagem de uma arquitetura AMD64 — o manifest linux/amd64 do mesmo índice, nativo na arquitetura do Codespace:

   terminal

   docker run --rm --platform linux/amd64 alpine:3.22 uname -m   # → x86_64, nativo

Validar o Docker no Codespaces, escrever um Dockerfile, construir a imagem e testá-la. A imagem criada aqui é a base dos próximos exercícios.

Parte 1 · Preparando o ambiente

1. Confira o cliente e o servidor Docker:

   terminal

   docker version

   Rode o primeiro container:

   terminal

   docker run --rm hello-world

2. Compare o kernel e a distribuição do host (tópico 1.1 na prática):

   terminal

   uname -r; grep PRETTY_NAME /etc/os-release

   Agora os mesmos dados, vistos de dentro de um container Alpine:

   terminal

   docker run --rm alpine:3.22 sh -c 'uname -r; grep PRETTY_NAME /etc/os-release'

Parte 2 · Criando a imagem

1. Crie a pasta do laboratório e entre nela:

   terminal

   mkdir -p ~/labs/site && cd ~/labs/site

   Crie a página:

   terminal

   cat > index.html <<'EOF'
   <!doctype html>
   <html lang="pt-BR">
   <head><meta charset="utf-8"><title>Container Technologies | Lab</title></head>
   <body>
     <h1>Container Technologies</h1>
     <p>Minha primeira imagem Docker no GitHub Codespaces.</p>
     <p>Versão da aplicação: 1.0.0</p>
   </body>
   </html>
   EOF

2. Crie o Dockerfile:

   terminal

   cat > Dockerfile <<'EOF'
   FROM nginx:stable-alpine
   LABEL org.opencontainers.image.title="site" \
         org.opencontainers.image.description="Página servida pelo NGINX"
   COPY index.html /usr/share/nginx/html/index.html
   EXPOSE 80
   HEALTHCHECK --interval=10s --timeout=3s CMD wget -qO- http://localhost/ || exit 1
   CMD ["nginx", "-g", "daemon off;"]
   EOF

   Confira o arquivo gerado:

   terminal

   cat Dockerfile

3. Crie o .dockerignore para tirar do contexto de build o que não deve ir para a imagem:

   terminal

   cat > .dockerignore <<'EOF'
   .git
   *.md
   .env
   EOF

   Confira o arquivo gerado:

   terminal

   cat .dockerignore

4. Defina o usuário do Docker Hub e o nome da imagem (variáveis usadas até o exercício 1.7):

   terminal

   export DOCKERHUB_USER="seu-usuario-dockerhub"
   export IMAGE="$DOCKERHUB_USER/container-technologies"

   Construa a imagem:

   terminal

   docker build -t "$IMAGE:1.0.0" .

   Confira que ela aparece no cache local:

   terminal

   docker image ls "$IMAGE"

5. Execute um container a partir da imagem criada. -d roda em segundo plano, --name dá um nome e -p 8080:80 liga a porta 8080 do Codespaces à porta 80 do container:

   terminal

   docker run -d --name site -p 8080:80 "$IMAGE:1.0.0"

6. Liste os containers em execução. Aguarde alguns segundos até o STATUS mostrar (healthy), resultado do HEALTHCHECK:

   terminal

   docker ps

7. Acesse a aplicação pelo terminal e, depois, pelo navegador na aba Ports (porta 8080):

   terminal

   curl localhost:8080

8. Pare e remova o container em execução:

   terminal

   docker rm -f site

   Confirme que ele sumiu da lista:

   terminal

   docker ps -a --filter name=site

Abrir a imagem criada no exercício 1.1 para ver na prática a anatomia OCI (tópico 1.4) e o efeito das camadas e do cache no tamanho e no tempo de build.

Parte 1 · Anatomia da sua imagem

1. O Cmd e o Entrypoint herdados da base:

   terminal

   docker image inspect "$IMAGE:1.0.0" --format 'Cmd={{json .Config.Cmd}} Entrypoint={{json .Config.Entrypoint}}'

   As labels OCI que você definiu no Dockerfile:

   terminal

   docker image inspect "$IMAGE:1.0.0" --format 'Labels={{json .Config.Labels}}'

   Quantas camadas a sua imagem tem:

   terminal

   docker image inspect "$IMAGE:1.0.0" --format '{{len .RootFS.Layers}} camadas'

   E quantas a imagem base já trazia:

   terminal

   docker image inspect nginx:stable-alpine --format '{{len .RootFS.Layers}} camadas na base'

   Por fim, o histórico completo de instruções:

   terminal

   docker history "$IMAGE:1.0.0"

2. O documento que o registry devolve para a imagem base (index ou manifest list):

   terminal

   docker buildx imagetools inspect --raw nginx:stable-alpine | python3 -m json.tool | head -25

3. Crie a pasta e entre nela:

   terminal

   mkdir -p ~/labs/oci && cd ~/labs/oci

   Exporte a sua imagem no formato OCI:

   terminal

   docker save "$IMAGE:1.0.0" -o site.tar

   Extraia o tar e liste o conteúdo:

   terminal

   tar -xf site.tar && ls

   Veja o oci-layout:

   terminal

   cat oci-layout; echo

   E o início do index.json:

   terminal

   python3 -m json.tool index.json | head -20

   Por fim, os blobs de conteúdo (camadas e config, endereçados por digest):

   terminal

   ls blobs/sha256 | head

Parte 2 · Camadas e cache

1. Veja qual backend de armazenamento o seu Docker usa:

   terminal

   docker info --format 'Storage Driver: {{.Driver}}'

   Com mais contexto (snapshotter, se for containerd image store):

   terminal

   docker info | grep -iA2 'storage driver'

2. Crie a pasta e entre nela:

   terminal

   mkdir -p ~/labs/camadas && cd ~/labs/camadas

   Crie um Dockerfile que escreve e apaga um arquivo de 50 MB em instruções RUN separadas:

   terminal

   cat > Dockerfile.ruim <<'EOF'
   FROM alpine:3.22
   RUN dd if=/dev/zero of=/lixo bs=1M count=50
   RUN rm /lixo
   EOF

   Construa a imagem:

   terminal

   docker build -f Dockerfile.ruim -t camadas:ruim .

   Veja o tamanho de cada camada no histórico:

   terminal

   docker history camadas:ruim | head -4

3. Agora o mesmo resultado, escrevendo e apagando o arquivo numa única instrução:

   terminal

   cat > Dockerfile.bom <<'EOF'
   FROM alpine:3.22
   RUN dd if=/dev/zero of=/lixo bs=1M count=50 && rm /lixo
   EOF

   Construa e compare o tamanho final das duas imagens:

   terminal

   docker build -f Dockerfile.bom -t camadas:bom .

   terminal

   docker image ls camadas

4. Altere só o HTML do site:

   terminal

   cd ~/labs/site && sed -i 's/1.0.0/1.0.1/' index.html

   Reconstrua e observe quais etapas usam CACHED:

   terminal

   docker build -t "$IMAGE:1.0.1" .

Validar o Dockerfile do exercício 1.1, depois corrigir um Dockerfile cheio de más práticas até o Hadolint aprovar.

1. Entre na pasta do Dockerfile criado no exercício 1.1:

   terminal

   cd ~/labs/site

   Valide-o com o Hadolint:

   terminal

   docker run --rm -i hadolint/hadolint < Dockerfile && echo "Dockerfile OK"

2. Crie a pasta e entre nela:

   terminal

   mkdir -p ~/labs/lint && cd ~/labs/lint

   Crie uma aplicação mínima:

   terminal

   echo 'print("ola, containers")' > app.py

   Crie um Dockerfile cheio de más práticas:

   terminal

   cat > Dockerfile <<'EOF'
   FROM ubuntu:latest
   MAINTAINER aluno@example.com
   RUN apt-get update
   RUN apt-get install -y python3 curl
   ADD app.py /app/app.py
   WORKDIR /app
   CMD python3 app.py
   EOF

   Analise-o com o Hadolint:

   terminal

   docker run --rm -i hadolint/hadolint < Dockerfile

3. Corrija até não restar aviso:

   terminal

   cat > Dockerfile <<'EOF'
   FROM python:3.13-alpine
   LABEL org.opencontainers.image.authors="aluno@example.com"
   WORKDIR /app
   COPY app.py .
   RUN adduser -D -u 10001 app
   USER app
   CMD ["python3", "app.py"]
   EOF

   Confira que o Hadolint aprova:

   terminal

   docker run --rm -i hadolint/hadolint < Dockerfile && echo "Dockerfile OK"

   Construa e rode:

   terminal

   docker build -t lint-ok . && docker run --rm lint-ok

Antes de otimizar, medir. Comparar tamanho, pacotes e vulnerabilidades de imagens base, avaliar a sua própria imagem, usar o Trivy como gate de pipeline e gerar o SBOM da imagem.

1. Crie um alias para o Trivy (via container, com cache persistente):

   terminal

   alias trivy='docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v $HOME/.cache/trivy:/root/.cache aquasec/trivy:latest'

   Confira que funciona:

   terminal

   trivy --version

2. Baixe algumas imagens base:

   terminal

   for i in ubuntu:24.04 debian:12 alpine:3.22 busybox:1.36 cgr.dev/chainguard/wolfi-base:latest; do docker pull -q $i; done

   Compare os tamanhos:

   terminal

   docker image ls --format 'table {{.Repository}}:{{.Tag}}\t{{.Size}}' | grep -E 'ubuntu|debian|alpine|busybox|wolfi'

3. Conte pacotes e vulnerabilidades de cada uma:

   terminal

   for i in ubuntu:24.04 debian:12 alpine:3.22 cgr.dev/chainguard/wolfi-base:latest; do
     echo "== $i"
     trivy image --quiet --list-all-pkgs --format json $i | python3 -c "import json,sys; d=json.load(sys.stdin); print('pacotes:', sum(len(r.get('Packages',[])) for r in d.get('Results',[])))"
     trivy image --quiet --scanners vuln $i | grep -E '^Total'
   done

4. Avalie a sua imagem:

   terminal

   trivy image --severity HIGH,CRITICAL "$IMAGE:1.0.1"

   Baixe uma imagem antiga e cheia de CVEs conhecidas:

   terminal

   docker pull -q python:3.4-alpine

   Use o exit code do Trivy como gate de pipeline:

   terminal

   trivy image --exit-code 1 --severity HIGH,CRITICAL --quiet python:3.4-alpine > /dev/null; echo "python:3.4-alpine → exit $?"

5. Gere o SBOM da sua imagem:

   terminal

   trivy image --quiet --format cyclonedx "$IMAGE:1.0.1" > ~/labs/sbom-site.json

   Consulte o inventário de componentes:

   terminal

   python3 -c "import json; d=json.load(open('$HOME/labs/sbom-site.json')); c=d['components']; print(len(c),'componentes'); [print(x['name'],x.get('version','')) for x in c if x['name'] in ('openssl','libssl3','musl','busybox','nginx','zlib')]"

Construir a mesma aplicação Go em estágio único e em multi-stage com distroless, e provar a diferença com os números e com o Trivy. Guarde esta pasta: a aplicação volta na Aula 05.

1. Crie a pasta e entre nela:

   terminal

   mkdir -p ~/labs/app-go && cd ~/labs/app-go

   Crie o go.mod:

   terminal

   printf 'module example.com/app-go\n\ngo 1.25\n' > go.mod

   Crie a aplicação (responde em / e /healthz e trata SIGTERM):

   terminal

   cat > main.go <<'EOF'
   package main
   
   import (
       "context"
       "fmt"
       "log"
       "net/http"
       "os"
       "os/signal"
       "syscall"
       "time"
   )
   
   func main() {
       host, _ := os.Hostname()
       version := os.Getenv("APP_VERSION")
       if version == "" {
           version = "v1"
       }
       mux := http.NewServeMux()
       mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
           fmt.Fprintf(w, "Container Technologies | versao=%s | host=%s\n", version, host)
       })
       mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
           w.Write([]byte("ok\n"))
       })
       srv := &http.Server{Addr: ":8080", Handler: mux}
       go func() {
           log.Printf("ouvindo em :8080 (versao %s)", version)
           if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
               log.Fatal(err)
           }
       }()
       stop := make(chan os.Signal, 1)
       signal.Notify(stop, syscall.SIGTERM, os.Interrupt)
       <-stop
       log.Println("SIGTERM recebido, encerrando conexoes...")
       ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
       defer cancel()
       srv.Shutdown(ctx)
   }
   EOF

2. Crie a versão em estágio único:

   terminal

   cat > Dockerfile.single <<'EOF'
   FROM golang:1.25
   WORKDIR /src
   COPY . .
   RUN go build -o /usr/local/bin/app .
   EXPOSE 8080
   CMD ["app"]
   EOF

   Construa-a:

   terminal

   docker build -f Dockerfile.single -t app-go:single .

3. Crie a versão multi-stage com distroless:

   terminal

   cat > Dockerfile <<'EOF'
   FROM golang:1.25-alpine AS build
   WORKDIR /src
   COPY go.mod ./
   RUN go mod download
   COPY . .
   RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /out/app .
   
   FROM gcr.io/distroless/static-debian12:nonroot
   COPY --from=build /out/app /app
   USER nonroot:nonroot
   EXPOSE 8080
   ENTRYPOINT ["/app"]
   EOF

   Construa-a:

   terminal

   docker build -t app-go:v1 .

   Compare o tamanho das duas:

   terminal

   docker image ls app-go

4. Rode a imagem final:

   terminal

   docker run -d --name go1 -p 8081:8080 app-go:v1

   Teste os dois endpoints:

   terminal

   curl -s localhost:8081; curl -s localhost:8081/healthz

   Tente abrir um shell (deve falhar: não há shell na imagem):

   terminal

   docker exec -it go1 sh

   Confira que roda como usuário não-root:

   terminal

   docker image inspect app-go:v1 -f 'User={{.Config.User}}'

   Pare, veja o log de encerramento e remova:

   terminal

   docker stop go1 && docker logs go1 | tail -2 && docker rm go1

5. Prove com o Trivy (alias do exercício 1.5) a diferença de vulnerabilidades entre as duas imagens:

   terminal

   for i in app-go:single app-go:v1; do echo "== $i"; trivy image --quiet --scanners vuln $i | grep -E '^Total' | head -3; done

   Use a distroless como gate de pipeline:

   terminal

   trivy image --exit-code 1 --severity HIGH,CRITICAL --quiet app-go:v1 > /dev/null; echo "app-go:v1 → exit $?"

Fechar o ciclo da imagem: publicar com uma estratégia de tags, conferir os digests, executar a partir do registry e gerar uma versão para amd64 e arm64 (o índice OCI do tópico 1.2).

Parte 1 · Tags e push

1. Entre na pasta da imagem:

   terminal

   cd ~/labs/site

   No Docker Hub, crie um Personal access token (Account settings → Personal access tokens) e o repositório container-technologies. Depois faça login:

   terminal

   docker login -u "$DOCKERHUB_USER"      # cole o token quando pedir a senha

2. Defina a versão e o SHA curto do commit:

   terminal

   VERSION=1.0.1
   SHA=$(git rev-parse --short HEAD 2>/dev/null || echo local)

   Aplique as tags de série, commit e a tag recomendada (versão + SHA) à mesma imagem:

   terminal

   docker tag "$IMAGE:$VERSION" "$IMAGE:1.0"
   docker tag "$IMAGE:$VERSION" "$IMAGE:sha-$SHA"
   docker tag "$IMAGE:$VERSION" "$IMAGE:v$VERSION-$SHA"      # recomendado: vMAJOR.MINOR.PATCH-sha

   Publique todas as tags:

   terminal

   docker push --all-tags "$IMAGE"

3. Confirme que as tags apontam para o mesmo digest:

   terminal

   for t in 1.0.1 1.0 sha-$SHA v1.0.1-$SHA; do echo -n "$t → "; docker buildx imagetools inspect "$IMAGE:$t" --format '{{json .Manifest.Digest}}'; done

   Remova as imagens locais para forçar o pull do registry:

   terminal

   docker image rm $(docker image ls "$IMAGE" -q) --force

   Rode a partir do registry:

   terminal

   docker run -d --name site -p 8080:80 "$IMAGE:1.0.1" && sleep 2

   Confira a resposta e limpe:

   terminal

   curl -s localhost:8080 | grep Versão; docker rm -f site

Parte 2 · Uma imagem, várias plataformas

1. Confira a arquitetura do host:

   terminal

   uname -m

   Habilite a emulação com QEMU:

   terminal

   docker run --privileged --rm tonistiigi/binfmt --install arm64

   Rode uma imagem arm64 no mesmo host amd64:

   terminal

   docker run --rm --platform linux/arm64 alpine:3.22 uname -m

2. Altere a versão exibida pela página:

   terminal

   sed -i 's/1.0.1/1.1.0/' index.html

   Crie um builder multi-plataforma:

   terminal

   docker buildx create --name multi --use

   Construa e publique a versão 1.1.0 para as duas arquiteturas:

   terminal

   docker buildx build --platform linux/amd64,linux/arm64 -t "$IMAGE:1.1.0" --push .

   Confira o índice gerado:

   terminal

   docker buildx imagetools inspect "$IMAGE:1.1.0"