WordPress com Docker: Docker Compose, Composer e Xdebug

Se é um programador profissional de WordPress em 2026, o Docker é o seu melhor aliado. Já lá vão os dias de instalar manualmente versões de PHP no Mac ou lutar contra bugs específicos de servidores Windows. O Docker tornou-se a linguagem comum dos ambientes de desenvolvimento, e conhecê-lo bem faz parte do ofício de qualquer profissional que trabalhe hoje no ecossistema WordPress.

Neste guia percorremos o Docker aplicado ao desenvolvimento WordPress: desde os conceitos básicos e a imagem oficial wordpress até ao Compose, ao wp-env, à depuração, ao CI/CD e à migração a partir do MAMP ou do LocalWP. Os detalhes técnicos vêm da documentação oficial da Docker, da página da imagem wordpress no Docker Hub, da documentação da MariaDB e do manual de programadores do WordPress, com ligação em cada secção.

#Porquê usar Docker no desenvolvimento WordPress

A desculpa do “funciona na minha máquina” deixa de valer quando o ambiente vive em ficheiros versionados. A contentorização garante consistência entre ambientes, e essa mudança alterou a forma como as equipas de WordPress colaboram e entregam software.

#Paridade entre o ambiente local e a produção

O seu contentor local pode usar a mesma distribuição Linux, a mesma versão de PHP e a mesma configuração de MySQL que o servidor de produção. Isso reduz a categoria de erros mais frustrante: os que só aparecem em produção. Quando desenvolve dentro de um contentor com a mesma imagem que o servidor usa, o código que funciona no seu portátil comporta-se da mesma forma no servidor de staging e em produção.

A paridade de ambientes vai além das versões de software. Inclui configurações de rede, variáveis de ambiente e permissões de ficheiros. Com Docker, cada membro da equipa trabalha num ambiente idêntico, quer use macOS, Windows ou Linux como sistema anfitrião.

#Várias versões de PHP em projetos isolados

O Projeto A precisa de PHP 8.4 e o Projeto B de PHP 7.4? Sem problema. Cada projeto vive na sua própria “bolha” e nunca entra em conflito com os outros. Este nível de isolamento era muito difícil com ferramentas tradicionais como o MAMP ou o XAMPP, onde mudar a versão de PHP afetava todos os projetos ao mesmo tempo.

O isolamento do Docker também protege o sistema anfitrião. As extensões de PHP, as bibliotecas do sistema e as dependências do projeto ficam separadas. Se um projeto exige uma extensão PHP experimental ou uma configuração de servidor pouco habitual, pode aplicá-la sem risco para os restantes projetos.

#Ambiente reproduzível com ficheiros versionados no Git

Cada ambiente Docker é definido por ficheiros de configuração versionados no Git. Um novo membro da equipa clona o repositório, executa um comando e tem o ambiente a funcionar, sem um guia de instalação passo a passo que fica desatualizado. A documentação do ambiente vive no próprio código do projeto.

#WordPress com Docker Compose

O Docker Compose é a ferramenta que coordena vários contentores. Uma configuração típica de WordPress em 2026 inclui vários serviços que trabalham em conjunto para formar um ambiente de desenvolvimento completo.

#Que serviços inclui o WordPress no Docker Compose

1. WordPress (PHP-FPM ou Apache): o motor que executa o código PHP do WordPress.
2. Nginx: o servidor web à frente do PHP-FPM, se escolher a variante fpm.
3. MariaDB/MySQL: a base de dados onde fica guardado todo o conteúdo.
4. Redis: a cache de objetos, recomendável se o projeto a usar em produção.
5. Mailpit: para capturar os emails enviados durante os testes.

# Excerto de compose.yaml com a variante FPM
services:
  db:
    image: mariadb:11.4
    volumes:
      - db_data:/var/lib/mysql
  wordpress:
    image: wordpress:php8.4-fpm
    depends_on:
      - db
volumes:
  db_data:

