Base de Conhecimento

Laravel na VPS: como publicar seu projeto com Nginx

  • laravel, nginx, php, vps, supervisor
  • Usuários acharam útil: 0

Passo a passo para publicar um projeto Laravel numa VPS com Nginx e PHP-FPM: requisitos, .env de produção, deploy, filas com Supervisor e agendador no cron.

Por Redação Eleven Host · @robson.direitodigital · 2 de novembro de 2026 · 10 min de leitura

Arte da Eleven Host: janela de terminal com o título: Laravel na VPS: como publicar seu projeto com Nginx

Capa da Redação Eleven Host para o guia: Laravel na VPS: como publicar seu projeto com Nginx Arte: Eleven Host

Laravel na VPS é uma forma de colocar no ar um projeto feito com o framework, atrás do Nginx e do PHP-FPM, num servidor que você controla. Segundo a documentação, o Laravel é um framework de aplicações web com sintaxe expressiva e elegante.

Aqui você vê os requisitos, a configuração do Nginx da documentação, o arquivo .env de produção, os comandos de deploy, a fila com Supervisor e o agendador no cron. Se você ainda não conhece o servidor VPS, comece por O que é servidor VPS: guia simples para iniciantes. Os exemplos usam example.com no lugar do seu domínio.

Requisitos do Laravel 13

Na versão 13, segundo a página de releases do Laravel, o framework exige PHP 8.3 ou superior. A tabela de suporte da mesma página lista a faixa de PHP 8.3 a 8.5 para o Laravel 13, que foi lançado em 17 de março de 2026.

A página de deployment pede estas extensões do PHP: Ctype, cURL, DOM, Fileinfo, Filter, Hash, Mbstring, OpenSSL, PCRE, PDO, Session, Tokenizer e XML.

O Laravel 13 exige PHP 8.3 ou superior, e o socket do PHP-FPM no Nginx precisa bater com a versão do PHP que você instalou.

A licença do framework, segundo o README no GitHub, é a MIT: o Laravel é um software de código aberto licenciado sob a licença MIT. Em caso de dúvida sobre uso comercial, consulte um profissional.

Instalar o PHP e o Composer

A documentação de instalação do Laravel traz um comando que instala PHP, Composer e o instalador do Laravel, mas ele é pensado para a máquina local e funciona baixando um script e executando na hora:

/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.5)"

Como ele executa o que vem da internet, leia o script antes de rodar. Você também pode instalar o PHP pelos pacotes da sua distribuição, na versão 8.3 ou superior, com as extensões listadas acima e o PHP-FPM, que é o que o Nginx chama.

Para o Composer, siga a página getcomposer.org/download. Ela mostra as linhas do instalador, incluindo uma verificação de hash que muda a cada versão, então copie essas linhas direto da página. Um exemplo de comando para rodar o instalador depois da verificação e deixá-lo disponível no sistema:

php composer-setup.php

php -r "unlink('composer-setup.php');"

sudo mv composer.phar /usr/local/bin/composer

A página do Composer também avisa para não redistribuir o código de instalação, porque ele muda a cada versão do instalador.

Levar o projeto para o servidor

A documentação mostra como criar um projeto novo com composer global require laravel/installer e laravel new example-app. Para um projeto que já existe no seu repositório, um exemplo de comandos é clonar o código para a pasta do site e instalar as dependências sem as de desenvolvimento:

git clone https://example.com/seu-usuario/seu-projeto.git /srv/example.com

cd /srv/example.com

composer install --no-dev

O Laravel precisa escrever nas pastas bootstrap/cache e storage, e a documentação pede que o dono do processo do servidor web tenha permissão nelas. Um exemplo de comando, supondo que o PHP-FPM rode com o usuário www-data:

sudo chown -R www-data:www-data /srv/example.com/storage /srv/example.com/bootstrap/cache

Confira com qual usuário o seu PHP-FPM roda antes de usar o exemplo. Para ver como manter e inspecionar o serviço depois, veja systemctl: como iniciar, parar e ver serviços na VPS.

Configurar o Nginx

