Laravel com Docker oferece um ambiente prático e consistente para desenvolvimento, garantindo fácil configuração, segurança e performance otimizadas em produção, facilitando o controle e a escalabilidade da aplicação.
Se você está começando a usar Laravel Docker no Ubuntu 22.04, já sabe que montar esse ambiente pode gerar algumas dúvidas, né?
Que tal entender passo a passo como configurar seu projeto Laravel com Docker Compose, deixando tudo redondinho para desenvolvimento sem sofrimento? Bora lá.
Introdução à conteinerização de aplicações com Docker
Conteinerização é uma forma inteligente de transformar aplicações e suas dependências em pequenos pacotes chamados “containers”.
Esses containers funcionam como mini-aplicativos isolados, que podem rodar iguais em qualquer lugar.
Docker é a ferramenta mais popular para criar e gerenciar esses containers. Ela facilita a vida do desenvolvedor, garantindo que a aplicação funcione da mesma forma no computador de todo mundo, sem surpresas.
Imagine embalar tudo o que seu app precisa, da linguagem de programação ao sistema operacional, em uma caixa única que você pode enviar para qualquer servidor ou computador.
Ao usar Docker, você evita o problema clássico de “funcionava no meu computador”.
Além disso, a conteinerização ajuda a organizar o ambiente de desenvolvimento, tornar o processo mais rápido e seguro, e facilita a manutenção.
Quase tudo pode virar um container, desde uma aplicação web até um banco de dados. Isso deixa seu projeto mais leve e mais fácil de escalar.
Quer aprender mais? Logo você verá como aplicar esses conceitos na prática, usando o Docker para criar um ambiente Laravel completo. Assim, seu desenvolvimento fica mais prático e eficiente.
Vantagens de usar Docker Compose para ambientes Laravel
Usar Docker Compose para ambientes Laravel traz muitas vantagens. Ele facilita a gestão de vários containers ao mesmo tempo.
Em vez de iniciar um container por vez, você define tudo num único arquivo, o docker-compose.yml. Assim, cria, inicia ou para todo o ambiente com apenas um comando.
Isso ajuda muito a manter o ambiente sempre igual para todos no time. Não importa se você está no Windows, Linux ou Mac. O Laravel rodará igual em todos os sistemas, evitando erros de compatibilidade.
Outra vantagem é a organização. Docker Compose deixa claro quais serviços sua aplicação precisa, como banco de dados, servidor web e cache. Cada serviço roda isoladamente, evitando conflitos no sistema.
Além disso, Docker Compose permite escalar serviços fácil. Se precisar de mais instâncias do banco ou do servidor, é só ajustar o arquivo e reconstruir o ambiente. Isso ajuda no desempenho e na estabilidade do projeto.
Por fim, usar Docker Compose facilita atualizar dependências. Como tudo está em containers, você testa versões novas sem alterar seu computador. Isso torna o desenvolvimento mais seguro e produtivo.
Preparativos: requisitos e ambiente Ubuntu 22.04
Antes de montar seu ambiente Laravel com Docker, é importante preparar o sistema corretamente. No Ubuntu 22.04, certifique-se de que seu sistema esteja atualizado. Use o comando sudo apt update && sudo apt upgrade para garantir que todos os pacotes estejam nas versões mais recentes.
Depois, instale o Docker e o Docker Compose. O Docker é responsável por rodar os containers, enquanto o Docker Compose ajuda a organizar vários containers juntos, definindo-os em um único arquivo.
Para instalar o Docker, você pode usar comandos simples no terminal ou seguir o site oficial para obter a versão mais atualizada. Depois, configure seu usuário para usar o Docker sem precisar de privilégios de administrador, adicionando-o ao grupo docker.
Você também precisa garantir que o Laravel tenha as permissões corretas de arquivos, isso evita erros durante o desenvolvimento. Além disso, lembre-se de instalar PHP, Composer (para gerenciar dependências do Laravel) e uma extensão para conectar ao banco de dados, caso necessário.
Finalmente, organize uma estrutura de pastas no sistema para seu projeto Laravel e seus arquivos Docker, assim tudo fica no lugar certo, facilitando sua vida no dia a dia.
Obtendo código da aplicação Laravel demo
Para começar com Laravel usando Docker, você precisa do código da aplicação demo. A forma mais comum é clonar o projeto do GitHub. GitHub é uma plataforma online onde desenvolvedores compartilham códigos.
Abra seu terminal e use o comando git clone seguido do link do repositório da aplicação demo. Isso vai baixar todos os arquivos para seu computador.
Depois de clonar, navegue até a pasta do projeto usando o comando cd nome-do-projeto. Assim, você estará dentro do diretório da aplicação.
Se preferir, pode baixar o código como um arquivo ZIP pelo navegador e descompactar na sua máquina. Depois, abra a pasta pelo terminal.
Lembre-se de ter o Git instalado no sistema, caso vá usar o terminal. Ele é a ferramenta que ajuda a gerenciar versões e facilita atualizações no código.
Configurando o arquivo .env do Laravel para Docker
No Laravel, o arquivo .env é onde ficam as configurações do ambiente, como banco de dados e serviços usados pela aplicação. Para usar o Laravel com Docker, é preciso ajustar esse arquivo. Você deve configurar o host do banco de dados para o nome do serviço definido no docker-compose.yml, por exemplo, DB_HOST=db, onde “db” é o nome do serviço MySQL no Docker.
Além disso, verifique a porta do banco e outros parâmetros, como usuário e senha, que precisam estar corretos para que o Laravel consiga se conectar ao banco dentro do container.
Colocar essas informações corretamente evita erros comuns, como falha na conexão ao banco. Também é importante definir as variáveis para cache, sessão e fila, se sua aplicação usar esses recursos.
Lembre-se de nunca expor informações sensíveis em repositórios públicos. Para isso, mantenha seu .env fora do controle de versão e use exemplos seguros no arquivo .env.example.
Depois de ajustar o .env, você garante que o Laravel funcione perfeitamente dentro do ambiente Docker, fazendo a comunicação correta entre containers.
Construindo uma imagem customizada com Dockerfile PHP 7.4-FPM
Para rodar Laravel com Docker, você pode criar uma imagem personalizada usando o Dockerfile. Ele é um arquivo com instruções para montar a imagem do seu ambiente. No caso, usamos o PHP 7.4-FPM, que é uma versão do PHP recomendada para essa aplicação.
No Dockerfile, você começa escolhendo uma imagem base oficial do PHP 7.4 com o FPM, que é o FastCGI Process Manager. Essa versão é otimizada para rodar aplicações web de forma eficiente.
Depois, você adiciona comandos para instalar extensões do PHP necessárias para o Laravel funcionar, como as extensões para banco de dados, cache e outras ferramentas essenciais.
Também é comum copiar os arquivos da aplicação para dentro da imagem e configurar permissões para que o servidor web consiga acessar e rodar o Laravel sem problemas.
Por fim, a imagem personalizada agiliza o processo de criação e melhora a performance, pois já vem pronta com tudo que a aplicação precisa para rodar no Docker.
Configurando serviço Nginx no ambiente Docker
O Nginx é um servidor web leve e rápido, muito usado para rodar aplicações Laravel dentro do Docker. Para configurar o Nginx, você precisa criar um arquivo de configuração que indique onde estão os arquivos do Laravel e como o servidor deve funcionar.
No Docker, o serviço Nginx roda em um container separado, que se comunica com o container do PHP-FPM onde o Laravel está instalado. Essa separação mantém o ambiente organizado e eficiente.
O arquivo de configuração do Nginx define o diretório raíz onde a aplicação está, as regras para lidar com URLs amigáveis e como tratar erros. É nele que você informa o caminho para o arquivo index.php, que inicia o Laravel.
Também é importante mapear as portas para que o Nginx possa receber requisições externas e encaminhar corretamente para a aplicação. Normalmente, a porta 80 do container é exposta para acesso no navegador.
Por fim, a configuração deve garantir que os logs sejam registrados e que o servidor trate corretamente arquivos estáticos, como imagens e CSS, garantindo bom desempenho.
Preparando a base de dados MySQL com dump inicial
Para preparar a base de dados MySQL no Docker, você pode usar um dump inicial. O dump é uma cópia dos dados e da estrutura do banco em um arquivo. Esse arquivo ajuda a criar e popular o banco automaticamente.
Coloque o arquivo do dump dentro da pasta do seu projeto, geralmente na pasta docker/mysql para facilitar a organização. Depois, configure o serviço do banco no docker-compose.yml para importar esse dump na primeira inicialização.
Ao iniciar o container do MySQL, ele executa automaticamente o arquivo de dump, criando tabelas e inserindo dados iniciais. Isso economiza tempo e evita que você tenha que fazer isso manualmente.
É importante revisar se o dump está atualizado e compatível com sua versão do MySQL. Usar versão errada pode causar problemas na importação.
Depois do banco pronto, você pode conectar sua aplicação Laravel passando os dados do banco no arquivo .env. Assim, a aplicação já encontra tudo configurado para funcionar.
Definindo serviços no docker-compose.yml: app, db, nginx
No arquivo docker-compose.yml, você define todos os serviços que sua aplicação Laravel vai usar dentro do Docker. Os serviços principais geralmente são o app (onde o Laravel roda), o db (banco de dados MySQL) e o nginx (servidor web).
No serviço app, configuramos a imagem PHP-FPM personalizada, definimos volumes para sincronizar código fonte e expomos portas se necessário. Ele é responsável por executar o código PHP do Laravel.
O serviço db utiliza uma imagem oficial do MySQL, onde podemos mapear volumes para persistir dados e definir variáveis de ambiente para usuário, senha e nome do banco. Esse serviço armazena todos os dados da aplicação.
O serviço nginx roda o servidor web, que recebe as requisições e as encaminha para o app PHP. Aqui, mapeamos a porta 80 para acesso externo e vinculamos os arquivos de configuração do Nginx no container.
Definir esses serviços no docker-compose.yml ajuda a orquestrar o ambiente completo, permitindo iniciar tudo com um só comando e garantindo que todos os containers funcionem juntos corretamente.
Sincronizando volumes entre host e containers
Volumes são usados no Docker para compartilhar arquivos entre o sistema do seu computador (host) e os containers. Eles permitem que você edite o código no seu computador e veja as mudanças no container em tempo real.
No arquivo docker-compose.yml, você define volumes para a aplicação Laravel sincronizar os arquivos. Assim, o código fonte fica disponível tanto no host quanto no container.
Isso facilita o desenvolvimento porque você pode usar seu editor de texto favorito e não precisa copiar arquivos toda hora para o container.
Além do código, é possível sincronizar arquivos de configuração e pastas temporárias para garantir que o ambiente Docker funcione corretamente com o Laravel.
Sincronizar volumes também ajuda a preservar dados entre reinícios dos containers, evitando perda de informações importantes.
Executando e validando containers com docker compose
Para executar os containers, use o comando docker compose up -d. A opção -d faz com que os containers rodem em segundo plano, liberando o terminal para outras tarefas.
Depois de iniciar, é importante validar se tudo está funcionando. Você pode usar docker compose ps para ver os containers ativos e seus status.
Também vale verificar os logs dos containers com docker compose logs nome-do-serviço. Isso ajuda a descobrir erros e confirmar se a aplicação rodou direito.
Outra forma é acessar o endereço no navegador, geralmente http://localhost, para testar se o Laravel está servindo as páginas.
Se precisar parar os containers, use docker compose down. Para reiniciar, basta rodar o up novamente. Esses comandos tornam fácil o controle do ambiente Docker.
Usando comandos docker compose exec para Artisan e Composer
No ambiente Docker, você pode usar comandos com docker compose exec para rodar ferramentas dentro do container da aplicação Laravel. Por exemplo, Artisan e Composer.
O Artisan é a ferramenta de linha de comando do Laravel, usada para criar tarefas, gerenciar banco e muito mais. Já o Composer gerencia as dependências do projeto, como bibliotecas e pacotes.
Para rodar comandos Artisan, use: docker compose exec app php artisan comando. Troque “comando” pela ação que deseja, como migrate para rodar migrações no banco.
Para Composer, o comando é parecido: docker compose exec app composer update, que atualiza as dependências do projeto dentro do container.
Essa prática evita instalar o Composer ou outras dependências diretamente no sistema host, deixando o ambiente mais limpo e controlado.
Gerenciando permissões de arquivos e diretórios do Laravel
Gerenciar as permissões de arquivos e pastas do Laravel é essencial para evitar erros durante o desenvolvimento. O Laravel precisa acessar e gravar em algumas pastas específicas, como storage e bootstrap/cache.
Dentro do Docker, você deve garantir que essas pastas tenham permissões adequadas para o usuário do container PHP, geralmente o usuário www-data.
Use comandos como chown para alterar o dono das pastas, por exemplo: chown -R www-data:www-data storage bootstrap/cache. Isso dá permissão para o servidor web escrever nesses diretórios.
Também é importante ajustar as permissões para que a aplicação funcione de forma segura. Permissões muito abertas (como 777) podem causar problemas de segurança.
Configurar corretamente as permissões evita erros comuns, como falha ao gravar arquivos temporários ou logs, e garante que o Laravel funcione sem problemas dentro do ambiente Docker.
Resolução de problemas comuns em Laravel com Docker
Ao usar Laravel com Docker, é comum encontrar alguns problemas que podem travar seu desenvolvimento. Um erro frequente é a falha de conexão com o banco de dados. Geralmente, isso ocorre por causa do nome do host errado no arquivo .env. No Docker, use o nome do serviço definido no docker-compose.yml.
Outro problema comum são as permissões dos arquivos e pastas, que podem impedir a gravação de arquivos temporários e cache. Sempre verifique se as pastas storage e bootstrap/cache têm as permissões corretas.
Se a aplicação não carregar, cheque os logs dos containers usando docker compose logs nome-do-serviço. Os logs ajudam a identificar erros de configuração ou falhas de serviço.
Problemas de cache também são comuns. Limpar cache do Laravel com o comando php artisan cache:clear dentro do container pode resolver muitos erros estranhos.
Lembre-se de sempre reiniciar os containers após mudanças significativas, usando docker compose down e docker compose up -d. Isso ajuda a aplicar as alterações corretamente no ambiente.
Configurando permissões para evitar erros comuns
Configurar permissões corretamente evita muitos erros comuns no Laravel com Docker. Um problema frequente é a falta de permissão para gravar arquivos nas pastas storage e bootstrap/cache.
Para garantir que o Laravel funcione bem, você deve ajustar o dono dessas pastas para o usuário do servidor web, geralmente www-data. Use o comando chown -R www-data:www-data storage bootstrap/cache dentro do container.
Também ajuste as permissões para que as pastas possam ser escritas, mas sem liberar demais, evitando riscos de segurança. chmod 775 é uma permissão comum para esses diretórios.
Evitar permissões 777 é importante para manter a segurança do sistema, mesmo que pareça mais simples no começo.
Se surgir erro relacionado a gravação, revise essas permissões antes de outras soluções. Isso resolve a maioria dos problemas com arquivos no Laravel dentro do Docker.
Diferenciando ambiente local e produção com docker-compose.override.yml
O arquivo docker-compose.override.yml permite criar configurações específicas para o ambiente local, diferenciando-o do ambiente de produção. Isso facilita o desenvolvimento e a manutenção.
No ambiente local, você pode habilitar recursos de debug, montar volumes para sincronizar código e usar variáveis flexíveis no Laravel. Já na produção, essas opções são desativadas por segurança e performance.
O docker-compose.override.yml é automaticamente carregado junto com o docker-compose.yml, permitindo que você sobrescreva ou adicione configurações.
Por exemplo, no local você pode mapear portas diferentes, usar servidores de cache e ferramentas de monitoramento que não são recomendadas na produção.
Essa separação torna seu ambiente mais seguro, evitando que dados sensíveis ou configurações de debug sejam usados fora do desenvolvimento.
Como criar envios específicos para produção com docker-compose.prod.yml
O arquivo docker-compose.prod.yml é usado para configurar o ambiente de produção. Ele tem ajustes que deixam seu app seguro e otimizado para rodar de verdade.
Nesse arquivo, você pode desabilitar ferramentas de debug e montar volumes apenas para leitura. Isso protege seu código contra alterações não autorizadas.
Também é comum ajustar variáveis específicas, como conexões ao banco de dados reais e configurações de cache para melhorar desempenho.
Além disso, você pode configurar o escalonamento do número de containers, para garantir que o sistema aguente muitos acessos.
Para usar esse arquivo, basta rodar docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d. Assim, o Docker aplica as configurações de produção junto com as bases do seu ambiente.
Boas práticas para segurança e performance em produção
Garantir segurança e boa performance em produção é essencial para aplicações Laravel com Docker. Sempre mantenha seu sistema e containers atualizados para evitar vulnerabilidades conhecidas.
Use imagens oficiais e confiáveis como base para suas imagens Docker. Evite instalar pacotes desnecessários que aumentem o tamanho e a superfície de ataque.
Configure o servidor Nginx para usar HTTPS e redirecionar todo o tráfego para conexões seguras. Isso protege dados sensíveis transmitidos entre usuário e servidor.
Limite permissões de arquivos para o mínimo necessário, protegendo seu código e dados contra acessos indevidos.
Use ferramentas de cache e otimização do Laravel para melhorar a performance, como config:cache e route:cache. Elas agilizam o carregamento das páginas.
Monitore seus containers e logs para agir rapidamente em caso de erros ou ataques. Manter backups regulares dos dados é fundamental para recuperação em desastres.
Testando e monitorando logs das aplicações e containers
Testar e monitorar os logs é fundamental para manter sua aplicação Laravel funcionando bem dentro do Docker. Os logs ajudam a identificar problemas e a entender o comportamento da aplicação.
Use o comando docker compose logs nome-do-serviço para ver os registros em tempo real dos containers. Isso facilita encontrar erros e mensagens importantes.
Também é possível usar ferramentas externas, como ELK Stack ou Grafana, para monitorar logs de forma mais visual e organizada.
Durante os testes, verifique se o Laravel está gerando logs locais corretamente, na pasta storage/logs. Isso ajuda a analisar falhas específicas do app.
Monitorar o consumo de recursos dos containers também é importante para garantir que o ambiente esteja estável e com bom desempenho.
Táticas para reconstrução e atualização do ambiente
Quando precisar atualizar seu ambiente Docker com Laravel, o melhor é reconstruir os containers para aplicar as mudanças. Use o comando docker compose build para recriar as imagens com as novas configurações.
Depois, reinicie os containers com docker compose up -d, que vai rodar tudo em segundo plano. Isso garante que as atualizações entrem em vigor corretamente.
Se encontrar problemas, pode ser útil parar os containers com docker compose down antes de reconstruir. Assim, evita conflitos e erros na hora de subir o ambiente.
Também vale limpar volumes temporários e cache para prevenir erros causados por arquivos antigos. Para isso, apague pastas temporárias dentro do container ou no host, conforme necessidade.
Manter um fluxo organizado de reconstrução evita perda de dados e facilita o desenvolvimento contínuo e seguro da aplicação.
FAQ e resoluções rápidas para dúvidas frequentes
Aqui estão respostas rápidas para dúvidas comuns ao usar Laravel com Docker. Se o Laravel não conecta ao banco, verifique se o DB_HOST no .env corresponde ao nome do serviço do banco no docker-compose.yml.
Se o container não sobe ou dá erro, veja os logs com docker compose logs nome-do-serviço para identificar falhas.
Para problemas de permissão, confira se as pastas storage e bootstrap/cache têm dono e permissões corretas, geralmente para o usuário www-data.
Quer limpar cache do Laravel? Use docker compose exec app php artisan cache:clear.
Se precisar atualizar dependências, rode docker compose exec app composer update. Reinicie containers com docker compose down e docker compose up -d para aplicar mudanças.
Conclusão
Usar Laravel com Docker traz muita praticidade e garante um ambiente de desenvolvimento consistente.
Seguir as melhores práticas, configurar corretamente os serviços e gerenciar permissões evita problemas comuns.
Monitorar e atualizar o ambiente com cuidado mantém sua aplicação segura e performática em produção.
Com as dicas e comandos certos, você ganha agilidade no desenvolvimento e maior controle sobre seu projeto.
FAQ – Perguntas frequentes sobre Laravel com Docker
Como faço para conectar o Laravel ao banco de dados no Docker?
Verifique se o valor da variável DB_HOST no arquivo .env corresponde ao nome do serviço do banco definido no docker-compose.yml.
O que devo fazer se os containers não subirem corretamente?
Use o comando docker compose logs nome-do-serviço para verificar os erros e identificar o problema.
Como resolver problemas de permissão em pastas do Laravel dentro do Docker?
Ajuste o dono das pastas storage e bootstrap/cache para o usuário www-data usando chown para evitar erros de gravação.
Como limpar o cache do Laravel no ambiente Docker?
Execute docker compose exec app php artisan cache:clear para limpar o cache da aplicação.
Qual o comando para atualizar as dependências do Laravel usando Docker?
Use docker compose exec app composer update para atualizar as dependências dentro do container.
Como faço para reiniciar os containers após alterações no ambiente?
Pare os containers com docker compose down e suba novamente com docker compose up -d para aplicar as mudanças.