A variante fpm não inclui servidor web, por isso precisa de um contentor Nginx que lhe passe os pedidos PHP. Se não quiser configurar o Nginx, a variante com Apache (wordpress:php8.4-apache) serve o WordPress diretamente na porta 80 do contentor.

#Bind mounts ou volumes nomeados para WordPress

Os volumes no Docker Compose são essenciais no desenvolvimento WordPress. Precisa de montar a pasta de temas e plugins para editar o código em tempo real, enquanto os dados da base de dados devem persistir em volumes nomeados para nada se perder entre reinícios do contentor.

A estratégia certa equilibra desempenho e funcionalidade. Para ficheiros que edita com frequência (temas, plugins próprios), use bind mounts. Para dados que só precisam de persistir (base de dados, uploads), use volumes nomeados do Docker. A documentação da imagem oficial indica os caminhos: os temas ficam em /var/www/html/wp-content/themes/ e os plugins em /var/www/html/wp-content/plugins/.

#Credenciais em ficheiros .env com Docker Compose

A gestão de segredos conta mesmo em ambiente local. Guarde as credenciais da base de dados e as chaves de API em ficheiros .env e confirme que estão no .gitignore. O Docker Compose lê o ficheiro .env da pasta do projeto e substitui variáveis como ${DB_PASSWORD} dentro do compose.yaml, o que separa a configuração sensível do código versionado.

#Variáveis de ambiente da imagem oficial do WordPress

A imagem wordpress do Docker Hub gera o seu próprio wp-config.php a partir de variáveis de ambiente. Segundo a página oficial da imagem, estas são as variáveis que reconhece:

O pormenor que mais tempo faz perder: o contentor do WordPress não cria a base de dados indicada em WORDPRESS_DB_NAME. Quem a cria é o contentor da base de dados, com MARIADB_DATABASE na MariaDB ou MYSQL_DATABASE no MySQL. Se os dois nomes não coincidirem, o WordPress mostra um erro de ligação mesmo com as credenciais corretas.

O WORDPRESS_CONFIG_EXTRA serve para constantes que a imagem não expõe, por exemplo WP_ALLOW_MULTISITE ou WP_ENVIRONMENT_TYPE. Tudo o que lá colocar é executado com eval(), por isso convém mantê-lo curto e versionado com o resto da configuração.

#Como esperar que a MariaDB esteja pronta antes do WordPress

Um depends_on simples não chega. A documentação do Compose sobre a ordem de arranque explica que o Compose espera que o contentor da dependência esteja em execução, e não que esteja pronto para aceitar ligações. A MariaDB demora alguns segundos a inicializar na primeira vez, e o WordPress pode arrancar antes e falhar a ligação.

A solução é um healthcheck na base de dados e condition: service_healthy no WordPress. A imagem oficial da MariaDB inclui o script healthcheck.sh para isso, e a documentação da MariaDB publica um exemplo com WordPress. Adaptado a um ambiente de desenvolvimento fica assim:

services:
  db:
    image: mariadb:11.4
    environment:
      MARIADB_DATABASE: wordpress
      MARIADB_USER: wordpress
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_RANDOM_ROOT_PASSWORD: '1'
    volumes:
      - db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 3
  wordpress:
    image: wordpress:php8.4-apache
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
      WORDPRESS_DEBUG: '1'
    volumes:
      - wp_data:/var/www/html
      - ./meu-tema:/var/www/html/wp-content/themes/meu-tema
    depends_on:
      db:
        condition: service_healthy
volumes:
  db_data:
  wp_data:

Com este ficheiro, docker compose up -d arranca a base de dados, espera que o healthcheck passe e só então inicia o WordPress em http://localhost:8080. O tema próprio é montado como bind mount, e o resto do WordPress fica no volume wp_data.

#Imagens apache, fpm, alpine e cli do WordPress

A imagem oficial é publicada em várias variantes. As etiquetas combinam versão do WordPress, versão do PHP e tipo, por exemplo php8.4-apache, php8.4-fpm, php8.4-fpm-alpine ou cli.

