Laravel z Apache na Debianie 13: konfiguracja wirtualnego hosta

Apache wciąż pozostaje najczęściej spotykanym serwerem WWW na hostingu współdzielonym i na maszynach postawionych wiele lat temu. Żeby wystawić aplikację Laravel za Apache, potrzebujesz trzech rzeczy: wirtualnego hosta z katalogiem głównym ustawionym na public/, włączonego modułu przepisywania adresów oraz AllowOverride All, żeby Apache czytał plik .htaccess dostarczany przez Laravel.

Ten rozdział należy do instalacji Laravela na serwerze Debian, w ścieżce Programowanie webowe. Pominięcie trzeciego punktu to niemal zawsze przyczyna tras kończących się błędem 404. Kroki sprawdzone na Debianie 13 z Apache 2.4.68 i Laravelem 13.30.1.

Instalacja Apache i modułu PHP

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

Server version: Apache/2.4.68 (Debian)

Pakiet libapache2-mod-php włącza PHP w Apache. Sprawdź to:

a2query -m | grep php

php8.4 (enabled by maintainer script)

Następnie włącz moduł przepisywania adresów, który domyślnie nie jest aktywny:

sudo a2enmod rewrite

Umieszczenie projektu

Utwórz aplikację przy pomocy Composera, na koncie bez uprawnień administratora:

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

Następnie nadaj prawa zapisu tylko trzem katalogom, które ich potrzebują, w tym database/, dopóki aplikacja używa bazy SQLite utworzonej przy instalacji:

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   # Apache musi mieć prawo wejścia do katalogu domowego

Utworzenie wirtualnego hosta

<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>

Włącz witrynę, wyłącz domyślną i sprawdź składnię:

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

Syntax OK

AllowOverride All: linijka, która decyduje o wszystkim

Laravel dostarcza plik public/.htaccess, który kieruje wszystkie żądania do index.php. Apache czyta ten plik tylko wtedy, gdy pozwala na to dyrektywa AllowOverride. Bez niej strona główna się wyświetla, ale żadna inna trasa nie odpowiada.

Zachowanie zmierzyliśmy na trasie zdrowia /up, obecnej w każdej świeżej instalacji:

To objaw, który warto rozpoznać od razu: strona główna działa, cała reszta zwraca 404. Problem nie leży ani w trasach, ani w kodzie, tylko w konfiguracji Apache.

Początek pliku .htaccess dostarczanego przez Laravel, od którego zależy cały mechanizm:

<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}]

Sprawdzenie instalacji

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

Odpowiedź 404 na /.env to wynik oczekiwany: skoro katalogiem głównym witryny jest public/, plik leży poza serwowanym drzewem i zwyczajnie nie da się do niego dotrzeć. Jeśli dostajesz 200, to DocumentRoot wskazuje katalog projektu zamiast public/, a dane dostępowe do bazy każdy może sobie odczytać.

Przejście na HTTPS

Certbot sam modyfikuje wirtualnego hosta i ustawia automatyczne odnawianie certyfikatu:

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

Pamiętaj, żeby wyłączyć tryb debugowania i ustawić APP_URL na adres w HTTPS, inaczej linki i zasoby generowane przez Laravel dalej będą wskazywać na 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 czy nginx

Na hostingu współdzielonym .htaccess jest decydującą przewagą Apache: pozwala skonfigurować przepisywanie adresów bez dostępu do konfiguracji serwera. Na maszynie, którą administrujesz sam, sprawdzą się oba serwery, a wybór sprowadza się do tego, co potrafisz utrzymać.