Instalar o Laravel 13 num servidor Debian 13 com nginx

Este guia percorre a instalação completa de uma aplicação Laravel 13 num servidor Debian 13, de um sistema virgem até uma página servida pelo nginx. Cada etapa foi executada num Debian 13 «trixie» limpo a 2 de setembro de 2026, e o resultado final verificado: resposta HTTP 200 na página inicial, ficheiro .env inacessível a partir da web.

Artigo do percurso Desenvolvimento web. Cinco etapas têm o seu próprio capítulo detalhado, listado na barra lateral. O que se segue é a sequência completa, com o que é preciso para chegar ao fim.

O que é preciso antes de começar

• Um servidor Debian 13 «trixie» acessível por SSH. O Debian 12 também serve, com PHP 8.2.
• Um utilizador não-root com sudo. Não instales nem faças deploy como root.
• Uma máquina de desenvolvimento do teu lado. No macOS, o bloqueio habitual é o comando laravel não encontrado.
• Um nome de domínio a apontar para o servidor, se contas usar HTTPS.

Cria o utilizador que vai suportar a aplicação, se ainda não existir:

sudo adduser deploy
sudo usermod -aG sudo deploy

1. O PHP e as suas extensões

O Debian 13 fornece o PHP 8.4, o que dispensa o repositório externo Sury:

sudo apt update
sudo apt install -y php-cli php-fpm \
  php-mbstring php-xml php-curl php-zip \
  php-bcmath php-intl php-mysql php-sqlite3 \
  unzip curl ca-certificates

php -v   # PHP 8.4.24

O detalhe das extensões necessárias, as afinações do php.ini e o procedimento para instalar outra versão do PHP estão no capítulo dedicado ao PHP.

2. O Composer

Instala-o verificando a assinatura do instalador, como prescreve a documentação oficial:

EXPECTED="$(curl -sS https://composer.github.io/installer.sig)"
curl -sS https://getcomposer.org/installer -o composer-setup.php
ACTUAL="$(php -r 'echo hash_file("sha384", "composer-setup.php");')"

if [ "$EXPECTED" = "$ACTUAL" ]; then
    sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
fi
rm composer-setup.php

composer --version   # Composer version 2.10.3

3. Criar o projeto Laravel

Como utilizador deploy, nunca como root:

su - deploy
composer create-project laravel/laravel /home/deploy/app --no-interaction
cd /home/deploy/app
php artisan --version   # Laravel Framework 13.30.1

O create-project gera o ficheiro .env, cria a chave da aplicação e executa as migrações na base SQLite predefinida. Para uma base MySQL ou MariaDB, cuja instalação tem um capítulo próprio, preenche a ligação e volta a lançar as migrações:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=un_mot_de_passe_solide

php artisan migrate --force

4. Permissões dos ficheiros

É o passo que se salta e que produz a página em branco, ou um erro 500. As pastas em causa correspondem a storage_path() e bootstrap/cache, descritas em os caminhos da aplicação, mais database/ enquanto a aplicação usar a base SQLite criada na instalação: o driver de sessão escreve nela a cada visita. O servidor web tem de poder escrever nestas três pastas, e apenas nestas:

sudo chown -R deploy:www-data /home/deploy/app/storage /home/deploy/app/bootstrap/cache /home/deploy/app/database
sudo chmod -R 775 /home/deploy/app/storage /home/deploy/app/bootstrap/cache /home/deploy/app/database

Se o projeto viver na pasta pessoal de um utilizador, o nginx tem de a poder atravessar:

sudo chmod o+x /home/deploy

5. nginx e PHP-FPM

Esta secção instala o nginx. Se preferires o Apache, mais comum em alojamento partilhado, segue antes o capítulo dedicado ao Apache: o resto do guia mantém-se válido.

sudo apt install -y nginx php-fpm

Anota o caminho exato do socket, que traz o número de versão do PHP:

grep -h '^listen' /etc/php/8.4/fpm/pool.d/www.conf
# listen = /run/php/php8.4-fpm.sock

Cria o ficheiro do site. A raiz aponta para public/, nunca para a raiz do projeto:

server {
    listen 80;
    server_name exemple.com;
    root /home/deploy/app/public;
    index index.php;

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

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

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
        fastcgi_index index.php;
        include fastcgi.conf;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Ativa o site, desativa o predefinido, verifica a sintaxe:

sudo ln -s /etc/nginx/sites-available/laravel /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

6. Verificar a instalação

Bastam dois controlos para saber se a instalação se aguenta:

curl -s -o /dev/null -w "page d'accueil : %{http_code}\n" http://127.0.0.1/
curl -s -o /dev/null -w ".env          : %{http_code}\n" http://127.0.0.1/.env

page d'accueil : 200
.env          : 403

O segundo é o mais importante. Um 200 em /.env significaria que as tuas credenciais de base de dados e a tua APP_KEY são publicamente legíveis. É o bloco location ~ /\.(?!well-known).* que o impede, e é por isso que a raiz do site tem de ser public/.

7. Passar a produção

A configuração de desenvolvimento deixa fugir informação. Três linhas no .env:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://exemple.com

Depois as caches, a regenerar a seguir a cada deploy:

composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan about --only=environment   # O Debug Mode deve mostrar OFF

O detalhe desta afinação é tratado no artigo sobre o modo de depuração.

Acrescenta o HTTPS com o Certbot, que altera ele próprio a configuração do nginx:

Se a aplicação expuser formulários públicos, prevê também uma proteção contra os envios automatizados.

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d exemple.com

Por fim, o agendador de tarefas, se a aplicação usar algum:

sudo crontab -u deploy -e
# * * * * * cd /home/deploy/app && php artisan schedule:run >> /dev/null 2>&1

Para a cache, as sessões e as filas de espera em Redis, continua com o capítulo dedicado ao Redis.