Локальное окружение обычно собирается по памяти: у одного PHP 8.2, у другого 8.3, у третьего MySQL 5.7 вместо 8.0. Ошибки воспроизводятся через раз. Compose фиксирует версии и команды в файлах, которые лежат в репозитории.

Состав

  • php-fpm — приложение и расширения;
  • nginx — веб-сервер и статика;
  • mysql — база;
  • redis — кэш и очереди, если используются.

Отдельный контейнер для CLI не нужен: docker compose exec php php artisan ... выполняет команды в том же образе.

Dockerfile

FROM php:8.3-fpm-alpine

RUN apk add --no-cache icu-dev oniguruma-dev libzip-dev \
    && docker-php-ext-install intl pdo_mysql mbstring zip opcache

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

WORKDIR /var/www/html
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-scripts --no-interaction

COPY . .

USER www-data

Порядок слоёв важен: сначала зависимости, потом код. Тогда правка файла не пересобирает Composer-слой. Для разработки --no-dev уберите, чтобы были доступны тесты и отладочные пакеты.

compose.yaml

services:
  php:
    build: .
    volumes:
      - .:/var/www/html
    environment:
      DB_HOST: mysql
      REDIS_HOST: redis

  nginx:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
    volumes:
      - .:/var/www/html
      - ./docker/nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - php

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: app
      MYSQL_ROOT_PASSWORD: secret
    volumes:
      - db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-psecret"]
      interval: 10s
      retries: 5

  redis:
    image: redis:7-alpine

volumes:
  db:

Имя хоста базы внутри сети — mysql, а не 127.0.0.1: в контейнере localhost указывает на сам контейнер. Порт наружу нужен только если вы подключаетесь клиентом с хоста.

nginx

server {
    listen 80;
    root /var/www/html/public;
    index index.php;

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

    location ~ \.php$ {
        fastcgi_pass php:9000;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}

fastcgi_pass php:9000 использует имя сервиса. Опечатка здесь даёт 502 Bad Gateway, а не ошибку PHP.

Первый запуск

docker compose up -d --build
docker compose exec php composer install
docker compose exec php php artisan migrate
docker compose exec php php artisan test

Если база ещё поднимается, миграция упадёт. Дождитесь healthcheck: docker compose ps покажет статус. В CI это решается ожиданием, вручную — повторным запуском.

Права и производительность

На Linux файлы, созданные контейнером, могут принадлежать root. Запускайте php-fpm от www-data и следите за владельцем storage и bootstrap/cache. На macOS нативные тома медленные; помогает cached или виртуальная файловая система Docker.

Для production не монтируйте код томом: он должен быть внутри образа. Включите opcache с validate_timestamps=0 и пересобирайте образ при каждом релизе.

Что не класть в репозиторий

  • .env с реальными паролями;
  • дампы базы и логи;
  • vendor и node_modules;
  • ключи и сертификаты.

Пароли в compose-файле допустимы только для локального окружения. Для сервера — переменные окружения или секреты оркестратора.

Для отладки добавьте Xdebug отдельным профилем и не включайте его по умолчанию: замедление в разы, а на слабом ноутбуке — таймауты. Почту локально перехватывайте Mailpit или аналогом, чтобы тестовые письма не уходили реальным адресатам.

Cron в контейнере не запускается сам: либо отдельный сервис с schedule:run, либо cron на хосте. Не смешивайте его с php-fpm, иначе долгие задачи заблокируют обработку запросов.

Для CI полезна та же конфигурация: статья GitHub Actions для PHP. О скриптах запуска — надёжные bash-скрипты.

Зафиксируйте версии образов, а не используйте latest: иначе завтра сборка может отличаться от сегодняшней. Обновляйте осознанно и проверяйте тестами. И держите compose-файл в репозитории рядом с кодом — окружение должно быть воспроизводимым, а не «настроенным на моей машине».

Проверьте, что контейнеры поднимаются на чистой машине: удалите тома и соберите заново. Только так видны забытые зависимости и ручные шаги, которые остались за кадром. Автоматизируйте эту проверку в CI.

Для базы заранее продумайте, как делать дамп и восстанавливать его в контейнере: это первое, что понадобится при смене схемы или переезде.

Коротко

  • compose фиксирует версии PHP, базы и сервера;
  • php-fpm и nginx — разные контейнеры, связанные сетью;
  • зависимости ставьте до копирования кода;
  • healthcheck избавляет от гонок при старте;
  • production-образ не должен зависеть от томов с кодом.