0. Configurar o WSL 2 e o Docker Desktop

Instale o WSL 2 e o Ubuntu e, em seguida, conecte o Ubuntu ao Docker Desktop no Windows.

O Ayakaleaf Pro usa contêineres Linux. No Windows, instale o Docker Desktop com o backend WSL 2 e execute os scripts do Toolkit no Ubuntu.

O WSL 2 fornece o kernel Linux. O Docker Desktop gerencia o engine do Docker em seu próprio ambiente docker-desktop; ativar a WSL Integration permite que a CLI do Docker no Ubuntu se comunique com esse engine. Em seguida, o Toolkit inicia a aplicação, o MongoDB e o Redis como contêineres. Com as compilações em sandbox ativadas, a aplicação usa o socket do Docker do engine para iniciar um contêiner separado do TeX Live para cada compilação. Você não precisa de instalações do MongoDB, do Redis ou do TeX Live no Windows.

1. Instalar o WSL 2 e o Ubuntu

   Abra o PowerShell como administrador no Windows e execute:

   wsl --install -d Ubuntu
   

   Reinicie o Windows se for solicitado. Abra o Ubuntu pelo menu Iniciar e crie um nome de usuário e uma senha do Linux. Essa é a conta para sudo dentro do Ubuntu; ela é separada do seu login do Windows.

   De volta ao PowerShell, atualize o WSL e verifique a distribuição:

   wsl --update
   wsl --version
   wsl --list --verbose
   

   A linha do Ubuntu deve mostrar VERSION 2. Se mostrar 1, use o nome exato da distribuição que aparece na lista:

   wsl --set-version Ubuntu 2
   

   O Docker exige o WSL 2.1.5 ou posterior; a versão do software WSL exibida por wsl --version e a coluna VERSION 2 da distribuição são verificações diferentes. Consulte a solução de problemas da instalação e as instruções de instalação da Microsoft se a instalação falhar, e ative a virtualização de hardware na BIOS/UEFI se o WSL informar que ela não está disponível.

2. Instalar e iniciar o Docker Desktop

   Baixe o Docker Desktop for Windows para o seu processador e execute o instalador. Use o backend WSL 2 se ele for oferecido. Abra o Docker Desktop pelo menu Iniciar do Windows e aguarde até que o engine inicie.

   Em Settings → General do Docker Desktop, ative Use WSL 2 based engine se a opção for exibida. Em Settings → Resources → WSL Integration, ative a integração para o Ubuntu e selecione Apply ou Apply & restart. Se o Ubuntu não for a sua distribuição padrão, ative explicitamente a chave dele.

   Se a WSL Integration não aparecer, verifique se o Docker Desktop está usando Linux containers. Consulte o guia do backend WSL 2 do Docker.

   Use a integração do Docker Desktop para este guia. Instalar um segundo Docker Engine com apt install docker.io ou iniciar o dockerd dentro do Ubuntu cria uma configuração separada e pode causar conflitos. Se você já usa um Engine no Ubuntu, siga as orientações de migração do Docker antes de trocar; mantenha os dados de aplicações e os backups existentes.

3. Verificar o Docker a partir do Ubuntu

   Abra um terminal do Ubuntu. Execute estes comandos nele, sem sudo:

   docker version
   docker compose version
   docker ps
   

   docker version deve mostrar tanto Client quanto Server. Uma lista de contêineres vazia é normal em uma nova instalação. docker --version sozinho não prova que o engine está em execução.

   Se docker não estiver disponível ou não conseguir se conectar, reabra o Ubuntu depois de aplicar a WSL Integration e verifique se o Docker Desktop está em execução. Consulte Solução de problemas.

4. Verificar os recursos e o socket do Docker

   Verifique os recursos visíveis para o Docker:

   docker info --format 'CPUs={{.NCPU}} Memory={{.MemTotal}} Kernel={{.KernelVersion}}'
   df -h "$HOME"
   ls -l /var/run/docker.sock
   

   Para uma pequena instância local, 4 CPUs e 8 GB de memória disponíveis para o Docker são uma sugestão inicial, não um mínimo medido. Reserve memória suficiente também para o Windows. Com o backend WSL 2, os limites de recursos são gerenciados pelas configurações do WSL, e não pelos controles deslizantes de recursos do Docker Desktop do Mac. Alterações que exigem wsl --shutdown interrompem todas as distribuições WSL e cargas de trabalho do Docker em execução; aplique-as antes de iniciar a instância.

   Mantenha DOCKER_SOCKET_PATH=/var/run/docker.sock na configuração do Toolkit. A aplicação precisa desse socket do engine para as compilações em sandbox. Não altere as permissões dele para 777 para corrigir erros de conexão; em vez disso, restaure a integração do Docker Desktop.

​

Próximo passo

Quando docker ps funcionar no Ubuntu, continue com 1. Baixar o Toolkit.