A página de deployment do Laravel 13 traz uma configuração de Nginx. O ponto central é o root apontar para a pasta public do projeto. A própria documentação avisa que o arquivo provavelmente precisa ser ajustado ao seu servidor e que mover o index.php para a raiz do projeto expõe muitos arquivos de configuração sensíveis à internet.

Esta é a configuração, uma linha por bloco de código:

server {

listen 80;

listen [::]:80;

server_name example.com;

root /srv/example.com/public;

add_header X-Frame-Options "SAMEORIGIN";

add_header X-Content-Type-Options "nosniff";

index index.php;

charset utf-8;

location / {

try_files $uri $uri/ /index.php?$query_string;

}

location = /favicon.ico { access_log off; log_not_found off; }

location = /robots.txt { access_log off; log_not_found off; }

error_page 404 /index.php;

location ~ ^/index\.php(/|$) {

fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;

fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;

include fastcgi_params;

fastcgi_buffer_size 32k;

fastcgi_buffers 8 32k;

fastcgi_busy_buffers_size 64k;

fastcgi_hide_header X-Powered-By;

}

location ~ \.php$ {

return 404;

}

location ~ /\.(?!well-known).* {

deny all;

}

}

O que cada parte faz:

  • server_name e root: troque example.com pelo seu domínio e /srv/example.com/public pelo caminho da pasta public do projeto.
  • try_files: manda os pedidos que não são arquivos para o index.php, onde o Laravel resolve as rotas.
  • fastcgi_pass: o socket php8.3-fpm.sock é o da versão 8.3. Se você instalou outra versão do PHP, o nome do socket muda.
  • location ~ \.php$: devolve 404 para os demais arquivos PHP.
  • location ~ /\.(?!well-known).*: bloqueia o acesso a arquivos ocultos, como o .env, e libera apenas a pasta .well-known.

Salve o arquivo na configuração de sites do Nginx. Um exemplo de comandos para testar e recarregar o serviço:

sudo nginx -t

sudo systemctl reload nginx

Se você pretende ter vários sites no mesmo servidor, o guia Nginx Proxy Manager: vários sites numa VPS só mostra outra forma de organizar os domínios.

Está comparando planos de servidor? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver os planos de VPS

Banco de dados no .env

O padrão do Laravel é o SQLite. Para usar o MySQL, a documentação de instalação mostra estas variáveis no .env:

DB_CONNECTION=mysql

DB_HOST=127.0.0.1

DB_PORT=3306

DB_DATABASE=laravel

DB_USERNAME=root

DB_PASSWORD=

O usuário root é o que a documentação usa no exemplo. Um conselho para produção: crie um usuário próprio do banco, com senha, para o projeto.

Preparar o .env de produção

O arquivo .env guarda a configuração de cada ambiente. A documentação diz que ele não deve ir para o controle de versão, porque isso seria um risco de segurança caso alguém invadisse o repositório. Crie-o no servidor, a partir do exemplo do projeto, e ajuste estas variáveis:

APP_ENV=production

APP_DEBUG=false

  • APP_ENV: define o ambiente atual da aplicação, segundo a documentação.
  • APP_DEBUG: em produção, o valor deve ser false. Com true, você corre o risco de expor valores sensíveis de configuração aos usuários da aplicação.
  • APP_KEY: a documentação manda gerar o valor com o comando abaixo.

php artisan key:generate

Trocar a chave depois que o site está em uso desloga todos os usuários e impede ler os dados que foram cifrados com a chave antiga. O Laravel tem a variável APP_PREVIOUS_KEYS para fazer essa rotação.

Migrações e otimização no deploy

Em produção, o php artisan migrate pede confirmação. Para rodar sem o aviso, a documentação de migrações indica a opção --force:

php artisan migrate --force

Depois vem a otimização. A página de deployment diz que o comando abaixo deve ser chamado, em geral, como parte do processo de deploy:

php artisan optimize

Para desfazer, use php artisan optimize:clear. Atenção: com a configuração em cache, o arquivo .env deixa de ser carregado e as chamadas à função env retornam null. Por isso, só chame env() dentro dos arquivos da pasta config.

Se o projeto já tem serviços de longa duração rodando, a documentação cita o php artisan reload para reiniciá-los depois do deploy. A rota /up responde com status 200 quando a aplicação subiu, o que ajuda a conferir o resultado.

