Instalacja Laravela 13 na serwerze Debian 13 krok po kroku

Ten przewodnik prowadzi przez pełną instalację aplikacji Laravel 13 na serwerze Debian 13, od czystego systemu po stronę serwowaną przez nginx. Każdy krok został wykonany 2 września 2026 na świeżym Debianie 13 „trixie”, a wynik końcowy sprawdzony: odpowiedź HTTP 200 na stronie głównej, plik .env niedostępny z sieci.

Artykuł ze ścieżki Programowanie webowe. Pięć etapów ma własny, szczegółowy rozdział, wypisany w pasku bocznym. Poniżej jest cała sekwencja, z dokładnie tym, co potrzebne, żeby dojść do końca.

Czego potrzebujesz na start

• Serwer Debian 13 „trixie” dostępny przez SSH. Debian 12 też się nada, z PHP 8.2.
• Użytkownik inny niż root, z prawem do sudo. Nie instaluj i nie wdrażaj na koncie root.
• Stacja robocza po twojej stronie. Na macOS typową przeszkodą jest nieznajdowana komenda laravel.
• Domena wskazująca na serwer, jeśli planujesz HTTPS.

Jeśli jeszcze go nie ma, utwórz użytkownika, na którym stanie aplikacja:

sudo adduser deploy
sudo usermod -aG sudo deploy

1. PHP i jego rozszerzenia

Debian 13 dostarcza PHP 8.4, więc zewnętrzne repozytorium Sury jest zbędne:

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

Listę wymaganych rozszerzeń, ustawienia php.ini i sposób instalacji innej wersji PHP znajdziesz w rozdziale poświęconym PHP.

2. Composer

Zainstaluj go, sprawdzając sumę kontrolną instalatora, tak jak nakazuje oficjalna dokumentacja:

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. Utworzenie projektu Laravel

Jako użytkownik deploy, nigdy jako 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

create-project generuje plik .env, tworzy klucz aplikacji i uruchamia migracje na domyślnej bazie SQLite. Dla bazy MySQL lub MariaDB, której instalacji poświęcony jest osobny rozdział, uzupełnij dane połączenia i uruchom migracje ponownie:

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. Uprawnienia do plików

To krok, który się pomija i który daje białą stronę albo błąd 500. Chodzi o katalogi odpowiadające storage_path() i bootstrap/cache, opisane w ścieżkach aplikacji, plus database/, dopóki aplikacja używa bazy SQLite utworzonej przy instalacji: sterownik sesji zapisuje do niej przy każdej wizycie. Serwer WWW musi móc pisać w tych trzech katalogach, i tylko w nich:

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

Jeśli projekt leży w katalogu domowym użytkownika, nginx musi móc przez ten katalog przejść:

sudo chmod o+x /home/deploy

5. nginx i PHP-FPM

Ta sekcja instaluje nginx. Jeśli wolisz Apache’a, częstszego na hostingu współdzielonym, przejdź zamiast tego do rozdziału o Apache’u: dalsza część przewodnika pozostaje aktualna.

sudo apt install -y nginx php-fpm

Sprawdź dokładną ścieżkę do socketu, zawiera numer wersji PHP:

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

Utwórz plik konfiguracji witryny. Katalog główny wskazuje na public/, nigdy na katalog projektu:

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

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

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. Weryfikacja instalacji

Dwie kontrole wystarczą, żeby wiedzieć, czy instalacja się trzyma:

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

Druga kontrola jest ważniejsza. 200 na /.env oznaczałoby, że dane dostępowe do bazy i twój APP_KEY są publicznie czytelne. Powstrzymuje to blok location ~ /\.(?!well-known).* i właśnie dlatego katalogiem głównym witryny musi być public/.

7. Przejście na produkcję

Konfiguracja deweloperska wypuszcza informacje na zewnątrz. Trzy linie w .env:

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

Potem cache, do przebudowania po każdym wdrożeniu:

composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan about --only=environment   # Debug Mode musi pokazywać OFF

Szczegóły tego ustawienia omawia artykuł o trybie debugowania.

Dodaj HTTPS przez Certbota, który sam zmienia konfigurację nginx:

Jeśli aplikacja wystawia publiczne formularze, przewidź też ochronę przed automatycznymi wysyłkami.

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

Na koniec harmonogram zadań, jeśli aplikacja z niego korzysta:

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

Po cache, sesje i kolejki na Redisie sięgnij do rozdziału poświęconego Redisowi.