Introdução aos contêineres remotos do Docker no WSL 2

Artigo
01/04/2024

Este guia passo a passo ajudará você a começar a desenvolver com contêineres remotos configurando o Docker Desktop para Windows com o WSL 2 (Subsistema do Windows para Linux, versão 2).

O Docker Desktop para Windows fornece um ambiente de desenvolvimento para criar, enviar e executar aplicativos colocados em docker. Ao habilitar o mecanismo baseado no WSL 2, você pode executar contêineres do Linux e do Windows no Docker Desktop no mesmo computador. (O Docker Desktop é gratuito para uso pessoal e para pequenas empresas. Para obter informações sobre preços do Pro, Team ou Business, consulte as Perguntas frequentes do site do Docker).

Observação

Recomendamos usar o Docker Desktop devido à integração com o Windows e o Subsistema do Windows para Linux. No entanto, enquanto o Docker Desktop dá suporte à execução de contêineres do Linux e do Windows, você não pode executar ambos simultaneamente. Para executar contêineres do Linux e do Windows simultaneamente, você precisaria instalar e executar uma instância separada do Docker no WSL. Se você precisar executar contêineres simultâneos ou apenas preferir instalar um mecanismo de contêiner diretamente na distribuição do Linux, siga as instruções de instalação do Linux para esse serviço de contêiner, como Instalar o Docker Engine no Ubuntu ou Instalar o Podman para executar contêineres do Linux.

Visão geral dos contêineres do Docker

O Docker é uma ferramenta usada para criar, implantar e executar aplicativos usando contêineres. Os contêineres permitem que os desenvolvedores empacotem um aplicativo com todas as partes necessárias (bibliotecas, estruturas, dependências etc.) e enviem tudo isso como um pacote. O uso de um contêiner garante que o aplicativo seja executado da mesma forma, independentemente de configurações personalizadas ou das bibliotecas instaladas anteriormente no computador que o executa, que poderiam ser diferentes do computador usado para escrever e testar o código do aplicativo. Isso permite que os desenvolvedores se concentrem em escrever código sem se preocupar com o sistema no qual o código será executado.

Os contêineres do Docker são semelhantes às máquinas virtuais, mas não criam um sistema operacional virtual inteiro. Em vez disso, o Docker permite que o aplicativo use o mesmo kernel do Linux que o sistema em que ele está sendo executado. Isso permite que o pacote do aplicativo exija apenas as partes que ainda não estão no computador host, reduzindo o tamanho do pacote e melhorando o desempenho.

A disponibilidade contínua, usando contêineres do Docker com ferramentas como Kubernetes, é outro motivo para a popularidade dos contêineres. Isso permite que várias versões de seu contêiner de aplicativo sejam criadas em momentos diferentes. Em vez de precisar desativar um sistema inteiro para atualizações ou manutenção, cada contêiner (e seus microsserviços específicos) pode ser substituído de forma dinâmica. Você pode preparar um novo contêiner com todas as atualizações, configurar o contêiner para produção e apenas apontar para o novo contêiner quando ele estiver pronto. Também é possível arquivar versões diferentes do aplicativo usando contêineres e mantê-los em execução como um fallback de segurança, se necessário.

Para saber mais, confira a Introdução aos contêineres do Docker.

Pré-requisitos

WSL versão 1.1.3.0 ou superior.
Windows 11 de 64 bits: Home ou Pro versão 21H2 ou superior, ou Enterprise ou Education versão 21H2 ou superior.
Windows 10 de 64 bits (recomendado): Home ou Pro 22H2 (build 19045) ou superior, ou Enterprise ou Education 22H2 (build 19045) ou superior. (Mínimo): Home ou Pro 21H2 (build 19044) ou superior, ou Enterprise ou Education 21H2 (build 19044) ou superior. Atualizar o Windows
Processador de 64 bits com SLAT (Conversão de Endereços de Segundo Nível).
RAM do sistema de 4 GB.
Habilite a virtualização de hardware na BIOS.
Instale o WSL e configure um nome de usuário e senha para sua distribuição do Linux em execução no WSL 2.
Instalar o Visual Studio Code(opcional). Isso fornecerá a melhor experiência, incluindo a capacidade de codificar e depurar dentro de um contêiner remoto do Docker e conectado à distribuição do Linux.
Instalar o Terminal do Windows (opcional). Isso fornecerá a melhor experiência, incluindo a capacidade de personalizar e abrir vários terminais na mesma interface (incluindo Ubuntu, Debian, PowerShell, CLI do Azure ou o que preferir usar).
Inscreva-se para criar uma ID do Docker no Docker Hub(opcional).
Consulte o contrato de licença do Docker Desktop para obter atualizações sobre os termos de uso.

Para obter mais informações, consulte os documentos do Docker – Requisitos do sistema para instalar o Docker Desktop no Windows.

Para saber como instalar o Docker no Windows Server, consulte Introdução: preparar o Windows para contêineres.

Observação

