К содержимому

CI CD на Jenkins: деплой Laravel и PHP-сайтов на VPS

Jenkins собирает проект и выкатывает его на сервер по одному нажатию: код, зависимости, сборка фронтенда, права, миграции и кэш.

Руководство Деплой 3 мин чтения

01Установите Jenkins и подготовьте пользователя деплоя

Jenkins в Ubuntu 24.04 ставят из его репозитория: нужен ключ и список пакетов. Служба запускается от пользователя jenkins, и все команды деплоя выполняются от него. Пользователь деплоя должен иметь доступ к каталогу сайта и SSH-ключ для приватного репозитория.

bash
sudo apt update
sudo apt install -y fontconfig openjdk-21-jre
sudo wget -O /usr/share/keyrings/jenkins-keyring.asc https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key
echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian-stable binary/" | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null
sudo apt update
sudo apt install -y jenkins
sudo systemctl enable --now jenkins

02Создайте каталог сайта и клонируйте код

Каталог /var/www/example.com создаёт пользователь, который деплоит, иначе git pull упадёт с error: cannot open .git/FETCH_HEAD: Permission denied. Приватный репозиторий клонируют по SSH-ключу этого пользователя, публичный ключ добавляют в GitHub как deploy key. Проверка доступа: ssh -T git@github.com.

bash
sudo mkdir -p /var/www/example.com
sudo chown $USER:www-data /var/www/example.com
git clone git@github.com:user/app.git /var/www/example.com
ssh -T git@github.com

03Установите зависимости и соберите фронтенд

composer install --no-dev --optimize-autoloader ставит только рабочие пакеты и готовит автозагрузчик. Если composer пишет Your requirements could not be resolved to an installable set of packages, в сообщении указано недостающее расширение, например ext-intl ставится пакетом php8.3-intl. Фронтенд собирают npm ci и npm run build. Обе команды и composer запускают без sudo, от владельца проекта.

bash
cd /var/www/example.com
composer install --no-dev --optimize-autoloader
npm ci
npm run build

04Выдайте права на storage и bootstrap/cache

Владелец файлов проекта это пользователь, который деплоит, а www-data пишет только в storage и bootstrap/cache через группу. Остальные файлы www-data только читает. Если сделать chown -R www-data:www-data на эти каталоги, composer install и php artisan optimize упадут с Permission denied.

bash
cd /var/www/example.com
sudo chown -R $USER:www-data storage bootstrap/cache
sudo chmod -R ug+rwX storage bootstrap/cache

05Примените миграции и соберите кэш

php artisan migrate --force применяет миграции без вопроса о подтверждении, флаг обязателен при APP_ENV=production. php artisan optimize кэширует конфиг, маршруты, события и шаблоны. После кэша конфига env() вне файлов config/ возвращает null, а правка .env действует только после нового php artisan optimize или php artisan config:clear. php artisan queue:restart перезапускает обработчиков очереди, чтобы они подхватили новый код.

bash
cd /var/www/example.com
php artisan migrate --force
php artisan optimize
php artisan queue:restart

06Настройте nginx и PHP-FPM

Для Laravel root в nginx смотрит в /var/www/example.com/public, поэтому .env и код вне public наружу не отдаются. PHP подключают через сниппет и сокет php8.3-fpm. Файл кладут в /etc/nginx/sites-available/ и включают симлинком в sites-enabled.

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

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
}

07Проверьте конфиг и перезагрузите службы

sudo nginx -t проверяет все файлы конфига, а sudo systemctl reload nginx применяет его без обрыва соединений. С ошибкой в конфиге nginx продолжает работать со старым. Конфиг FPM проверяет sudo php-fpm8.3 -t, затем службу перезагружают. С opcache.validate_timestamps=0 новый код подхватывается только после sudo systemctl reload php8.3-fpm.

bash
sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com
sudo nginx -t
sudo systemctl reload nginx
sudo php-fpm8.3 -t
sudo systemctl reload php8.3-fpm

08Проверьте, что сайт работает

Откройте http://example.com и убедитесь, что отдаётся страница, а не 500 или 502. Ошибки Laravel пишет в storage/logs/laravel.log, при APP_DEBUG=false в браузере видна только общая страница. Логи nginx лежат в /var/log/nginx/access.log и /var/log/nginx/error.log, если в конфиге сайта не заданы свои.

bash
curl -I http://example.com
tail -n 50 /var/www/example.com/storage/logs/laravel.log
sudo tail -n 50 /var/log/nginx/error.log

Частые ошибки

  • composer install или php artisan optimize падает с file_put_contents(/var/www/example.com/bootstrap/cache/packages.php): Failed to open stream: Permission denied.

    Каталог bootstrap/cache принадлежит www-data, а команду запускает владелец проекта. Верните группу: sudo chown -R $USER:www-data bootstrap/cache и sudo chmod -R ug+rwX bootstrap/cache.

  • Сайт отвечает 500, а в storage/logs/laravel.log запись The stream or file "/var/www/example.com/storage/logs/laravel.log" could not be opened in append mode: Failed to open stream: Permission denied.

    У www-data нет записи в storage. Выполните sudo chown -R $USER:www-data storage bootstrap/cache и sudo chmod -R ug+rwX storage bootstrap/cache.

  • git pull в задании Jenkins падает с git@github.com: Permission denied (publickey).

    У пользователя jenkins нет ключа, добавленного в GitHub. Сгенерируйте ключ для jenkins, добавьте публичную часть как deploy key и проверьте ssh -T git@github.com от этого пользователя.

  • После правки .env сайт работает со старыми настройками, а env() вне config/ возвращает null.

    Конфиг закэширован. Выполните php artisan optimize или php artisan config:clear и уберите вызовы env() из кода вне каталога config/.

Deploykin

Как это делается в Deploykin

В Deploykin сайт обновляется после пуша в GitHub: панель запускает deploy-скрипт с миграциями и кэшами, на тарифе Про без простоя. Каждый релиз остаётся в истории, откат делается в один клик.

7 дней бесплатно на тарифе Про, без привязки карты.

Вопросы и ответы

Зачем нужен CI CD на Jenkins для Laravel?

Jenkins выполняет один и тот же набор команд при каждом изменении кода: установку зависимостей, сборку фронтенда, миграции и кэширование. Это убирает ручные шаги и расхождение между серверами.

Почему миграции запускают с флагом --force?

При APP_ENV=production команда php artisan migrate ждёт подтверждения в консоли, а в задании Jenkins ответить некому. Флаг --force выполняет миграции без вопроса.

От какого пользователя запускать composer и artisan?

От владельца файлов проекта, без sudo. Запуск через sudo оставляет в bootstrap/cache файлы root, которые PHP-FPM не может перезаписать.

Как проверить, что деплой прошёл?

Запросите сайт через curl -I http://example.com и посмотрите код ответа. Затем проверьте storage/logs/laravel.log и /var/log/nginx/error.log на свежие ошибки.

Ещё по теме

Деплой Laravel на сервер: команды, конфиг и ошибки: все материалы темы

Мы используем cookies и сервис веб-аналитики «Яндекс Метрика» (включая Вебвизор) для улучшения работы сайта. Подробности — в политике конфиденциальности.