Laravel на VPS: встановлення, Nginx та деплой

Вимоги для Laravel на VPS

Laravel 11.x потребує PHP 8.2+, розширення: BCMath, Ctype, cURL, DOM, Fileinfo, JSON, Mbstring, OpenSSL, PCRE, PDO, Tokenizer, XML. Також потрібні Composer, Node.js (для npm) і база даних (MySQL/MariaDB або PostgreSQL).

Встановлення залежностей

sudo apt update && sudo apt install -y php8.2-fpm php8.2-cli php8.2-mysql \
    php8.2-mbstring php8.2-xml php8.2-curl php8.2-zip php8.2-bcmath \
    php8.2-intl php8.2-redis nginx mysql-server git unzip

# Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

Встановлення Laravel

cd /var/www
composer create-project laravel/laravel myapp
cd myapp
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data .

Налаштування .env

cp .env.example .env
php artisan key:generate

nano .env

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

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=myapp_db
DB_USERNAME=myapp_user
DB_PASSWORD=StrongPassword123

Nginx vhost для Laravel

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

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/myapp/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.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

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

sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Міграції та збірка

php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache
npm install && npm run build

Supervisor для черг Laravel

sudo apt install supervisor
sudo nano /etc/supervisor/conf.d/laravel-worker.conf

[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/myapp/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/log/laravel-worker.log

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*

Cron для Laravel Scheduler

sudo crontab -u www-data -e
# Додати:
* * * * * cd /var/www/myapp && php artisan schedule:run >> /dev/null 2>&1

Реальні помилки після деплою Laravel

419 Page Expired

Виникає при розсинхронізації CSRF-токена із сесією: найчастіше — через неправильний SESSION_DOMAIN у .env за зворотним проксі, або тому що APP_KEY взагалі не згенерований після копіювання проєкту на новий сервер.

Не вдається відкрити storage/logs/laravel.log

The stream or file "/var/www/myapp/storage/logs/laravel.log" could not be opened in append mode: Failed to open stream: Permission denied

PHP-FPM працює від імені www-data, а папку storage після деплою часто лишають із правами користувача, з-під якого виконувався git pull чи composer install. Права потрібно виставляти після кожного оновлення коду, а не один раз під час першого встановлення.

Порожній білий екран замість сторінки

За APP_DEBUG=false Laravel показує користувачу універсальну сторінку «500 | Server Error» без жодної технічної деталі — це правильна поведінка для прода, але реальну причину потрібно шукати не на екрані, а в storage/logs/laravel.log.

Коли ця схема не підходить

• Файлові драйвери сесій і кешу за замовчуванням зберігають дані на диску одного сервера — під час масштабування на кілька інстансів за балансувальником потрібен Redis чи база даних як спільне сховище.
• numprocs=2 у Supervisor розрахований на легку чергу — для важких завдань (розсилки, генерація звітів) двох воркерів швидко стає мало, черга починає накопичуватися без попереджень у логах.
• Запуск php artisan queue:work напряму, без Supervisor, обриває всі завдання, що перебувають в обробці, під час кожного деплою — Supervisor із stopwaitsecs дає воркеру час коректно завершити поточне завдання.

Перевірка результату

# Конфігурація і оточення застосунку читаються коректно
php artisan about

# Воркери черг реально працюють
sudo supervisorctl status

# Живий хвіст логу застосунку під час тестового запиту
tail -f storage/logs/laravel.log

php artisan about в одній таблиці показує версію PHP, оточення, статус кешів конфігурації та маршрутів — швидше, ніж збирати ту саму інформацію вручну з десятка файлів. Для черг поверх Redis дивіться окремий розбір налаштування сесій і драйверів кешу.