O WSL pode executar distribuições no modo WSL versão 1 ou WSL 2. Para verificar isso, abra o PowerShell e digite: wsl -l -v. Verifique se a distribuição está definida para usar o WSL 2 inserindo: wsl --set-version <distro> 2. Substitua <distro> pelo nome da distribuição (por exemplo, Ubuntu 18.04).

No WSL versão 1, devido a diferenças fundamentais entre o Windows e o Linux, o Docker Engine não pôde ser executado diretamente dentro do WSL, portanto, a equipe do Docker desenvolveu uma solução alternativa usando as VMs Hyper-V e LinuxKit. No entanto, como o WSL 2 agora é executado em um kernel do Linux com capacidade completa de chamada do sistema, o Docker pode ser executado totalmente no WSL 2. Isso significa que os contêineres do Linux podem ser executados nativamente sem emulação, resultando em melhor desempenho e interoperabilidade entre suas ferramentas do Windows e Linux.

Instalar o Docker Desktop

Com o back-end do WSL 2 com suporte no Docker Desktop para Windows, você pode trabalhar em um ambiente de desenvolvimento baseado no Linux e criar contêineres baseados no Linux, usando o Visual Studio Code para edição e depuração de código e executando seu contêiner no navegador Microsoft Edge no Windows.

Para instalar o Docker (depois de instalar o WSL):

Baixe o Docker Desktop e siga as instruções de instalação.
Depois de instalado, inicie o Docker Desktop no menu Iniciar do Windows e selecione o ícone do Docker no menu ícones ocultos da barra de tarefas. Clique com o botão direito do mouse no ícone para exibir o menu de comandos do Docker e selecione “Configurações”.
Verifique se “Usar o mecanismo baseado em WSL 2” está marcado em Configurações>Gerais.
Selecione entre as distribuições do WSL 2 instaladas nas quais você deseja habilitar a integração do Docker acessando: Configurações>Recursos>Integração do WSL.
Para confirmar se o Docker foi instalado, abra uma distribuição do WSL (por exemplo, Ubuntu) e exiba a versão e o número do build inserindo: docker --version
Teste se a instalação funciona corretamente executando uma imagem interna simples do Docker usando: docker run hello-world

Dica

A seguir estão alguns comandos úteis do Docker:

Liste os comandos disponíveis na CLI do Docker digitando: docker
Liste as informações para um comando específico com: docker <COMMAND> --help
Liste as imagens do Docker em seu computador (que é apenas a imagem hello-world neste momento), com: docker image ls --all
Liste os contêineres em seu computador com: docker container ls --all ou docker ps -a (sem o sinalizador -a show all, somente contêineres em execução serão exibidos)
Liste as informações de todo o sistema referentes à instalação do Docker, incluindo estatísticas e recursos (CPU e memória) disponíveis para você no contexto do WSL 2, com: docker info

Desenvolver em contêineres remotos usando o VS Code

Para começar a desenvolver aplicativos usando o Docker com o WSL 2, recomendamos usar o VS Code, juntamente com as extensões do WSL, de Contêineres de Desenvolvimento e do Docker.

Instalar a extensão do WSL no VS Code. Essa extensão permite abrir seu projeto do Linux em execução no WSL no VS Code (não é necessário se preocupar com problemas de caminhos, compatibilidade binária ou outros desafios entre sistemas operacionais).
Instalar a extensão de Contêineres de Desenvolvimento do VS Code. Essa extensão permite abrir sua pasta de projeto ou repositório dentro de um contêiner, aproveitando o conjunto completo de recursos do Visual Studio Code para fazer seu trabalho de desenvolvimento dentro do contêiner.
Instalar a extensão do Docker do VS Code. Essa extensão adiciona a funcionalidade para criar, gerenciar e implantar aplicativos em contêineres de dentro do VS Code. (Você precisa da extensão de Contêineres de Desenvolvimento para realmente usar o contêiner como seu ambiente de desenvolvimento.)

Vamos usar o Docker para criar um contêiner de desenvolvimento para um projeto de aplicativo existente.

Para este exemplo, usarei o código-fonte do meu tutorial Olá, Mundo para Django nos documentos de configuração de ambiente de desenvolvimento Python. Você pode ignorar esta etapa se preferir usar o código-fonte do seu projeto. Para baixar meu aplicativo Web HelloWorld-Django do GitHub, abra um terminal do WSL (Ubuntu, por exemplo) e insira: git clone https://github.com/mattwojo/helloworld-django.git

Observação

