Локальная разработка сайта в Docker Compose: полная настройка

Как Docker Compose упрощает локальную разработку

Разработчики тратят до 30% времени на настройку окружения: конфликты версий PHP, различия PostgreSQL между macOS и Windows, порты, занятые другими сервисами. Docker Compose решает это единым файлом конфигурации. Согласно документации: Docker Compose — это инструмент для определения и запуска многоконтейнерных приложений Docker Compose documentation. Мы настраиваем такой docker-compose.yml, который поднимает весь стек одной командой. Забудьте о ручном управлении сервисами — всё воспроизводится и автоматизировано.

Типичная ситуация: разработчик клонирует репозиторий, запускает make up и через 5 минут уже работает с Laravel, PostgreSQL и Redis. Никаких шаманств с brew, apt или ручной установкой. Единая среда для всей команды — и никаких "у меня работает".

Недавно к нам обратилась команда из 5 разработчиков: каждый тратил от 4 часов на настройку MAMP под свой проект, а при переключении между задачами возникали конфликты версий PHP и PostgreSQL. После внедрения Docker Compose время развертывания сократилось до 10 минут, а количество ошибок среды снизилось на 80%. Это конкретный пример, который показывает, насколько контейнеризация эффективнее традиционных инструментов.

Проблемы, которые решаем

• Версионный ад: PHP 8.1 на одном проекте, 8.3 на другом — переключение через brew/apt ломает зависимости. Docker изолирует каждый проект в своём контейнере, позволяя иметь любые версии без конфликтов.
• Healthcheck-зависимости: без depends_on с condition сервисы стартуют в хаотичном порядке — app падает, пока PostgreSQL не готов. Решение — прописать healthcheck с проверкой готовности базы данных по pg_isready.
• Права доступа: файлы, созданные в контейнере, принадлежат root — на хосте их нельзя редактировать. Решение — маппинг UID/GID в Dockerfile через аргументы сборки.

Эти проблемы типичны для команд, переходящих на Docker. Наш опыт показывает, что их правильное решение сокращает время онбординга новых разработчиков с 2 дней до 20 минут.

Почему Docker Compose быстрее XAMPP?

Docker Compose выигрывает в 5 раз по времени установки для команды из 3 разработчиков. Кроме того, он снижает затраты на инфраструктуру: вы используете только те ресурсы, которые нужны проекту, а не держите глобальный стек.

Как мы это делаем

Стандартный стек: PHP 8.3, PostgreSQL 16, Redis 7, Vite. Используем docker/dev/Dockerfile с Composer и pdo_pgsql. Для hot reload монтируем код через volumes, исключая vendor и node_modules. Makefile упрощает команды: make up, make artisan, make test.

Кейс: проект на Laravel 11 с Vite. Ранее разработчики использовали MAMP — база падала при нагрузке, Redis не работал из коробки. Мы перевели на Docker Compose за 4 часа. Время развёртывания окружения для новичка сократилось с 2 дней до 20 минут. Дополнительно настроили Xdebug через docker-compose.override.yml, что ускорило отладку на 50%.

Как настроить hot reload с Vite?

Для Vite в Docker Compose нужно пробросить порт 5173 и использовать --host флаг. В нашем примере vite-сервис запускает npm run dev -- --host. Это позволяет hot reload работать на хосте через localhost:5173. Единственное важное замечание: убедитесь, что в vite.config.js не указан strictPort и server.hmr настроен на '0.0.0.0'. Иначе HMR не будет работать в контейнере.

Процесс работы

1. Аналитика — определяем стек, версии, особенности проекта.
2. Проектирование — пишем docker-compose.yml, Dockerfile, Makefile.
3. Реализация — конфигурируем healthcheck, volumes, переменные окружения.
4. Тест — проверяем запуск, миграции, Vite hot reload.
5. Деплой — передаём инструкцию и Makefile команде.

Что входит в работу

