Cum să instalezi și să configurezi Laravel cu Nginx pe Ubuntu 24.04: Ghidul definitiv

Implementarea unei aplicații Laravel într-un mediu de producție necesită o stivă de server robustă, sigură și performantă. Combinația dintre Nginx ca server web și PHP-FPM pentru procesare oferă o fundație extrem de eficientă pentru aplicațiile PHP moderne. Acest ghid oferă o prezentare completă, pas cu pas, pentru instalarea și configurarea unei aplicații Laravel 11 gata de producție pe un server care rulează Ubuntu 24.04. Vom construi o stivă LEMP completă (Linux, Nginx, MySQL, PHP), securizând-o cu permisiuni corespunzătoare pentru fișiere, creând un utilizator dedicat pentru baza de date, configurând blocurile de server Nginx pentru o rutare optimă și activând criptarea SSL cu Let's Encrypt. La sfârșitul acestui tutorial, veți avea un mediu scalabil și sigur, gata să găzduiască proiectul dvs. Laravel, construit conform celor mai bune practici din industrie.

Cerințe preliminare

Înainte de a începe acest tutorial, trebuie să aveți o instanță de server curată care rulează Ubuntu 24.04. Toate comenzile din acest ghid presupun că operați de la această bază. De asemenea, veți avea nevoie de următoarele, complet configurate:

• Un utilizator non-root cu privilegii sudo: Toate comenzile trebuie executate ca un utilizator obișnuit cu permisiuni `sudo`. Rularea comenzilor direct ca utilizator `root` este un risc de securitate care poate duce la daune accidentale și ireversibile ale sistemului.
• O stivă LEMP complet configurată: Acest tutorial se concentrează pe implementarea Laravel într-un mediu LEMP (Linux, Nginx, MySQL, PHP) existent. Trebuie să aveți Nginx, MySQL 8 (sau o alternativă compatibilă) și PHP 8.3 instalate și funcționale.
• Composer instalat global: Composer este managerul de dependențe pentru PHP, iar Laravel se bazează pe acesta pentru instalare și gestionarea pachetelor. Trebuie să fie instalat și disponibil în PATH-ul sistemului dvs.
• Un nume de domeniu: Pentru o configurație de producție, ar trebui să aveți un nume de domeniu complet calificat (FQDN) cu înregistrarea sa DNS 'A' direcționată către adresa IP publică a serverului dvs. Acest lucru este necesar pentru generarea unui certificat SSL valid.

Acest ghid vă va îndruma prin fiecare pas, dar presupune că porniți de la un server privat virtual (VPS) provizionat corespunzător. Dacă lipsesc oricare dintre componentele preliminare, trebuie să le instalați și să le configurați înainte de a continua.

Pasul 1: Instalarea PHP 8.3 și a extensiilor esențiale

Laravel 11 necesită un minim de PHP 8.2. Pentru a asigura suport pe termen lung și acces la cele mai recente îmbunătățiri de performanță, acest ghid utilizează PHP 8.3, care este disponibil direct din depozitele de pachete implicite ale Ubuntu 24.04. Pe lângă procesorul de bază PHP-FPM, Laravel necesită un set specific de extensii PHP pentru a gestiona conexiunile la bazele de date, parsarea XML, manipularea șirurilor de caractere și alte sarcini critice. Fără aceste extensii, instalarea va eșua sau framework-ul nu va funcționa corect.

Mai întâi, actualizați indexul de pachete al serverului pentru a vă asigura că preluați cele mai recente versiuni disponibile:

sudo apt update

Acum, instalați PHP-FPM și extensiile necesare. Fiecare extensie servește unui scop specific:

• php8.3-fpm: Managerul de Procese FastCGI, care este responsabil pentru executarea codului PHP.
• php8.3-mysql: Permite PHP să se conecteze la bazele de date MySQL.
• php8.3-mbstring: Oferă funcții pentru manipularea șirurilor multi-byte, esențiale pentru suportul UTF-8.
• php8.3-xml: Necesar pentru manipularea XML, utilizat de multe pachete Composer.
• php8.3-bcmath: Oferă suport pentru matematică cu precizie arbitrară, utilizat de biblioteci precum Laravel Cashier.
• php8.3-curl: Permite PHP să facă cereri HTTP, utilizat de Guzzle și clientul HTTP al Laravel.
• php8.3-zip: Permite gestionarea arhivelor .zip.
• php8.3-gd: O bibliotecă de procesare a imaginilor utilizată pentru sarcini precum redimensionarea avatarelor.
• php8.3-intl: Oferă funcții de internaționalizare.

