Introdução
O Docker Buildx estende o comando docker build padrão com recursos aprimorados para criar imagens de múltiplas arquiteturas. No entanto, os usuários frequentemente encontram o erro "docker buildx build requires exactly 1 argument" (docker buildx build requer exatamente 1 argumento) ao trabalhar com esta ferramenta. Este tutorial abrangente irá guiá-lo através da compreensão do Docker Buildx, do diagnóstico deste erro comum e da implementação de soluções eficazes.
Ao final deste laboratório, você terá experiência prática na configuração do Docker Buildx, na criação de imagens Docker, na solução de problemas do erro "requires exactly 1 argument" e na construção de imagens para múltiplas arquiteturas. Essas habilidades são essenciais para o desenvolvimento e implantação modernos de aplicações em contêineres.
Configurando o Docker Buildx
O Docker Buildx vem pré-instalado com o Docker, mas precisa ser configurado corretamente antes de ser usado. Nesta etapa, vamos verificar se o Docker está instalado, habilitar o Docker Buildx e criar nossa primeira instância de builder.
Verificando a Instalação do Docker
Vamos primeiro confirmar se o Docker está instalado e em execução em nosso sistema:
docker --version
Você deve ver uma saída semelhante a:
Docker version 20.10.21, build baeda1f
Isso confirma que o Docker está instalado e pronto para uso.
Entendendo o Docker Buildx
O Docker Buildx é um plugin CLI que estende a funcionalidade do Docker com o BuildKit. Ele permite:
- Construir imagens para múltiplas plataformas (como AMD64, ARM64) simultaneamente
- Caching de camadas (layer caching) mais eficiente
- Melhor desempenho de construção
- Recursos avançados de construção
Criando um Docker Buildx Builder
Vamos criar e usar um novo Docker Buildx builder:
docker buildx create --name mybuilder --use
A saída deve ser semelhante a:
mybuilder
Agora, vamos verificar se nosso builder foi criado e está definido como o padrão:
docker buildx ls
Você deve ver uma saída semelhante a:
NAME/NODE DRIVER/ENDPOINT STATUS PLATFORMS
mybuilder * docker-container
mybuilder0 unix:///var/run/docker.sock inactive
default docker
default default running linux/amd64, linux/386
O asterisco (*) ao lado de mybuilder indica que ele é o builder atualmente ativo.
Inspecionando o Builder
Vamos examinar os detalhes do nosso builder:
docker buildx inspect mybuilder
Isso mostrará a configuração do builder, incluindo as plataformas suportadas e seu status atual.
Agora que configuramos com sucesso o Docker Buildx, estamos prontos para prosseguir com a criação de um Dockerfile para usar com nosso builder.
Criando um Dockerfile Simples para Teste
Antes de usar o Docker Buildx para construir imagens, precisamos criar um Dockerfile simples. Este servirá como nosso caso de teste para entender o erro "requires exactly 1 argument" (requer exatamente 1 argumento).
Entendendo Dockerfiles
Um Dockerfile é um documento de texto contendo instruções para construir uma imagem Docker. Ele automatiza o processo de criação de contêineres com configurações específicas.
Vamos criar um diretório para nosso projeto:
mkdir -p ~/project/buildx-test
cd ~/project/buildx-test
Criando um Dockerfile Básico
Agora, vamos criar um Dockerfile simples usando o editor de texto nano:
nano Dockerfile
Copie e cole o seguinte conteúdo no Dockerfile:
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y \
curl \
nginx \
&& rm -rf /var/lib/apt/lists/*
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
Pressione Ctrl+O seguido por Enter para salvar, depois Ctrl+X para sair do nano.
Vamos detalhar este Dockerfile:
FROM ubuntu:22.04- Usa o Ubuntu 22.04 como imagem baseRUN apt-get update...- Atualiza as listas de pacotes e instala curl e nginxEXPOSE 80- Indica que o contêiner ouvirá na porta 80CMD ["nginx", "-g", "daemon off;"]- Executa o nginx em primeiro plano quando o contêiner inicia
Criando um arquivo .dockerignore
Um arquivo .dockerignore ajuda a excluir arquivos e diretórios que não são necessários no contexto da construção, tornando as construções mais rápidas e eficientes:
nano .dockerignore
Adicione o seguinte conteúdo:
.git
.gitignore
*.md
Pressione Ctrl+O seguido por Enter para salvar, depois Ctrl+X para sair do nano.
Verificando a Estrutura do Projeto
Vamos verificar se nossos arquivos foram criados corretamente:
ls -la
Você deve ver uma saída semelhante a:
total 16
drwxrwxr-x 2 labex labex 4096 Jan 1 00:00 .
drwxr-xr-x 3 labex labex 4096 Jan 1 00:00 ..
-rw-rw-r-- 1 labex labex 21 Jan 1 00:00 .dockerignore
-rw-rw-r-- 1 labex labex 159 Jan 1 00:00 Dockerfile
Agora que temos um Dockerfile básico, estamos prontos para testar o Docker Buildx e explorar o erro "requires exactly 1 argument" na próxima etapa.
Entendendo e Resolvendo o Erro "Requires Exactly 1 Argument"
Nesta etapa, vamos deliberadamente acionar o erro "requires exactly 1 argument" (requer exatamente 1 argumento) para entender suas causas e, em seguida, aprender como resolvê-lo.
Acionando o Erro
Primeiro, vamos navegar para o diretório do nosso projeto, se ainda não estivermos lá:
cd ~/project/buildx-test
Agora, vamos tentar construir uma imagem usando o Docker Buildx sem especificar o contexto de construção:
docker buildx build
Você deve ver uma mensagem de erro semelhante a:
"docker buildx build" requires exactly 1 argument.
See 'docker buildx build --help'.
Usage: docker buildx build [OPTIONS] PATH | URL | -
Este erro ocorre porque o comando docker buildx build requer um contexto de construção (o diretório que contém o Dockerfile) como um argumento.
Entendendo o Erro
O erro "requires exactly 1 argument" significa que o Docker Buildx precisa saber onde encontrar os arquivos necessários para construir a imagem. Este argumento é tipicamente um caminho para o diretório que contém seu Dockerfile (o contexto de construção).
Cenários comuns que acionam este erro incluem:
- Esquecer de especificar o contexto de construção
- Usar a sintaxe de comando incorreta
- Colocar opções na ordem errada
Corrigindo o Erro
Vamos corrigir o comando adicionando o contexto de construção. A maneira mais simples é usar . para indicar o diretório atual:
docker buildx build .
Desta vez, o Docker iniciará o processo de construção, mas notaremos que ele não marca a imagem, tornando-a difícil de referenciar mais tarde.
Vamos parar a construção com Ctrl+C se ela ainda estiver em execução e tentar novamente com uma tag adequada:
docker buildx build -t nginx-test:latest .
Você deve ver a saída mostrando o progresso da construção:
[+] Building 12.8s (7/7) FINISHED
=> [internal] load build definition from Dockerfile 0.0s
=> => transferring dockerfile: 203B 0.0s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 34B 0.0s
=> [internal] load metadata for docker.io/library/ubuntu:22.04 0.5s
=> [1/3] FROM docker.io/library/ubuntu:22.04@sha256:... 0.0s
=> CACHED [2/3] RUN apt-get update && apt-get install -y curl nginx 0.0s
=> CACHED [3/3] EXPOSE 80 0.0s
=> exporting to image 0.0s
=> => exporting layers 0.0s
=> => writing image sha256:... 0.0s
=> => naming to docker.io/library/nginx-test:latest 0.0s
Usando Diferentes Opções do Buildx
Vamos explorar algumas opções adicionais com o Docker Buildx:
- Construindo e carregando a imagem no armazenamento local de imagens do Docker:
docker buildx build --load -t nginx-test:local .
- Construindo sem usar o cache de construção (forçando uma construção nova):
docker buildx build --no-cache -t nginx-test:nocache .
- Construindo e emitindo apenas o ID final da imagem:
docker buildx build -q -t nginx-test:quiet .
Verificando as Imagens Construídas
Vamos verificar as imagens que construímos:
docker images | grep nginx-test
Você deve ver uma saída semelhante a:
nginx-test quiet abcdef123456 5 minutes ago 123MB
nginx-test nocache fedcba654321 5 minutes ago 123MB
nginx-test local 123456abcdef 5 minutes ago 123MB
nginx-test latest abcdef123456 5 minutes ago 123MB
Agora você entende o erro comum "requires exactly 1 argument" com o Docker Buildx e sabe como construir imagens corretamente com várias opções.
Construindo Imagens Multi-Arquitetura com Docker Buildx
Uma das características mais poderosas do Docker Buildx é sua capacidade de construir imagens para múltiplas arquiteturas simultaneamente. Nesta etapa, aprenderemos como criar imagens multi-arquitetura.
Entendendo Imagens Multi-Arquitetura
Imagens multi-arquitetura permitem que o mesmo nome de imagem funcione em diferentes plataformas (como AMD64, ARM64, etc.). O Docker seleciona automaticamente a versão apropriada para a arquitetura do host quando a imagem é puxada.
Isso é especialmente útil para:
- Suportar dispositivos baseados em x86 e ARM
- Garantir que seus aplicativos sejam executados em vários provedores de nuvem
- Construir para dispositivos IoT com diferentes arquiteturas
Configurando para Construções Multi-Arquitetura
O Docker Buildx precisa ser configurado para construções multi-arquitetura. Primeiro, vamos garantir que nosso builder suporte este recurso:
docker buildx inspect --bootstrap mybuilder
Se você vir um erro sobre o builder não estar disponível, vamos recriá-lo com a configuração correta:
docker buildx rm mybuilder
docker buildx create --name mybuilder --driver docker-container --bootstrap --use
Criando uma Imagem Multi-Arquitetura
Agora, vamos construir nossa imagem Nginx para múltiplas arquiteturas:
docker buildx build --platform linux/amd64,linux/arm64 -t nginx-test:multi .
Você pode ver uma mensagem de erro semelhante a:
error: multiple platforms feature is currently not supported for docker driver. Please switch to a different driver (eg. "docker buildx create --use")
Isso acontece porque o driver Docker padrão não suporta construções multi-arquitetura. Vamos modificar nossa abordagem.
Para fins de demonstração, construiremos para plataformas específicas separadamente:
docker buildx build --platform linux/amd64 -t nginx-test:amd64 --load .
Isso constrói a imagem especificamente para a arquitetura AMD64 e a carrega no armazenamento local de imagens do Docker.
Usando Argumentos de Construção
O Docker Buildx nos permite usar argumentos de construção para personalizar nossas construções. Vamos modificar nosso Dockerfile para usar um argumento de construção:
nano Dockerfile
Atualize o conteúdo do Dockerfile para:
FROM ubuntu:22.04
ARG PACKAGE=nginx
RUN apt-get update && apt-get install -y \
curl \
${PACKAGE} \
&& rm -rf /var/lib/apt/lists/*
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
Pressione Ctrl+O seguido por Enter para salvar, depois Ctrl+X para sair do nano.
Agora podemos construir a imagem com um pacote personalizado:
docker buildx build --build-arg PACKAGE=nginx-extras -t nginx-extras:latest .
Enviando para um Registro (Opcional)
Para utilizar totalmente imagens multi-arquitetura, você normalmente as enviaria para um registro. Isso requer credenciais do Docker Hub ou um registro privado. Em um cenário real, o comando seria semelhante a:
## Exemplo apenas - não é necessário para este laboratório
## docker buildx build --platform linux/amd64,linux/arm64 -t username/nginx-test:multi --push .
Inspecionando Imagens
Vamos examinar as imagens que criamos:
docker images | grep nginx
Você deve ver uma saída semelhante a:
nginx-extras latest abcdef123456 1 minute ago 130MB
nginx-test amd64 123456abcdef 2 minutes ago 123MB
nginx-test latest fedcba654321 10 minutes ago 123MB
Testando Nossa Imagem
Finalmente, vamos executar um contêiner usando nossa imagem para verificar se ela funciona:
docker run -d --name test-nginx -p 8080:80 nginx-test:latest
Verifique se o contêiner está em execução:
docker ps
Você deve ver uma saída indicando que seu contêiner está em execução:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
abcdef123456 nginx-test:latest "nginx -g 'daemon of…" 10 seconds ago Up 10 seconds 0.0.0.0:8080->80/tcp test-nginx
Vamos usar o curl no servidor nginx para garantir que ele esteja respondendo:
curl http://localhost:8080
Você deve ver a página de boas-vindas padrão do Nginx em HTML.
Quando terminar, limpe o contêiner:
docker stop test-nginx
docker rm test-nginx
Parabéns! Você trabalhou com sucesso com o Docker Buildx, entendeu e resolveu o erro "requires exactly 1 argument" e aprendeu como criar construções especializadas para diferentes arquiteturas.
Resumo
Neste laboratório, você ganhou experiência prática com o Docker Buildx e aprendeu a solucionar o erro comum "requires exactly 1 argument" (requer exatamente 1 argumento). Aqui está o que você realizou:
- Configuração do Docker Buildx e criação de uma instância de builder
- Criação de um Dockerfile básico para testes
- Encontrou, entendeu e resolveu o erro "requires exactly 1 argument"
- Construiu imagens Docker com várias opções e configurações
- Aprendeu os conceitos básicos da construção de imagens multi-arquitetura
Essas habilidades fornecem uma base sólida para trabalhar com o Docker em ambientes de desenvolvimento modernos, onde os aplicativos geralmente precisam ser executados em diversas plataformas de hardware. Agora você pode usar com confiança o Docker Buildx para criar imagens de contêiner eficientes e específicas para a plataforma, evitando erros comuns.
Ao continuar sua jornada com o Docker, considere explorar recursos mais avançados do Buildx, integrá-lo a pipelines de CI/CD e usá-lo para construir aplicativos verdadeiramente portáteis que podem ser executados em qualquer lugar.