Filas com o Supervisor

Se o projeto usa filas, o processo queue:work precisa ficar rodando. A documentação de filas usa o Supervisor para isso. Para instalar:

sudo apt-get install supervisor

Os arquivos de configuração ficam em /etc/supervisor/conf.d. O exemplo da documentação, no arquivo laravel-worker.conf:

[program:laravel-worker]

process_name=%(program_name)s_%(process_num)02d

command=php /home/forge/app.com/artisan queue:work --sleep=3 --tries=3 --max-time=3600

autostart=true

autorestart=true

stopasgroup=true

killasgroup=true

user=forge

numprocs=8

redirect_stderr=true

stdout_logfile=/home/forge/app.com/worker.log

stopwaitsecs=3600

Os caminhos /home/forge/app.com, o user=forge e o numprocs=8 são valores do exemplo: adapte-os ao seu servidor. A documentação pede que o valor de stopwaitsecs seja maior que o tempo, em segundos, do seu job mais demorado. Para ler o arquivo e subir os processos:

sudo supervisorctl reread

sudo supervisorctl update

sudo supervisorctl start "laravel-worker:*"

A cada deploy, rode o comando abaixo. Ele faz os workers saírem de forma ordenada depois de terminar o job atual, para que nenhum job existente seja perdido, e o Supervisor os sobe de novo:

php artisan queue:restart

Agendador no cron

Para tarefas agendadas, a documentação diz que é preciso uma única entrada no cron do servidor que roda o comando schedule:run a cada minuto. Adicione a linha ao cron, trocando o caminho pelo do seu projeto:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

O Laravel decide, a cada minuto, quais tarefas do seu código devem rodar. Se você faz scripts em outra linguagem, o guia Bot em Python na VPS: como deixar o seu rodando mostra uma forma de manter um processo ativo no servidor.

Manutenção e atualização

Para colocar o site em modo de manutenção, a documentação indica php artisan down, e para tirar, php artisan up. Enquanto o modo de manutenção está ativo, nenhum job da fila é processado.

php artisan down

php artisan up

Sobre atualizar o framework, as notas de versão dizem que a equipe se esforça para que você consiga atualizar para uma nova versão maior em um dia ou menos, e há um guia de upgrade na documentação.

Checklist do Laravel na VPS

  • PHP 8.3 ou superior e as extensões pedidas pela documentação.
  • root do Nginx apontando para a pasta public, e o socket do PHP-FPM igual à versão instalada.
  • .env criado no servidor, fora do controle de versão, com APP_ENV=production e APP_DEBUG=false.
  • php artisan key:generate uma vez, ao criar o .env; php artisan migrate --force e php artisan optimize no deploy.
  • Permissão de escrita em storage e bootstrap/cache.
  • Supervisor com stopwaitsecs maior que o job mais longo, e php artisan queue:restart a cada deploy.
  • Uma entrada no cron com o schedule:run a cada minuto.

Vai escolher onde instalar? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver os planos de VPS

Perguntas frequentes

Qual versão do PHP o Laravel 13 exige?

PHP 8.3 ou superior. A página de releases do Laravel diz que a versão 13 exige no mínimo o PHP 8.3, e a tabela de suporte lista a faixa de 8.3 a 8.5.

Para onde o root do Nginx deve apontar?

Para a pasta public do projeto. A documentação avisa que mover o index.php para a raiz expõe muitos arquivos de configuração sensíveis à internet.

Posso deixar o APP_DEBUG como true em produção?

Não é indicado. A documentação diz que, em produção, o valor deve ser false, porque com true você corre o risco de expor valores sensíveis de configuração aos usuários.

Como rodo as filas e as tarefas agendadas?

As filas usam o Supervisor com o queue:work, e as tarefas agendadas usam uma entrada no cron que executa o schedule:run a cada minuto.

Preciso rodar o migrate com alguma opção em produção?

Só se quiser rodar sem a pergunta de confirmação. Nesse caso, a documentação indica a opção --force: php artisan migrate --force.

Esta resposta lhe foi útil?

Artigos Relacionados