Sempre armazene seu código no mesmo sistema de arquivos no qual você está usando as ferramentas. Isso resultará em um desempenho de acesso a arquivos mais rápido. Neste exemplo, estamos usando uma distribuição do Linux (Ubuntu) e queremos armazenar nossos arquivos de projeto no \\wsl\ do sistema de arquivos do WSL. Armazenar arquivos de projeto no sistema de arquivos do Windows reduziria a velocidade significativamente ao usar ferramentas do Linux no WSL para acessar esses arquivos.
No terminal do WSL, altere os diretórios para a pasta de código-fonte deste projeto:
```
cd helloworld-django
```
Abra o projeto no VS Code em execução no servidor de extensão do WSL local inserindo:
```
code .
```
Confirme se você está conectado à distribuição do Linux no WSL verificando o indicador remoto verde no canto inferior esquerdo da instância do VS Code.
Na paleta de comandos do VS Code (Ctrl + Shift + P), insira: Contêineres de desenvolvimento: reabrir no contêiner, pois estamos usando uma pasta já aberta usando a extensão WSL. Como alternativa, use Contêineres de desenvolvimento: abrir pasta no contêiner... para escolher uma pasta WSL usando o compartilhamento local \\wsl$ (do lado do Windows). Consulte o Código do Visual Studio Início Rápido: abrir uma pasta existente em um contêiner para obter mais detalhes. Se esses comandos não forem exibidos quando você começar a digitar, verifique se instalou a extensão Contêineres de Desenvolvimento vinculada acima.
Selecione a pasta do projeto que você deseja colocar em contêiner. No meu caso, isso é \\wsl\Ubuntu-20.04\home\mattwojo\repos\helloworld-django\
Uma lista de definições de contêiner será exibida, pois ainda não há nenhuma configuração de contêiner de desenvolvimento na pasta do projeto (repositório). A lista de definições de configuração de contêiner exibidas é filtrada com base no tipo de projeto. Para o meu projeto do Django, selecionarei Python 3.
Uma nova instância do VS Code será aberta, começará a criar nossa nova imagem e, depois que o build for concluído, iniciará nosso contêiner. Você verá que uma nova pasta de .devcontainer apareceu com informações de configuração de contêiner dentro de um arquivo Dockerfile e devcontainer.json.
Para confirmar se o projeto ainda está conectado ao WSL e em um contêiner, abra o terminal integrado do VS Code (Ctrl + Shift + ~). Verifique o sistema operacional inserindo: uname e a versão do Python com: python3 --version. Você pode ver que o uname voltou como “Linux”, portanto, você ainda está conectado ao mecanismo do WSL 2 e o número da versão do Python será baseado na configuração do contêiner que pode ser diferente da versão do Python instalada na distribuição do WSL.
Para executar e depurar seu aplicativo dentro do contêiner usando o Visual Studio Code, primeiro abra o menu Executar (Ctrl+Shift+D ou selecione a guia na barra de menus à esquerda). Em seguida, selecione Executar e depurar para selecionar uma configuração de depuração e escolha a configuração mais adequada ao seu projeto (no meu exemplo, esta será "Django"). Isso criará um arquivo launch.json na pasta .vscode do projeto com instruções sobre como executar seu aplicativo.
De dentro do VS Code, selecione Executar>Iniciar depuração (ou basta pressionar a tecla F5). Isso abrirá um terminal dentro do VS Code e você verá um resultado dizendo algo como: "Iniciando o servidor de desenvolvimento em http://127.0.0.1:8000/ Feche o servidor com CONTROL-C". Mantenha pressionada a tecla Control e selecione o endereço exibido para abrir seu aplicativo no navegador da Web padrão e veja seu projeto em execução dentro de seu contêiner.

Agora você configurou com êxito um contêiner de desenvolvimento remoto usando o Docker Desktop, alimentado pelo back-end do WSL 2, que você pode codificar, compilar, executar, implantar ou depurar usando o VS Code!

Solução de problemas

Contexto do Docker do WSL preterido

Se você estava usando uma Pré-Visualização Técnica antecipada do Docker para WSL, talvez tenha um contexto do Docker chamado “wsl” que agora está preterido e não é mais usado. Você pode verificar com o comando: docker context ls. Você pode remover esse contexto “wsl” para evitar erros com o comando: docker context rm wsl como você deseja usar o contexto padrão para Windows e WSL2.

Os possíveis erros que você pode encontrar com esse contexto wsl preterido incluem: docker wsl open //./pipe/docker_wsl: The system cannot find the file specified. ou error during connect: Get http://%2F%2F.%2Fpipe%2Fdocker_wsl/v1.40/images/json?all=1: open //./pipe/docker_wsl: The system cannot find the file specified.

Para obter mais informações sobre esse problema, consulte Como configurar o Subsistema do Windows para Linux (WSL2) no Windows 10.

Problemas ao localizar a pasta de armazenamento de imagens do Docker

O Docker cria duas pastas de distribuição para armazenar dados:

\wsl$\docker-desktop
\wsl$\docker-desktop-data

Você pode encontrar essas pastas abrindo sua distribuição do Linux no WSL e inserindo: explorer.exe . para exibir a pasta no Explorador de Arquivos do Windows. Insira: \\wsl\<distro name>\mnt\wsl substituindo <distro name> pelo nome da distribuição (ou seja, Ubuntu-20.04) para ver essas pastas.

Saiba mais sobre como localizar locais de armazenamento do Docker no WSL, consulte o problema no repositório do WSL ou nesta postagem do StackOverflow.

Para obter mais ajuda com problemas gerais de solução de problemas no WSL, consulte o documento Solução de problemas.