No Boss Wiki - Guia Completo: Ambiente de Desenvolvimento PHP 8.3 com Docker e WSL no Windows

Detalhes: Escrito por Johnny Salazar Reidel; Categoria: WSL e Docker; Última Atualização: 26 Setembro 2025

Este guia foi elaborado para configurar um ambiente de desenvolvimento PHP robusto e isolado no Windows, utilizando o poder do Subsistema Windows para Linux (WSL) e a flexibilidade do Docker.

Vamos replicar uma configuração avançada usando arquivos docker-compose e dockerfiles customizados para criar um ambiente com PHP 8.3, Apache (com suporte a HTTPS/SSL), MariaDB (MySQL) e diversas ferramentas de desenvolvimento.

Índice

Pré-requisitos e Acesso aos Terminais
Preparando o Ambiente WSL
Instalando o Docker Engine no WSL
Estrutura e Arquivos do Projeto
Executando o Ambiente de Desenvolvimento
Integração SSH com GitHub
Opcional: Configuração de ODBC para SQL Server
Comandos Úteis e Dicas

1. Pré-requisitos e Acesso aos Terminais

Windows 10 ou 11 atualizado.
WSL2 instalado.
Ubuntu 22.04 LTS instalado da Microsoft Store.
Windows Terminal instalado da Microsoft Store.

Como Abrir os Terminais Corretamente

Para encontrar os terminais, pressione a tecla Windows e digite o nome (PowerShell ou Windows Terminal).

Terminal como Administrador (Elevado): Necessário para instalar o WSL e alguns componentes do Windows. Clique com o botão direito no ícone do terminal e selecione "Executar como administrador".
Terminal como Usuário Normal: Usado para todas as outras operações do dia a dia, como navegar no Linux (WSL), usar Git, Docker, etc. Apenas abra o terminal normalmente.

2. Preparando o Ambiente WSL

a. Instale o WSL (se ainda não o fez): Abra o PowerShell como Administrador e execute:

wsl --install

Isso instalará o WSL e a distribuição padrão (Ubuntu). Reinicie o computador quando solicitado.

b. Atualize sua distribuição Linux: Abra o Windows Terminal. Ele deve iniciar diretamente no seu ambiente Ubuntu (WSL). Execute os seguintes comandos:

# Atualiza a lista de pacotes e os pacotes já instalados
sudo apt update && sudo apt upgrade -y

# Instala ferramentas essenciais
sudo apt install -y git curl ca-certificates gnupg openssl net-tools

3. Instalando o Docker Engine no WSL

Ainda no seu terminal do Ubuntu (como usuário normal), siga os passos:

a. Configurar o repositório oficial do Docker:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL [https://download.docker.com/linux/ubuntu/gpg](https://download.docker.com/linux/ubuntu/gpg) | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] [https://download.docker.com/linux/ubuntu](https://download.docker.com/linux/ubuntu) \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

b. Instalar o Docker Engine e o Docker Compose:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

c. Adicionar seu usuário ao grupo do Docker (Passo importante!):

sudo usermod -aG docker $USER

Atenção: Após executar o comando acima, você precisa fechar e reabrir o terminal do WSL para que a alteração de grupo tenha efeito.

4. Estrutura e Arquivos do Projeto

Agora vamos criar todos os arquivos de configuração necessários.

Passo 1: Criar a Estrutura de Pastas

No seu terminal WSL, crie as pastas que armazenarão a configuração do Docker e os seus projetos.

# Navegue para sua pasta de usuário
cd ~

# Pasta para a configuração do Docker
mkdir docker

# Pasta para os dados persistentes do MariaDB
mkdir mysql

# Pasta onde ficarão os seus sites e aplicações
mkdir public_html

# Entre na pasta de configuração do Docker
cd docker

Passo 2: Arquivo de Variáveis de Ambiente (`.env`)

Dentro da pasta ~/docker, crie um arquivo chamado .env.

# ~/docker/.env
UID=1000
GID=1000
USER=www-data

Passo 3: Arquivo de Orquestração (`docker-compose.yml`)

Ainda em ~/docker, crie o arquivo docker-compose.yml.

# ~/docker/docker-compose.yml
version: '3.8'

services:
  # Serviço para Apache e PHP 8.3
  php8.3:
    image: meu-ambiente/apache-php8.3:1.0
    container_name: php8.3
    build:
      context: .
      dockerfile: dockerfiles
      args:
        - TAG_VERSION_PHP=8.3-apache
        - UID=${UID}
        - GID=${GID}
        - USER=${USER}
    restart: always
    networks:
      - app-network
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - mariadb
    volumes:
      - type: bind
        source: /home/${USER}/public_html
        target: /var/www/html
      - ./ssl/000-default.conf:/etc/apache2/sites-available/000-default.conf
      - ./ssl/server.crt:/etc/apache2/ssl/server.crt
      - ./ssl/server.key:/etc/apache2/ssl/server.key
      # Mapeamentos Opcionais para ODBC
      - ./freetds.conf:/etc/freetds/freetds.conf
      - ./odbc.ini:/etc/odbc.ini
      - ./odbcinst.ini:/etc/odbcinst.ini

  # Serviço para banco de dados MariaDB
  mariadb:
    image: mariadb:10.8
    container_name: mariadb
    ports:
      - "3306:3306"
    restart: always
    networks:
      - app-network
    environment:
      MARIADB_ROOT_PASSWORD: "us35#w3(b)%"
    volumes:
      - type: bind
        source: /home/${USER}/mysql
        target: /var/lib/mysql
    command: --sql-mode="ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION"

networks:
  app-network:
    driver: bridge
    driver_opts:
      com.docker.network.driver.mtu: 1400

Acessando o Banco de Dados

Com o serviço mariadb definido, é importante saber como se conectar a ele.

Conexão pela Aplicação (Código Fonte PHP):
- Host: mariadb (Este é o nome do serviço na rede interna do Docker)
- Usuário: root
- Senha: us35#w3(b)% (A senha que definimos no docker-compose.yml)
Conexão por Software Externo (Navicat, DBeaver, etc.):
- Host: localhost (Porque a porta 3306 do contêiner está mapeada para a sua máquina)
- Porta: 3306
- Usuário: root
- Senha: us35#w3(b)%

Passo 4: Arquivo de Build da Imagem (`dockerfiles`)

Este arquivo contém todas as instruções para construir uma imagem Docker personalizada. Crie-o em ~/docker.

# ~/docker/dockerfiles
ARG TAG_VERSION_PHP
FROM php:$TAG_VERSION_PHP
LABEL maintainer="PHP Custom Build"

ARG UID
ARG GID

# Instala dependências do sistema e extensões comuns do PHP
RUN apt-get update && apt-get install -y --no-install-recommends \
    ghostscript libbz2-dev libgmp-dev libicu-dev libfreetype6-dev libjpeg-dev \
    libldap2-dev libmemcached-dev libmagickwand-dev libpq-dev libpng-dev \
    libwebp-dev libzip-dev nano git zip unzip wget telnet net-tools rsync openssh-client \
    ruby ruby-dev sendmail libsasl2-dev \
    # Dependências para ODBC
    unixodbc unixodbc-dev freetds-dev freetds-bin tdsodbc \
    && rm -rf /var/lib/apt/lists/*

# Configura e instala extensões do PHP
RUN docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp \
    && debMultiarch="$(dpkg-architecture --query DEB_BUILD_MULTIARCH)" \
    && docker-php-ext-configure ldap --with-libdir="lib/$debMultiarch" \
    && docker-php-ext-install -j "$(nproc)" bz2 bcmath exif gd gmp intl ldap mysqli pdo_mysql zip soap opcache

# Instala imagick, apcu, memcached, redis via PECL
RUN pecl install imagick memcached redis apcu \
    && docker-php-ext-enable imagick memcached redis apcu

# Configurações recomendadas de PHP.INI para desenvolvimento
COPY --from=php:8.3-apache /usr/local/etc/php/php.ini-development /usr/local/etc/php/php.ini
RUN { \
        echo 'memory_limit = 256M'; \
        echo 'max_execution_time = 120'; \
        echo 'post_max_size = 200M'; \
        echo 'upload_max_filesize = 200M'; \
        echo 'display_errors = On'; \
        echo 'error_reporting = E_ALL'; \
    } > /usr/local/etc/php/conf.d/custom.ini

# Habilita módulos do Apache e configura ServerName
RUN a2enmod rewrite expires remoteip ssl
RUN echo "ServerName localhost" >> /etc/apache2/apache2.conf

# Instala Ruby SASS e Compass
RUN gem install sass compass

# Instala Composer
RUN php -r "copy('[https://getcomposer.org/installer](https://getcomposer.org/installer)', 'composer-setup.php');" \
    && php composer-setup.php --install-dir=/usr/local/bin --filename=composer \
    && php -r "unlink('composer-setup.php');"

# Instala Node.js 18.x e Yarn
RUN curl -sL [https://deb.nodesource.com/setup_18.x](https://deb.nodesource.com/setup_18.x) | bash - \
    && apt-get install -y nodejs \
    && npm install -g yarn

# Altera UID e GID do usuário www-data para corresponder ao usuário do host
RUN usermod -u ${UID} www-data && groupmod -g ${GID} www-data

USER www-data
VOLUME /var/www/html
EXPOSE 80 443
CMD ["apache2-foreground"]

Passo 5: Configuração do Apache e SSL

Para que o https:// funcione corretamente e seja confiável no seu navegador, é preciso gerar e instalar um certificado SSL local. Este é um processo mais detalhado.

➡️ Para um passo a passo completo, consulte nosso guia: Criação de Certificado SSL Local Confiável para Docker

Depois de seguir o guia acima e gerar seus arquivos de certificado, crie o arquivo 000-default.conf dentro de ~/docker/ssl/ com o seguinte conteúdo para configurar o Apache:

# ~/docker/ssl/000-default.conf
<VirtualHost *:80>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

<VirtualHost *:443>
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/html
    
    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined

    SSLEngine on
    SSLCertificateFile /etc/apache2/ssl/server.crt
    SSLCertificateKeyFile /etc/apache2/ssl/server.key
</VirtualHost>

Passo 6: Arquivo de Teste (`index.php`)

Crie um arquivo de teste na pasta public_html.

# No terminal, a partir de qualquer pasta
nano ~/public_html/index.php

Cole o seguinte conteúdo, salve (Ctrl+O) e saia (Ctrl+X).

<?php
echo "<h1>Ambiente PHP 8.3 com Docker e WSL</h1>";
echo "<h3>Versão do PHP: " . phpversion() . "</h3>";
phpinfo();
?>

5. Executando o Ambiente de Desenvolvimento

Com todos os arquivos criados, no terminal, navegue até a pasta ~/docker.

a. Inicie o serviço do Docker (se necessário):

sudo service docker start

b. Construa a imagem e suba os contêineres:

# Estando na pasta ~/docker
docker compose up --build -d php8.3

A primeira execução será demorada.

c. Acesse sua aplicação:

HTTP: Abra seu navegador e acesse http://localhost
HTTPS: Acesse https://localhost (se você seguiu o guia de SSL, o cadeado deve aparecer como seguro).

6. Integração SSH com GitHub

No terminal do WSL, execute:

# Gere uma nova chave SSH
ssh-keygen -t ed25519 -C "Este endereço de email está sendo protegido de spambots. Você precisa do JavaScript ativado para vê-lo."

# Exiba e copie a chave pública
cat ~/.ssh/id_ed25519.pub

Vá para o GitHub, em Settings > SSH and GPG keys > New SSH key, e cole a chave.

7. Opcional: Configuração de ODBC para SQL Server

A imagem Docker que construímos já inclui os drivers necessários. Para ativá-la, crie os seguintes arquivos de configuração dentro da sua pasta ~/docker.

a. Arquivo ~/docker/freetds.conf:

[global]
    tds version = 7.2
    port = 1433
    text size = 64512

[ASAV_TOTVS_HOM]
	host = bdhom10.asav.org.br
	port = 1433
	tds version = 4.2

b. Arquivo ~/docker/odbc.ini:

[ASAV_HOM_CORPORERM_WEB]
Driver = FREETDS
Description = Totvs - homologacao
Servername = ASAV_TOTVS_HOM
Database = corporerm_web

c. Arquivo ~/docker/odbcinst.ini:

[FreeTDS]
Description = v0.91 with protocol v7.3
Driver = /usr/lib/x86_64-linux-gnu/odbc/libtdsodbc.so

8. Comandos Úteis e Dicas

Parar e remover os contêineres:

# Estando na pasta ~/docker
docker compose down

Ver logs em tempo real:
```
docker compose logs -f php8.3
```
Acessar o terminal do contêiner:
```
docker compose exec php8.3 bash
```
Problemas com VPN (MTU): O docker-compose.yml já inclui um ajuste de MTU. Se ainda tiver problemas de rede no WSL, execute: sudo ifconfig eth0 mtu 1400.

Guia Completo: Ambiente de Desenvolvimento PHP 8.3 com Docker e WSL no Windows