sudo apt install php8.3-fpm php8.3-mysql php8.3-mbstring php8.3-xml php8.3-bcmath php8.3-curl php8.3-zip php8.3-gd php8.3-intl

Odată ce instalarea este finalizată, verificați dacă versiunea corectă de PHP este activă rulând:

php -v

Rezultatul ar trebui să confirme că rulați PHP 8.3.x. Trecerea la PHP 8.3 oferă avantaje semnificative față de versiunile mai vechi, unele benchmark-uri arătând câștiguri de performanță de până la 50% în comparație cu PHP 7.4, datorită optimizărilor din compilatorul JIT (Just-In-Time) și unei gestionări mai eficiente a memoriei.

Pasul 2: Securizarea unei baze de date dedicate pentru Laravel

Pentru orice aplicație de producție, crearea unei baze de date și a unui utilizator dedicate este o măsură de securitate nenegociabilă. Aceasta respectă principiul privilegiului minim, care dictează că o aplicație ar trebui să aibă acces doar la resursele absolut necesare pentru funcționarea sa. Acest lucru previne ca o potențială vulnerabilitate de injecție SQL în aplicația dvs. Laravel să afecteze alte baze de date de pe același server.

Mai întâi, conectați-vă la interfața de linie de comandă MySQL ca utilizator root:

sudo mysql

Apoi, creați o nouă bază de date pentru aplicația dvs. Pentru acest ghid, o vom numi `laravel_app`. Utilizarea setului de caractere `utf8mb4` este standardul actual, deoarece oferă suport complet pentru Unicode, inclusiv emoji-uri, ceea ce este esențial pentru aplicațiile web moderne.

CREATE DATABASE laravel_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Acum, creați un nou utilizator MySQL dedicat. Vom numi acest utilizator `laravel_user`. În mod crucial, vom restricționa acest utilizator să se conecteze doar de la `localhost`. Acesta este un pas vital de consolidare a securității care previne orice încercare de conectare la baza de date de la o locație la distanță folosind aceste acreditări. Înlocuiți `parola_ta_securizata` cu o parolă puternică, generată aleatoriu.

CREATE USER 'laravel_user'@'localhost' IDENTIFIED BY 'parola_ta_securizata';

Cu utilizatorul creat, acordați-i privilegii complete, dar *doar* pentru baza de date `laravel_app`. Acest utilizator nu va avea acces la nicio altă bază de date de pe server.

GRANT ALL PRIVILEGES ON laravel_app.* TO 'laravel_user'@'localhost';

În cele din urmă, reîncărcați privilegiile MySQL pentru a vă asigura că modificările sunt aplicate imediat, apoi părăsiți clientul.

FLUSH PRIVILEGES;
EXIT;

Pasul 3: Instalarea și configurarea proiectului Laravel

Cu stiva serverului complet pregătită, puteți acum instala framework-ul Laravel în sine. Vom folosi Composer pentru a crea un nou proiect. Locația standard pentru aplicațiile web pe Ubuntu este în directorul `/var/www`.

Navigați la acest director și executați comanda `composer create-project`. Aceasta va crea un nou director numit `laravel_app`, va descărca cea mai recentă versiune stabilă a Laravel și va instala toate dependențele sale terțe necesare.

cd /var/www
composer create-project laravel/laravel laravel_app

După ce Composer termină, navigați în directorul proiectului nou creat.

cd laravel_app

Următoarea sarcină critică este configurarea mediului aplicației. Laravel utilizează un fișier special numit `.env` pentru a stoca variabile specifice mediului, cum ar fi acreditările bazei de date și cheile API. Acest lucru vă permite să păstrați informațiile sensibile separate de baza de cod controlată prin versiuni. Deschideți fișierul `.env` pentru editare:

nano .env

Localizați secțiunea `DB_` și actualizați valorile pentru a se potrivi cu numele bazei de date, numele de utilizator și parola pe care le-ați creat la pasul anterior.

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_app
DB_USERNAME=laravel_user
DB_PASSWORD=parola_ta_securizata

Cât timp acest fișier este deschis, trebuie să faceți alte două modificări cruciale pentru un mediu de producție. Setați `APP_ENV` la `production` și, cel mai important, setați `APP_DEBUG` la `false`. Lăsarea modului de depanare activat în producție este o vulnerabilitate de securitate severă, deoarece poate expune date de configurare sensibile și urme de stivă publicului în cazul unei erori. De asemenea, setați `APP_URL` la domeniul dvs.

APP_ENV=production
APP_DEBUG=false
APP_URL=http://domeniul_tau.com

Salvați și închideți fișierul. Aplicația dvs. Laravel este acum instalată și configurată pentru a comunica cu baza sa de date.