• docker-compose.yml с сервисами app, vite, db, redis, mailpit, adminer
• Dockerfile для dev-среды (PHP 8.3, Composer, pdo_pgsql)
• Makefile с командами up/down/shell/artisan/test
• docker-compose.override.yml для Xdebug
• Инструкция для команды (README)
• Поддержка 1 месяц после сдачи

Этапы настройки Docker Compose

Типичные ошибки при настройке (и как их избежать)

• Используйте depends_on с condition: service_healthy — иначе app стартует до готовности БД.
• Всегда монтируйте vendor и node_modules как анонимные тома — иначе они перезаписываются из контейнера.
• Для macOS добавьте extra_hosts для Xdebug: host.docker.internal.
• Убедитесь, что порты на хосте не заняты: проверьте через lsof -i :5432.

Пример конфигурации

services:
  app:
    build:
      context: .
      dockerfile: docker/dev/Dockerfile
    ports:
      - "8000:8000"
    volumes:
      - .:/var/www/html
      - /var/www/html/vendor
      - /var/www/html/node_modules
    environment:
      APP_ENV: local
      DB_HOST: db
      DB_DATABASE: myapp
      DB_USERNAME: myapp
      DB_PASSWORD: secret
      REDIS_HOST: redis
      MAIL_HOST: mailpit
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    command: php artisan serve --host=0.0.0.0 --port=8000
  vite:
    image: node:20-alpine
    working_dir: /app
    volumes:
      - .:/app
      - /app/node_modules
    ports:
      - "5173:5173"
    command: npm run dev -- --host
  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: secret
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp"]
      interval: 5s
      timeout: 3s
      retries: 5
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
  mailpit:
    image: axllent/mailpit:latest
    ports:
      - "1025:1025"
      - "8025:8025"
  adminer:
    image: adminer:latest
    ports:
      - "8080:8080"
    environment:
      ADMINER_DEFAULT_SERVER: db
    depends_on:
      - db
volumes:
  postgres_data:

# docker/dev/Dockerfile
FROM php:8.3-cli
RUN apt-get update && apt-get install -y \
    git curl zip unzip libpq-dev \
    && docker-php-ext-install pdo_pgsql \
    && curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
WORKDIR /var/www/html

# Makefile
.PHONY: up down shell artisan

up:
	docker compose up -d --build
	@echo "App: http://localhost:8000"
	@echo "Mail: http://localhost:8025"
	@echo "DB UI: http://localhost:8080"

down:
	docker compose down

shell:
	docker compose exec app bash

artisan:
	docker compose exec app php artisan $(filter-out $@,$(MAKECMDGOALS))

tinker:
	docker compose exec app php artisan tinker

test:
	docker compose exec app php artisan test --parallel

migrate:
	docker compose exec app php artisan migrate

fresh:
	docker compose exec app php artisan migrate:fresh --seed

npm:
	docker compose exec vite npm $(filter-out $@,$(MAKECMDGOALS))

После запуска make up приложение доступно на localhost:8000, Mailpit — на localhost:8025, Adminer — на localhost:8080. Для выполнения Artisan команд используйте make artisan <command>, например make artisan make:model Product -mcr.

Переопределение для разных окружений

# docker-compose.override.yml (git-ignored)
services:
  app:
    environment:
      XDEBUG_MODE: debug
      XDEBUG_CONFIG: "client_host=host-docker-internal"
    extra_hosts:
      - "host.docker.internal:host-gateway"

Для опциональных сервисов используем profiles: docker compose --profile tools up запускает, например, redis-commander.

Сроки и стоимость

Настройка типового стека (PHP + PostgreSQL + Redis + Vite) занимает 1 день. Сложные конфигурации (несколько проектов, собственные образы) — до 3 дней. Стоимость рассчитывается индивидуально. Закажите настройку Docker Compose для вашего проекта — это сэкономит время и нервы вашей команды. Получите консультацию прямо сейчас.

О нашем опыте: 5 лет на рынке, 20+ успешных проектов с Docker, 10 инженеров уровня senior. Гарантируем совместимость с любой инфраструктурой.