Servir uma aplicação Laravel com Apache no Debian 13

O Apache continua a ser o servidor web mais espalhado em alojamento partilhado e nas máquinas instaladas há mais tempo. Servir uma aplicação Laravel por trás do Apache exige três coisas: um host virtual cuja raiz aponte para public/, o módulo de reescrita ativado e AllowOverride All para que o ficheiro .htaccess fornecido pelo Laravel seja lido.

Este capítulo faz parte da instalação do Laravel num servidor Debian, dentro do percurso Desenvolvimento web. Esquecer o terceiro ponto é a causa quase sistemática das rotas em erro 404. Passos verificados no Debian 13 com o Apache 2.4.68 e o Laravel 13.30.1.

Instalar o Apache e o módulo PHP

sudo apt update
sudo apt install -y apache2 libapache2-mod-php
apache2 -v

Server version: Apache/2.4.68 (Debian)

O pacote libapache2-mod-php ativa o PHP no Apache. Confirma:

a2query -m | grep php

php8.4 (enabled by maintainer script)

Ativa em seguida o módulo de reescrita, que não fica ativo por predefinição:

sudo a2enmod rewrite

Colocar o projeto

Cria a aplicação com o Composer, a partir de uma conta sem privilégios:

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

Dê depois direitos de escrita às três únicas pastas que deles precisam, database/ incluída enquanto a aplicação usar a base SQLite criada na instalação:

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
sudo chmod o+x /home/deploy   # O Apache tem de conseguir atravessar a pasta pessoal

Criar o host virtual

<VirtualHost *:80>
    ServerName exemple.com
    DocumentRoot /home/deploy/app/public

    <Directory /home/deploy/app/public>
        AllowOverride All
        Require all granted
        Options -Indexes +FollowSymLinks
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/laravel-error.log
    CustomLog ${APACHE_LOG_DIR}/laravel-access.log combined
</VirtualHost>

Ativa o site, desativa o site por omissão e verifica a sintaxe:

sudo a2ensite laravel
sudo a2dissite 000-default
sudo apache2ctl configtest
sudo systemctl reload apache2

Syntax OK

AllowOverride All: a linha que decide tudo

O Laravel traz um ficheiro public/.htaccess que encaminha todos os pedidos para index.php. O Apache só lê esse ficheiro se a diretiva AllowOverride o autorizar. Sem ela, a página inicial aparece, mas nenhuma outra rota responde.

O comportamento foi medido na rota de saúde /up, presente em qualquer instalação recente:

É este o sintoma a reconhecer: a página inicial funciona, todo o resto devolve 404. O problema não está nas rotas nem no código, mas na configuração do Apache.

O início do .htaccess fornecido pelo Laravel, de que depende este mecanismo:

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews -Indexes
    </IfModule>

    RewriteEngine On

    # Handle X-XSRF-Token Header
    RewriteCond %{HTTP:x-xsrf-token} .
    RewriteRule .* - [E=HTTP_X_XSRF_TOKEN:%{HTTP:X-XSRF-Token}]

    # Handle Authorization Header
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

Verificar a instalação

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

accueil : 200
route   : 200
.env    : 404

O 404 em /.env é o resultado esperado: como a raiz do site é public/, o ficheiro fica fora da árvore servida e não é sequer alcançável. Se obtiveres 200, é porque o DocumentRoot aponta para a raiz do projeto em vez de public/, e as tuas credenciais de base de dados estão publicamente legíveis.

Passar para HTTPS

O Certbot altera ele próprio o host virtual e trata da renovação automática:

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

Lembra-te de desativar o modo de depuração e de alinhar o APP_URL pelo endereço em HTTPS, senão os links e os assets gerados pelo Laravel continuam a apontar para HTTP:

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

php artisan config:cache
php artisan route:cache
php artisan view:cache

Apache ou nginx

O .htaccess é a vantagem decisiva do Apache em alojamento partilhado: permite configurar a reescrita sem acesso à configuração do servidor. Numa máquina que administras, ambos servem, e a escolha faz-se por aquilo que sabes explorar.