• apache: WordPress e Apache num único contentor. É a opção mais direta para desenvolvimento local.
• fpm: só PHP-FPM, pensado para ficar atrás do Nginx ou de outro proxy.
• fpm-alpine: o mesmo sobre Alpine Linux, com uma imagem mais pequena.
• cli: WP-CLI sem servidor web, para executar comandos wp sobre uma instalação existente.

A variante cli tem uma armadilha documentada no Docker Hub: baseia-se em Alpine e o seu utilizador www-data tem o UID 82, enquanto as variantes baseadas em Debian usam o UID 33. Ao executar wordpress:cli sobre uma instalação Debian costuma ser preciso --user 33:33, e por vezes -e HOME=/tmp, para que o WP-CLI consiga escrever nos ficheiros.

#Como acrescentar extensões PHP à imagem oficial

A imagem não inclui extensões PHP adicionais, mesmo que plugins populares as peçam. O Docker Hub dá como exemplo o facto de a imagem não conseguir enviar email por si só. Para acrescentar extensões, constrói-se uma imagem própria com FROM wordpress:... seguindo as instruções da imagem php. Para ajustar diretivas como upload_max_filesize, basta copiar um custom.ini para $PHP_INI_DIR/conf.d/:

FROM wordpress:php8.4-apache
COPY custom.ini $PHP_INI_DIR/conf.d/

Se quiser incluir temas ou plugins dentro da imagem para várias instalações, a documentação indica copiá-los para /usr/src/wordpress/, que é copiado para /var/www/html/ no primeiro arranque do contentor.

#wp-env, o ambiente Docker oficial do WordPress

Se desenvolve plugins ou temas e não precisa de reproduzir um servidor concreto, o wp-env evita escrever o compose.yaml à mão. É um pacote Node mantido no repositório do Gutenberg que usa Docker por baixo. Instala-se com npm -g i @wordpress/env e arranca-se com wp-env start a partir da pasta do plugin.

O ambiente fica disponível em http://localhost:8888 com o utilizador admin e a palavra-passe password. A configuração vai num ficheiro .wp-env.json na raiz do projeto:

{
  "$schema": "https://schemas.wp.org/trunk/wp-env.json",
  "core": null,
  "phpVersion": "8.3",
  "plugins": [ "." ],
  "config": {
    "WP_DEBUG_LOG": true
  }
}

core a null usa a versão estável mais recente do WordPress, phpVersion fixa a versão de PHP e plugins lista os plugins a instalar e ativar. Existem ainda themes, mappings para montar pastas, port (8888 por omissão), testsPort (8889) e mariadbVersion.

O Composer, o PHPUnit e o WP-CLI vêm incluídos no contentor cli: wp-env run cli wp plugin list ou wp-env run cli --env-cwd=wp-content/plugins/meu-plugin composer install. O Xdebug está instalado mas desligado, e ativa-se com wp-env start --xdebug. A documentação descreve também um modo experimental, wp-env start --runtime=playground, que executa o WordPress em WebAssembly sem Docker, com SQLite e sem o comando run.

A diferença prática face ao Compose: o wp-env decide a arquitetura por si. Para um plugin é mais rápido. Para reproduzir um servidor de produção com Nginx, Redis e uma versão exata da MariaDB, o Compose continua a ser a ferramenta adequada.

#VS Code Dev Containers para WordPress

Muitos programadores já não instalam PHP no portátil. Usam os VS Code Dev Containers, que mudam a forma de trabalhar com o editor.

#Como funciona um Dev Container no VS Code

Abre a pasta do projeto, e o VS Code deteta a pasta .devcontainer, arranca o Docker e liga o IDE diretamente dentro do contentor. As extensões do VS Code, as ferramentas de linha de comandos e a configuração do editor correm dentro do contentor.

#Extensões e linters pré-configurados no contentor

Um espaço de trabalho configurado para cada projeto, logo ao abrir a pasta. Não importa se o programador entrou na equipa há cinco minutos ou há cinco anos: o ambiente é idêntico para todos. As extensões de PHP, os linters, os formatadores de código e as ferramentas de depuração ficam definidos no repositório.

