Skip to main content

Гайд по работе с Docker в Lowcode Platform

Этот документ объясняет, как устроены Docker-файлы, как запускать dev-окружение и тестовый контур, как выполнять очистку, откуда Docker берёт конфигурацию, и как всё это интегрировано в CI/CD.

1. Общая архитектура Docker

Lowcode Platform использует Docker в двух сценариях:

  1. Dev-окружение для локальной разработки (docker-compose.dev.yml).
  2. Test-окружение для e2e тестов (docker-compose.test.yml).

Базовый образ API собирается через infra/docker/Dockerfile.api.

Схема:

Dockerfile.api
  ├── stage deps   → ставит node_modules
  ├── stage dev    → копирует repo и готовит API
  └── stage prod   → финальный runtime

Dev/test compose-файлы используют stage dev, который содержит весь монорепозиторий + node_modules.

2. Dockerfile.api — устройство

Файл расположен по адресу:

infra/docker/Dockerfile.api

Он содержит три стадии:

2.1. deps​

  • ставит Node.js
  • включает corepack (для pnpm)
  • устанавливает системные пакеты
  • копирует package.json и pnpm-lock.yaml
  • устанавливает зависимости командой pnpm install --frozen-lockfile

2.2. dev​

  • копирует весь репозиторий внутрь контейнера
  • генерирует Prisma Client (prisma generate)

Эта стадия используется dev/test окружениями.

2.3. prod​

  • минимальный образ
  • копирует dist и node_modules
  • запускает приложение

Этот stage используется CI/CD в будущем для deployment.

3. Dev окружение (docker-compose.dev.yml)

Файл:

infra/docker/docker-compose.dev.yml

Запускает:

✔ db — PostgreSQL 16​

  • хранит данные в volume docker_docker_pgdata
  • не пробрасывает порт наружу, чтобы БД была только внутри Docker Network

✔ api-dev​

  • собирает контейнер из Dockerfile.api (stage dev)
  • запускает миграции
  • запускает API в режиме разработки (pnpm dev)
  • пробрасывает порт 3000:3000

✔ Health-check​

Fastify не предоставляет /health по умолчанию, поэтому в dev окружении используется:

wget -qO- http://localhost:3000/projects

Если API отвечает — контейнер считается healthy.

3.1. Запуск dev окружения​

docker compose -f infra/docker/docker-compose.dev.yml up --build

3.2. Остановка​

docker compose -f infra/docker/docker-compose.dev.yml down

3.3. Полная очистка DB​

docker compose -f infra/docker/docker-compose.dev.yml down -v

Это удалит volume docker_docker_pgdata.

4. Test окружение (docker-compose.test.yml)

Используется локально и в CI.

Файл:

infra/docker/docker-compose.test.yml

Запускает:

✔ db — БД для e2e тестов​

С параметрами:

POSTGRES_USER=lowcode_user
POSTGRES_PASSWORD=lowcode_password
POSTGRES_DB=lowcode_test

✔ api-test​

Выполняет полный тестовый цикл:

1. prisma migrate dev
2. pnpm test
3. pnpm test:e2e

Контейнер завершается автоматически, а docker compose остаётся жить из-за Postgres.

4.1. Быстрый запуск тестов локально​

Поднять только БД​

docker compose -f infra/docker/docker-compose.test.yml up -d db

Запустить тесты​

docker compose -f infra/docker/docker-compose.test.yml run --rm api-test

Очистить всё​

docker compose -f infra/docker/docker-compose.test.yml down -v

5. Работа .env файлов

Prisma в контейнере загружает переменные среды из:

  1. .env, если он внутри репозитория
  2. переменные environment: в docker-compose
  3. переменные, переданные при запуске (-e FOO=bar)

В dev/test окружениях приоритет такой:

docker-compose → .env → default значения

Например, dev окружение задаёт:

DATABASE_URL=postgresql://lowcode:lowcode@db:5432/lowcode

А тестовое:

DATABASE_URL=postgres://lowcode_user:lowcode_password@db:5432/lowcode_test

6. Подключение к базе данных внутри контейнера

База данных не пробрасывается наружу, поэтому подключение возможно только изнутри Docker Network.

Чтобы войти в БД dev окружения:

docker exec -it lowcode-postgres psql -U lowcode lowcode

Для test окружения:

docker exec -it lowcode-postgres-test psql -U lowcode_user lowcode_test

Миграции применяются автоматически при старте API.

7. Интеграция Docker в CI/CD

GitHub Actions запускают тесты через:

docker compose -f infra/docker/docker-compose.test.yml up --build --abort-on-container-exit --exit-code-from api-test

Пояснение флагов:

  • --abort-on-container-exit → когда api-test завершился, Docker гасит остальные контейнеры
  • --exit-code-from api-test → код завершения из e2e тестов = код завершения CI job

То есть:

  • если тесты зелёные → CI проходит
  • если e2e упали → CI красный

В будущем​

Stage prod из Dockerfile будет использоваться для деплоймента:

  • публикации Docker-образов в container registry
  • развёртывания в NestJS runtime-хосте

8. Какие требования предъявляются к Docker-файлам

  1. Детерминированная сборка — зависит только от package.json, pnpm-lock.yaml и контента монорепы.

  2. Минимальный набор зависимостей в prod-образе.

  3. Возможность сборки всего приложения или отдельных пакетов.

  4. Совместимость с CI/CD, включая:

    • генерацию Prisma Client
    • запуск миграций
    • запуск unit/e2e тестов

  5. Health-checks для dev/prod контейнеров.

  6. Быстрая сборка (stage deps кешируется).

9. Частые команды Docker (чеклист)

Пересобрать dev окружение​

docker compose -f infra/docker/docker-compose.dev.yml up --build

Запустить e2e тесты в чистом окружении​

docker compose -f infra/docker/docker-compose.test.yml down -v
docker compose -f infra/docker/docker-compose.test.yml up --build

Удалить ВСЕ контейнеры и volume в проекте​

docker compose -f infra/docker/docker-compose.dev.yml down -v
docker compose -f infra/docker/docker-compose.test.yml down -v

Посмотреть контейнеры​

docker ps -a

Удалить один контейнер​

docker rm <na