Pasul 4: Configurarea Nginx și setarea permisiunilor corecte pentru fișiere

Acesta este cel mai critic pas pentru a vă asigura că aplicația dvs. este atât sigură, cât și funcțională. Implică două părți: setarea permisiunilor corecte pentru sistemul de fișiere și crearea unui bloc de server Nginx pentru a ruta corect traficul web.

Setarea permisiunilor pentru fișiere

Serverul web (Nginx) rulează ca un utilizator de sistem specific, care pe Ubuntu este `www-data`. Pentru ca Nginx să poată citi fișierele aplicației și pentru ca Laravel să poată scrie în directoarele sale de cache și log, acest utilizator `www-data` trebuie să aibă proprietatea și permisiunile corespunzătoare.

Mai întâi, schimbați proprietarul întregului director de proiect la utilizatorul și grupul `www-data`.

sudo chown -R www-data:www-data /var/www/laravel_app

Apoi, setați permisiunile standard. O permisiune de `755` pentru directoare permite proprietarului (www-data) să citească, să scrie și să execute, în timp ce grupul și ceilalți pot doar să citească și să execute. O permisiune de `644` pentru fișiere permite proprietarului să citească și să scrie, în timp ce ceilalți pot doar să citească. Aceasta este o valoare implicită sigură.

sudo chmod -R 755 /var/www/laravel_app

Cu toate acestea, Laravel trebuie să scrie în anumite directoare. Directorul `storage` (pentru loguri, sesiuni și vizualizări cache) și directorul `bootstrap/cache` (pentru fișiere de servicii compilate) necesită setări mai permisive. O permisiune de `775` permite proprietarului și grupului să scrie în aceste directoare.

sudo chmod -R 775 /var/www/laravel_app/storage
sudo chmod -R 775 /var/www/laravel_app/bootstrap/cache

Crearea blocului de server Nginx

Un bloc de server Nginx (similar cu un gazdă virtuală în Apache) îi spune lui Nginx cum să gestioneze cererile primite pentru un anumit domeniu. Vom crea un nou fișier de configurare pentru aplicația noastră Laravel.

sudo nano /etc/nginx/sites-available/laravel_app

Lipiți următoarea configurație gata de producție în fișier. Sub blocul de cod, vom detalia ce face fiecare directivă.