#Dev Containers para equipas distribuídas

Para agências WordPress com equipas distribuídas, os Dev Containers eliminam uma fonte comum de atrito: as diferenças entre ambientes locais. Cada pessoa trabalha no mesmo ambiente, seja qual for o local ou o equipamento, sem sessões de “vamos configurar o seu portátil”.

#Desempenho do Docker no Mac e no Windows

O Docker era lento em sistemas que não fossem Linux, porque os ficheiros do projeto atravessam uma máquina virtual. O Docker Desktop oferece hoje várias opções para reduzir esse custo.

#Como ativar o VirtioFS no Docker Desktop

No macOS, escolha o VirtioFS como implementação de partilha de ficheiros nas definições do Docker Desktop. A documentação das definições do Docker Desktop indica que o VirtioFS reduziu o tempo das operações de sistema de ficheiros até 98%. Substitui as opções anteriores, osxfs e gRPC FUSE.

#Synchronized file shares para repositórios grandes

Para projetos muito grandes, o Docker Desktop oferece o Synchronized file shares: mantém uma cache sincronizada dos ficheiros do anfitrião num sistema ext4 dentro da máquina virtual. A Docker recomenda-o para repositórios com 100 000 ficheiros ou mais, e está disponível nas subscrições Pro, Team e Business. Uma instalação WordPress com um node_modules grande no tema pode aproximar-se desse número.

#Quanta RAM usa o Docker Desktop

A máquina virtual do Docker Desktop reserva memória enquanto está ligada. O modo Resource Saver desliga-a quando não há contentores em execução durante 5 minutos (valor ajustável), e a Docker indica uma poupança de 2 GB ou mais de memória e CPU no anfitrião.

#Docker vs LocalWP, MAMP e DDEV

#Docker Compose face ao DDEV e ao Lando

O DDEV e o Lando simplificam a experiência Docker para programadores WordPress. Trazem configurações predefinidas e comandos simplificados que reduzem a curva de aprendizagem. Para projetos em que precisa de controlo total sobre cada peça da infraestrutura, o Compose com o seu próprio ficheiro continua a ser a opção mais flexível.

#Quando escolher DDEV e quando escolher Docker Compose

A escolha depende da sua experiência e do projeto. Se está a começar com a contentorização, o DDEV tem uma curva de aprendizagem mais suave. Se gere vários projetos com requisitos de infraestrutura diferentes, o Docker Compose com configurações próprias dá-lhe mais margem.

#Segurança em ambientes Docker para WordPress

O Docker oferece isolamento por omissão, mas é a configuração que decide quanta proteção obtém.

#Contentores sem root e imagens atualizadas

Evite executar processos como root dentro dos contentores quando não for necessário. Mantenha as imagens base atualizadas para receber correções de segurança; a própria documentação da imagem wordpress lembra que se deve reconstruir e voltar a implementar com regularidade. Analise as imagens à procura de vulnerabilidades conhecidas com ferramentas como o Docker Scout ou o Trivy.

#Redes Docker separadas por projeto

O Compose cria uma rede própria para cada projeto. Mantenha essa separação e não ligue sem motivo contentores de projetos diferentes à mesma rede, para que uma intrusão num não chegue aos outros.

#Docker Secrets e ficheiros .env para palavras-passe

Nunca coloque credenciais diretamente no Dockerfile ou no compose.yaml. A imagem wordpress aceita o sufixo _FILE nas suas variáveis: WORDPRESS_DB_PASSWORD_FILE=/run/secrets/db_password lê a palavra-passe a partir de um ficheiro em vez de uma variável. O Compose monta cada segredo em /run/secrets/<nome> dentro do contentor, segundo o seu guia de segredos, que acrescenta um limite: os segredos só funcionam em contentores Linux.

#Como configurar CI/CD para WordPress com Docker

