Локальное окружение обычно собирается по памяти: у одного 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-образ не должен зависеть от томов с кодом.