Docker Compose для локальной разработки: рабочая схема

Локальная среда, которая не спорит с вашим компьютером

Для проекта на Vite, Node.js 22 и PostgreSQL 16 можно собрать среду разработки на Compose без ручной установки Node и базы на хосте. Исходники будут обновляться сразу после сохранения, зависимости останутся внутри контейнера, а данные PostgreSQL не исчезнут после остановки. Ниже — конфигурация для Docker Compose v2 и существующего Vite-проекта с файлом package-lock.json.

Понадобятся Docker Desktop или Docker Engine с плагином Compose v2, каталог проекта и права запускать Docker. В проекте должны быть скрипт dev и зафиксированные npm-зависимости. Создайте в корне файл .env и добавьте в него POSTGRES_PASSWORD=YOUR_DB_PASSWORD. Это заглушка: замените её локальным значением и не добавляйте файл с паролем в репозиторий.

Конфигурация: исходники на хосте, сервисы в контейнерах

Создайте в корне compose.yaml. В примере Vite слушает стандартный порт 5173, а приложение получает адрес базы через отдельные переменные. Само приложение должно читать эти переменные; если сейчас оно ждёт строку подключения, настройте её в коде проекта отдельно.

services:
  app:
    image: node:22-bookworm-slim
    working_dir: /workspace
    command: sh -c "npm ci && npm run dev -- --host 0.0.0.0"
    ports:
      - "127.0.0.1:5173:5173"
    volumes:
      - .:/workspace
      - node_modules:/workspace/node_modules
    environment:
      DB_HOST: db
      DB_PORT: "5432"
      DB_NAME: app
      DB_USER: app
      DB_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  node_modules:
  postgres_data:

Поле version здесь намеренно отсутствует: актуальный Compose использует Compose Specification, и это поле больше не требуется. Зафиксированные основные версии образов упрощают повтор запуска, но не закрепляют конкретный патч-релиз. Если команде нужна полная воспроизводимость, отдельно согласуйте и зафиксируйте версии образов по digest.

Почему здесь три разных вида хранения

Bind mount* .:/workspace показывает контейнеру файлы проекта с компьютера. Поэтому правка исходника видна сразу, без пересборки образа. Отдельный именованный том для node_modules не даёт содержимому этой папки с хоста скрыть установленные в контейнере зависимости. Ещё один том хранит каталог данных PostgreSQL независимо от жизненного цикла контейнера.

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

Запуск и проверка

1. Проверьте конфигурацию. Выполните docker compose config в корне проекта. Если Compose сообщает, что POSTGRES_PASSWORD не задан, проверьте наличие .env рядом с compose.yaml. Успешная проверка выводит итоговую конфигурацию без сообщения об ошибке.
2. Поднимите сервисы. Запустите docker compose up. Первый старт скачает образы и выполнит npm ci, поэтому займёт дольше последующих. В логах приложения должна появиться информация о запуске Vite; у базы — сообщение о готовности принимать подключения.
3. Откройте приложение. Перейдите на http://localhost:5173. Страница должна загрузиться, а изменение исходного файла — отобразиться после обновления или через механизм HMR Vite.
4. Проверьте соединение с базой. Из приложения подключайтесь к хосту db и порту 5432. Если используете клиент базы данных на компьютере, подключайтесь к localhost:5432. В первом случае имя db — адрес сервиса во внутренней сети Compose, а не имя, которое знает ваш хост.

Остановить сервисы можно сочетанием Ctrl+C, затем выполните docker compose down. Эта команда удалит контейнеры и сеть, но оставит именованные тома. Для нового запуска используйте docker compose up.

Что чаще всего ломается

• Vite запущен, но браузер не открывает страницу. Проверьте, что в команде есть --host 0.0.0.0. Без этого сервер может слушать только loopback-интерфейс внутри контейнера, куда проброс порта с хоста не попадёт.
• В контейнере не находится пакет, который есть на хосте. Это часто происходит, когда зависимости установили только на компьютере, а том node_modules пуст. Перезапустите сервис: команда в конфигурации выполнит npm ci по lock-файлу внутри контейнера.
• Приложение не подключается к PostgreSQL. Внутри Compose используйте хост db, не localhost: последний указывает на сам контейнер приложения. Убедитесь также, что приложение ожидает здоровье базы или повторяет попытки подключения.
• Порт уже занят. Если Docker не может опубликовать 5173 или 5432, остановите другой сервис на этом порту либо измените левую часть записи в ports. Например, для базы можно опубликовать другой порт хоста, оставив внутренний порт 5432 без изменений.
• После правки зависимостей поведение не изменилось. Пересоздание контейнера не всегда означает сброс именованного тома. Перезапустите установку зависимостей через docker compose run --rm app npm ci, затем поднимите сервисы снова.

Термин. Именованный том — хранилище, которым управляет Docker. В отличие от bind mount, он не привязан к конкретной папке проекта на хосте; поэтому зависимости контейнера и данные базы не смешиваются с файлами разработчика.

Границы этой схемы

depends_on с условием service_healthy помогает не запускать приложение раньше, чем база станет готовой при старте Compose. Но это не гарантирует, что база никогда не перезапустится позже. Клиент приложения должен корректно обрабатывать временный отказ соединения. Также пароль в .env годится для локальной среды, но не заменяет секрет-хранилище и политику доступа в продакшене.

На Linux bind mount обычно работает напрямую. В Docker Desktop на macOS и Windows обмен файлами проходит через дополнительный слой, поэтому большие проекты могут обновляться медленнее. Если Vite не замечает изменения файлов, сначала проверьте настройки наблюдения за файлами в документации используемой версии Vite и Docker Desktop: универсальный параметр для всех ОС и версий здесь обещать нельзя.

Что делать дальше

Сначала проверьте, что команда может поднять проект с нуля: клонировать репозиторий, создать локальный .env и выполнить docker compose up. Затем договоритесь, какие данные должны переживать перезапуск, и отдельно проверьте сценарий сброса базы. В рабочем процессе полезно наблюдать за временем запуска, ошибками подключения и размером томов — так локальная среда не превратится в ещё один источник сюрпризов.