A maior vantagem do Docker é que o seu pipeline de CI/CD (GitHub Actions, GitLab CI) pode usar as mesmas imagens que usa localmente. Essa consistência elimina uma categoria inteira de erros de implementação.

#Passos de um pipeline CI/CD com Docker

1. Executar testes PHPUnit no contentor para verificar a lógica do backend.
2. Executar testes end-to-end com Cypress ou Playwright contra o contentor.
3. Implementar a imagem estável no cluster de produção (Kubernetes/Swarm).

#Registo privado de imagens Docker para WordPress

As equipas que constroem imagens WordPress próprias guardam-nas num registo privado de contentores. Essas imagens incluem as extensões PHP necessárias, as ferramentas de desenvolvimento e a configuração do projeto, de modo que um novo membro descarrega a imagem em vez de a construir.

O Docker Hub descreve também um modo de implementação estático: construir uma imagem com o WordPress, o tema e os plugins dentro de /usr/src/wordpress, executá-la em modo --read-only com tmpfs para /tmp e /run, e atualizar implementando uma imagem nova em vez de usar as atualizações automáticas.

#WordPress em Kubernetes ou Docker Swarm

Para sites WordPress com muito tráfego, a orquestração com Kubernetes ou Docker Swarm permite escalar conforme a procura. Quando o tráfego sobe durante campanhas ou promoções, arrancam novos contentores para absorver a carga.

#Como depurar WordPress em Docker

A depuração de WordPress dentro de contentores exige algumas técnicas diferentes do desenvolvimento local tradicional.

#Xdebug dentro de contentores

Configurar o Xdebug num contentor exige atenção à rede: o contentor tem de alcançar o IDE que está à escuta no anfitrião. Muitas configurações de Dev Containers já trazem o Xdebug, o wp-env ativa-o com --xdebug, e numa imagem própria terá de instalar a extensão e configurar o host de ligação e a porta.

#Como ver os logs com docker compose logs

O Docker dá acesso centralizado aos logs de todos os serviços. Use docker compose logs para ver a saída combinada do WordPress, Nginx, MariaDB e Redis, ou docker compose logs -f wordpress para seguir um único serviço. Com o WORDPRESS_DEBUG ativo, os avisos de PHP aparecem nessa mesma saída. Em produção, ferramentas como o Grafana e o Prometheus oferecem painéis de monitorização.

#Query Monitor e Blackfire em Docker

Ferramentas como o Query Monitor e o Blackfire funcionam em ambientes Docker com WordPress. Fazer profiling dentro do contentor dá uma imagem do desempenho em condições próximas das de produção.

#Migrar do MAMP ou do LocalWP para Docker

Se usa MAMP, XAMPP ou LocalWP, a migração para Docker é mais simples do que parece. O processo típico inclui exportar as bases de dados, criar ficheiros Compose que reproduzam a configuração atual e adotar as restantes práticas aos poucos.

#Como migrar um projeto piloto para Docker Compose

Comece por um único projeto piloto. Crie um ficheiro compose.yaml que reproduza o ambiente atual, incluindo a versão de PHP, o motor de base de dados e as extensões necessárias. Quando o piloto funcionar, migre os restantes projetos.

#Como importar a base de dados e o wp-content

Exporte as bases de dados com mysqldump e importe-as no contentor MariaDB. Copie os ficheiros do WordPress (sobretudo o wp-content) para a estrutura de volumes do Docker. Se o endereço mudar, por exemplo para http://localhost:8080, execute wp search-replace com o WP-CLI e confirme que os media e as ligações funcionam no novo ambiente.

#Conclusão

O Docker já não é só para DevOps; é uma competência fundamental para programadores WordPress em 2026. Com a contentorização elimina erros de ambiente, acelera a integração de novos membros na equipa e constrói aplicações mais seguras. O tempo investido a aprender Docker recupera-se em produtividade e qualidade do código.

Veja também como acelerar um site em WordPress e o papel que a contentorização tem no desempenho geral do site.

Ainda luta com configurações de servidores locais? Está na hora de contentorizar o seu ambiente com Docker.