PHP Academy · Aula

Docker Compose para ambientes locais

Execute PHP, um banco de dados e um cache juntos localmente.

Docker Compose para ambientes locais é uma aula grátis de PHP Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de PHP Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de PHP Academy inclui 4 aulas no total.

Ambientes locais com Compose

Aplicativos PHP reais nunca são apenas PHP — eles precisam de um banco de dados, um cache, às vezes uma fila e um capturador de e-mails. O Docker Compose declara todos esses componentes como serviços em um único arquivo e os conecta a uma rede compartilhada para que possam alcançar uns aos outros pelo nome.

Nesta lição, você criará um ambiente local completo: PHP-FPM + nginx + MySQL + Redis, com volumes, verificações de integridade e ordenação de dependências.

Estrutura básica dos serviços

Um arquivo do Compose lista os serviços em services:. Cada serviço pode ser compilado a partir de um Dockerfile com build ou baixar uma image. O Compose cria uma rede padrão na qual cada serviço pode ser acessado por sua chave — seu aplicativo PHP se conecta ao MySQL pelo host db, não por localhost.

services:
  app:
    build:
      context: .
      target: dev          # multi-stage dev target
    volumes:
      - ./:/app            # live code mount
    depends_on:
      db:
        condition: service_healthy
  db:
    image: mysql:8.4
  redis:
    image: redis:7-alpine

nginx na frente do FPM

O FPM se comunica por FastCGI na porta 9000, não por HTTP. O nginx encerra o HTTP e encaminha as solicitações .php para app:9000. A configuração do nginx faz referência ao serviço PHP pelo nome usado no Compose.

# docker/nginx/default.conf
server {
  listen 80;
  root /app/public;
  index index.php;

  location / {
    try_files $uri /index.php?$query_string;
  }

  location ~ \.php$ {
    fastcgi_pass app:9000;       # service name from compose
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
  }
}

Conectando o serviço web

O serviço nginx monta o mesmo código para resolver SCRIPT_FILENAME e também monta a configuração, publica a porta 80 e depende do aplicativo. Ambos compartilham /app para que os caminhos correspondam nos dois lados do FastCGI.

services:
  web:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
    volumes:
      - ./:/app:ro
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - app

Volumes persistentes

Os sistemas de arquivos dos contêineres são efêmeros. Volumes nomeados preservam os arquivos do banco de dados entre execuções de docker compose down. Montagens vinculadas (./:/app) sincronizam o código do computador em tempo real durante o desenvolvimento. Use volumes nomeados para dados com estado e montagens vinculadas para o código-fonte.

services:
  db:
    image: mysql:8.4
    environment:
      MYSQL_DATABASE: app
      MYSQL_USER: app
      MYSQL_PASSWORD: secret
      MYSQL_ROOT_PASSWORD: rootsecret
    volumes:
      - dbdata:/var/lib/mysql

volumes:
  dbdata:        # survives `down`, removed only by `down -v`

Verificações de integridade e depends_on

depends_on sozinho apenas espera o contêiner iniciar, não que o MySQL aceite conexões. Adicione uma healthcheck e use condition: service_healthy para que o aplicativo espere até que o banco de dados esteja realmente pronto.

services:
  db:
    image: mysql:8.4
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-prootsecret"]
      interval: 5s
      timeout: 3s
      retries: 10
  app:
    build: .
    depends_on:
      db:
        condition: service_healthy   # waits for healthcheck pass

Ambiente e .env

O Compose carrega automaticamente um .env vizinho para interpolação de variáveis, e você passa a configuração do aplicativo por meio de environment ou env_file. Mantenha os segredos fora do arquivo do Compose confirmado no repositório; faça referência às variáveis em vez disso.

services:
  app:
    build: .
    env_file:
      - .env
    environment:
      DATABASE_URL: "mysql://app:secret@db:3306/app"
      REDIS_URL: "redis://redis:6379"
# .env (gitignored) provides ${...} substitutions
#   MYSQL_PASSWORD=secret

Conectando a partir do PHP

Dentro da rede, os nomes de host são os nomes dos serviços. Seu código PHP conecta-se diretamente a db e redis. Este trecho analisa um DSN como faria uma camada de configuração, mostrando como o nome do serviço do Compose chega à sua cadeia de conexão.

<?php
$dsn = 'mysql://app:secret@db:3306/app';
$p = parse_url($dsn);

printf("driver: %s\n", $p['scheme']);
printf("host:   %s\n", $p['host']);   // 'db' resolves via compose DNS
printf("port:   %d\n", $p['port']);
printf("db:     %s\n", ltrim($p['path'], '/'));

$pdoDsn = sprintf('mysql:host=%s;port=%d;dbname=%s', $p['host'], $p['port'], ltrim($p['path'], '/'));
echo $pdoDsn . PHP_EOL;
?>

Xdebug para desenvolvimento local

Monte a configuração do Xdebug apenas localmente, por meio do destino de compilação dev. Aponte client_host para host.docker.internal para que o depurador alcance sua IDE no computador anfitrião. Nunca envie o Xdebug para a produção — ele destrói o desempenho.

; docker/php/xdebug.ini  (mounted only in dev)
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003

Executando comandos avulsos

docker compose run inicia um contêiner efêmero para migrações, testes ou Composer; exec executa dentro de um serviço que já está em execução. Use run --rm para essas tarefas, para que o contêiner descartável seja limpo.

# Run migrations against the running db
docker compose exec app php bin/console doctrine:migrations:migrate

# One-off: install deps without a long-lived container
docker compose run --rm app composer install

# Tail logs of just the web service
docker compose logs -f web

Arquivos de substituição

O Compose mescla docker-compose.yml com docker-compose.override.yml automaticamente. Mantenha padrões com estrutura de produção no arquivo base e coloque os volumes, as portas e o Xdebug exclusivos do desenvolvimento na substituição — assim, a integração contínua usa o arquivo base e os desenvolvedores recebem os recursos extras automaticamente.

# docker-compose.override.yml (auto-merged, dev only)
services:
  app:
    volumes:
      - ./docker/php/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini:ro
    environment:
      APP_ENV: dev
# CI runs: docker compose -f docker-compose.yml up  (no override)

Verificação rápida

Por que depends_on: [db] simples é insuficiente antes de executar as migrações?

Recapitulação

Você montou um ambiente local com o Compose: PHP-FPM atrás do nginx (FastCGI para app:9000), MySQL e Redis acessíveis pelo nome do serviço, volumes nomeados para persistência, verificações de integridade controlando depends_on, configuração orientada por env, Xdebug em uma substituição exclusiva do desenvolvimento e comandos avulsos por meio de run/exec.

Lembre-se: os nomes dos serviços são nomes de host DNS, os arquivos de substituição mantêm os recursos extras de desenvolvimento fora da integração contínua e as verificações de integridade são melhores que uma ordenação ingênua da inicialização.

Perguntas Frequentes

A aula “Docker Compose para ambientes locais” é grátis?

Sim — o texto completo de “Docker Compose para ambientes locais” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de PHP Academy, atualize para CoddyKit PRO. O curso de PHP Academy inclui 4 aulas no total.

O que vou aprender em “Docker Compose para ambientes locais”?

Execute PHP, um banco de dados e um cache juntos localmente. Você pratica PHP Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar PHP Academy?

Nenhuma experiência prévia é necessária. PHP Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Docker Compose para ambientes locais”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de PHP Academy?

Sim. Cada aula de PHP Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

Conteinerizando uma aplicação PHP
Compilações em múltiplas etapas e otimização
Docker Compose para ambientes locais
CI/CD com GitHub Actions

← Voltar para PHP Academy