server {
    listen 80;
    server_name domeniul_tau.com;
    root /var/www/laravel_app/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-XSS-Protection "1; mode=block";
    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 ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

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

Detalierea configurației:

• `listen 80;`: Îi spune lui Nginx să asculte conexiunile primite pe portul 80 (HTTP).
• `server_name domeniul_tau.com;`: Specifică la ce domeniu ar trebui să răspundă acest bloc de server.
• `root /var/www/laravel_app/public;`: Setează rădăcina documentului. Acest lucru este critic; toate cererile ar trebui să fie direcționate către directorul `public` al Laravel, niciodată la rădăcina proiectului.
• `add_header ...`: Aceste linii adaugă antete de securitate HTTP pentru a ajuta la atenuarea atacurilor precum clickjacking și cross-site scripting (XSS).
• `location / { ... }`: Acesta este blocul de locație principal. Directiva `try_files` este cheia rutării Laravel. Îi spune lui Nginx să caute mai întâi un fișier care se potrivește cu URI-ul cererii, apoi un director. Dacă niciunul nu există, pasează cererea la `index.php`, permițând routerului Laravel să o gestioneze.
• `location ~ \.php$ { ... }`: Acest bloc gestionează toate cererile care se termină în `.php`. Pasează cererea procesului PHP-FPM printr-un socket Unix pentru execuție.
• `location ~ /\.(?!well-known).*`: Aceasta este o regulă de securitate care interzice accesul public la toate fișierele ascunse (cum ar fi `.env`), cu excepția directorului `.well-known` utilizat de Let's Encrypt pentru validarea domeniului.

Acum, activați noua configurație creând o legătură simbolică de la `sites-available` la `sites-enabled`. Apoi, rulați un test de sintaxă pentru a vă asigura că nu există erori.

sudo ln -s /etc/nginx/sites-available/laravel_app /etc/nginx/sites-enabled/
sudo nginx -t

Dacă testul returnează "syntax is ok", puteți reîncărca Nginx în siguranță pentru a aplica toate modificările.

sudo systemctl reload nginx

Pasul 5: Securizarea aplicației cu un certificat SSL Let's Encrypt

În web-ul modern, servirea aplicației dvs. printr-o conexiune HTTP necriptată este inacceptabilă. Expune datele utilizatorilor și dăunează încrederii. Vom folosi Certbot și Let's Encrypt pentru a obține și instala un certificat SSL gratuit și de încredere, activând HTTPS.

Mai întâi, instalați Certbot și plugin-ul său pentru Nginx:

sudo apt install certbot python3-certbot-nginx

Acum, rulați Certbot, specificând plugin-ul Nginx și domeniul pe care doriți să îl securizați. Certbot va citi automat fișierul dvs. de configurare Nginx pentru a găsi blocul de server corect.

sudo certbot --nginx -d domeniul_tau.com

Certbot vă va ghida printr-un proces interactiv. Vi se va cere să furnizați o adresă de e-mail pentru notificări de reînnoire și să fiți de acord cu termenii serviciului. Când vi se cere să redirecționați traficul HTTP către HTTPS, ar trebui să alegeți întotdeauna opțiunea "Redirect". Acest lucru asigură că toți vizitatorii folosesc o conexiune sigură. La finalizare, Certbot va fi modificat automat configurația Nginx pentru a activa SSL și va configura un cronometru systemd sau un job cron pentru a reînnoi automat certificatul înainte de a expira.

Pasul 6: Optimizări finale pentru producție

Înainte de a servi trafic, ar trebui să rulați comenzile de optimizare încorporate ale Laravel. La fiecare cerere, Laravel trebuie în mod normal să citească mai multe fișiere de configurare și să parseze fișierele de rutare pentru a-și da seama cum să răspundă. Comenzile de optimizare compilează toate aceste fișiere în câteva fișiere unice, în cache, ceea ce reduce dramatic supraîncărcarea framework-ului și îmbunătățește timpii de răspuns.

cd /var/www/laravel_app
php artisan config:cache
php artisan route:cache
php artisan view:cache

De asemenea, este înțelept să ajustați managerul de procese PHP-FPM în funcție de resursele serverului. Setările implicite sunt adesea prea conservatoare. Editați fișierul de configurare a pool-ului `www.conf`:

sudo nano /etc/php/8.3/fpm/pool.d/www.conf

Pentru un server cu 2GB de RAM, ajustarea setărilor `pm` (process manager) la `dynamic` și creșterea numărului de procese copil poate oferi un echilibru bun între utilizarea memoriei și capacitatea de gestionare a cererilor. Următorul este un punct de plecare rezonabil:

pm = dynamic
pm.max_children = 25
pm.start_servers = 8
pm.min_spare_servers = 5
pm.max_spare_servers = 15

După salvarea modificărilor, reporniți serviciul PHP-FPM pentru ca acestea să intre în vigoare.

sudo systemctl restart php8.3-fpm

În acest moment, aplicația dvs. Laravel ar trebui să fie live și accesibilă la domeniul dvs. Ați implementat cu succes un mediu de aplicație sigur, performant și scalabil.

Depanarea erorilor comune de implementare

Implementările pot fi complexe, iar greșelile mici de scriere sau configurările greșite pot duce la erori. Iată soluții pentru cele mai comune probleme întâlnite în timpul acestui proces.

502 Bad Gateway

Aceasta este cea mai frecventă eroare. Semnifică faptul că Nginx rulează, dar nu poate obține un răspuns de la backend-ul PHP-FPM. Cele mai comune cauze sunt:

• Serviciul `php8.3-fpm` nu rulează. Verificați starea acestuia cu `systemctl status php8.3-fpm`.
• Calea socket-ului din configurația Nginx (`fastcgi_pass`) nu se potrivește cu fișierul socket real creat de PHP-FPM. Verificați calea în `/var/run/php/`.

Erori de permisiune refuzată / Erori la scrierea în `laravel.log`

Dacă aplicația dvs. se încarcă, dar vedeți erori în fișierele de log (sau fișierul de log nu poate fi creat), este aproape sigur o problemă de permisiuni. Laravel, rulând ca utilizator `www-data`, nu are permisiunea de a scrie în directoarele `storage` sau `bootstrap/cache`. Rulați din nou comenzile `chown` și `chmod` de la Pasul 4 pentru a remedia acest lucru.

404 Not Found pe toate rutele, cu excepția paginii de pornire

Acest simptom clasic indică faptul că Nginx nu pasează corect cererile pentru sub-pagini către routerul Laravel. Problema constă în directiva `try_files` din blocul `location /` al configurației Nginx. Asigurați-vă că este scrisă exact ca `try_files $uri $uri/ /index.php?$query_string;`. Acest lucru îi spune lui Nginx să transmită orice URI care nu corespunde unui fișier fizic sau unui director către controlerul frontal al Laravel.