Symfony за замовчуванням розрахований на структуру, де точка входу лежить у каталозі public/, а все інше — вихідний код, кеш, логи — недоступне вебсерверу напряму. Помилки в конфігу Nginx або в правах на каталоги — найчастіша причина білого екрана і 502 після першого деплою.

Структура каталогів проєкту

Вебсервер має дивитися строго в public/, а не в корінь проєкту — інакше через браузер будуть доступні .env, composer.json і вміст var/. Каталог var/cache і var/log має бути доступний на запис користувачу PHP-FPM, а vendor/ збирається через Composer уже на сервері або заливається разом із релізом. Про сам менеджер залежностей — у статті про встановлення і налаштування Composer.

Конфіг Nginx для Symfony

Ключова частина — правило try_files, яке віддає всі запити, крім реальних файлів, через index.php:

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

    location / {
        try_files $uri /index.php$is_args$args;
    }

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        internal;
    }

    location ~ \.php$ {
        return 404;
    }
}

Рядок internal; забороняє відкривати /index.php напряму за URL — лише через try_files. Налаштування самого пулу PHP-FPM, включно з лімітами воркерів, розібрані у статті про пули і оптимізацію PHP-FPM.

Права на каталоги var/cache і var/log

Symfony пише кеш контейнера сервісів, скомпільовані шаблони і логи у var/. Якщо користувач PHP-FPM не може писати в ці теки, застосунок падає з помилкою доступу вже на першому запиті після деплою.

Каталог	Власник	Права	Призначення
var/cache	www-data	775	кеш контейнера і шаблонів
var/log	www-data	775	логи застосунку
public/uploads	www-data	775	файли, завантажені відвідувачами
config, src	деплой-користувач	755	вихідний код, лише читання для веба

Порядок деплою релізу

Оновлення коду без прогрівання кешу веде до того, що перший гість після релізу чекає компіляцію контейнера сервісів кілька секунд. Порядок команд на сервері такий:

composer install --no-dev --optimize-autoloader — ставить залежності без dev-пакетів і будує оптимізований автозавантажувач.
php bin/console cache:clear --env=prod — очищає старий кеш перед перезбіркою.
php bin/console cache:warmup --env=prod — прогріває кеш заздалегідь, до приходу першого запиту.
php bin/console doctrine:migrations:migrate --no-interaction — застосовує міграції бази даних, якщо вони є в релізі.

composer install --no-dev --optimize-autoloader
php bin/console cache:clear --env=prod
php bin/console cache:warmup --env=prod
php bin/console doctrine:migrations:migrate --no-interaction

Типові помилки 502 і білий екран

Після першого деплою найчастіше трапляються такі проблеми:

502 Bad Gateway зазвичай означає, що Nginx не може достукатися до сокета PHP-FPM — або шлях у fastcgi_pass не збігається з реальним сокетом, або сам пул впав через брак пам'яті. Білий екран без тексту помилки означає, що APP_DEBUG=0 і Symfony ховає деталі — тимчасово увімкніть перегляд через var/log/prod.log, а не через браузер. Автозавантаження PSR-4 повʼязане з оптимізацією автозавантажувача Composer — деталі у статті про оптимізацію Composer autoloader.

Чек-лист перед запуском у проді

Перед тим як перемкнути домен на новий реліз, пройдіться за списком:

Перевірте, що APP_ENV=prod і APP_DEBUG=0 у файлі .env.local на сервері, а не лише локально.
Переконайтеся, що OPcache увімкнено і налаштовано на інвалідацію за часом, а не на кожен запит — конфігурацію описано в статті про налаштування OPcache.
Прожене smoke-тест ключових сторінок одразу після деплою, до того як на сайт зайдуть реальні відвідувачі.

Symfony на VPS: деплой, конфіг Nginx і права на каталоги