Provision
—— XP

Переменные и окружения

теория~6 минут+170 XP

Как держать один стек и на ноутбуке, и на сервере, не поддерживая два почти одинаковых файла, которые однажды разойдутся? На ноутбуке удобно видеть порт приложения и базы напрямую, на сервере наружу смотрит только прокси, зато нужны лимиты памяти. Каждое такое место называют окружением: ноутбук разработчика, учебный стенд, рабочий сервер. Описание у них общее, а детали разные.

Compose решает это двумя механизмами — подстановкой значений из .env и наложением файлов отличий поверх основного. Устроено как договор с приложениями: основной текст один для всех, а особые условия для конкретного клиента пишут отдельным листом, и никто не переписывает договор целиком ради одной строки. Этот приём понадобится и в разделе про CI/CD: конвейер проверит описание сервера командой config до выката.

Подстановка из .env

В описании пишут не значение, а имя переменной, а значение кладут в .env рядом. Ты уже пользовался простой формой ${ИМЯ}. Есть ещё две, и первая — со значением по умолчанию.

compose.yaml
    ports:
      - "127.0.0.1:${APP_PORT:-8012}:8000"

Запись :-8012 значит «если переменная не задана или пуста, взять 8012». Так в .env указывают только то, что отличается.

Обычная форма без :? опасна для важных значений. Пустой ${APP_IMAGE} превращается в пустую строку, Compose печатает предупреждение, которое теряется в выводе, а дальше идёт загадочная ошибка invalid reference format. С паролем не лучше: образ PostgreSQL с пустым паролем не стартует вовсе, и причину ты увидишь только в журнале базы, а не в описании, где она на самом деле. Поэтому важные значения помечают второй формой, ${ИМЯ:?сообщение}: без значения Compose прервёт запуск сразу, со словами, которые ты сам написал. В практике этого раздела так будет помечен образ сервера.

Четыре источника значений по убыванию приоритета: переменные оболочки, файл по флагу --env-file, файл .env рядом и значение по умолчанию в подстановке. Ниже пояснение про раздел environment.
Переменная, заданная в оболочке, перекрывает .env. Раздел environment — другое: он задаёт переменные внутри контейнера.

Значения подставляются, а различия в самой структуре — порты, тома, лимиты — выносят в отдельные файлы.

Файлы отличий

Рядом с основным compose.yaml кладут файлы, которые накладываются поверх него. Принято два. compose.override.yaml — для разработки: Compose подхватывает его сам, если он лежит рядом. compose.prod.yaml — для сервера: его указывают явно.

Сложение двух файлов: compose.yaml плюс compose.override.yaml даёт то, что запустится. Ниже явное наложение через два флага -f с выносками «основа» и «поверх неё».
Override подхватывается сам — на сервере это и приводит к неожиданностям. Порядок флагов -f и есть порядок наложения: последний побеждает.

Файл отличий содержит только отличия. Например, лимиты для сервера.

compose.prod.yaml
services:
  app:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"

Ключ deploy.resources.limits — те же --memory и --cpus из прошлого раздела, только строками файла. Слово deploy досталось от Docker Swarm, старого оркестратора Docker, где этот раздел описывал выкат на кластер; лимиты из него обычный Compose тоже применяет. На сервере набор файлов задают явно: флагом -f на каждый файл, по порядку.

ubuntu@stand:~$
docker compose -f compose.yaml -f compose.prod.yaml ps
ubuntu@stand:~$
NAME              SERVICE   STATUS
provision-app-1   app       Up 2 minutes
provision-db-1    db        Up 2 minutes (healthy)

Набирать два -f каждый раз утомительно и опасно: однажды забудешь. Поэтому на сервере набор файлов записывают в .env переменной COMPOSE_FILE=compose.yaml:compose.prod.yaml, и дальше работают обычные короткие команды.

Правила слияния

Наложение работает не так, как кажется. Одиночные значения — образ, команда — заменяются: побеждает последний файл. А списки складываются: порты, тома из двух файлов объединятся.

Три правила слияния с примерами: списки объединяются, в отображениях побеждает последнее значение ключа, скаляры заменяются целиком.
Порты из двух файлов сложатся, а образ просто заменится. Что получилось, надёжнее смотреть через docker compose config.

Отсюда главное правило раскладки. Если в основном файле опубликован порт приложения, файл поверх с ports: [] его не уберёт: пустой список просто сложится с непустым, и публикация доедет до сервера. Убрать можно только специальным тегом YAML !reset, который есть в Compose с версии 2.24.

compose.prod.yaml, сброс списка
services:
  app:
    ports: !reset []

Тег !reset значит «забудь, что было в файлах раньше, и возьми это». Его родственник !override заменяет список новым целиком. Работает надёжно, но держится на том, что кто-то не забудет его написать. Поэтому в общем файле держат минимум, а всё опасное — открытые порты, код с диска, отладку — добавляют только в файл разработки. Не «в общем всё, а на сервере отключим»: отключение легко потерять, а лишнее, которого нет в общем файле, на сервер не попадёт никогда.

Проверить итог

Читать три файла и складывать их в голове — путь к ошибке. Итог показывает config с тем же набором файлов, а grep -c считает совпавшие строки.

ubuntu@stand:~$
docker compose config | grep -c published
ubuntu@stand:~$
1

Здесь, без COMPOSE_FILE, работает разработка: основной файл и override, и опубликован один порт. С серверным набором ожидаем ноль публикаций у приложения.

Есть ещё профили — сервисы, которые не поднимаются без явного --profile, например веб-интерфейс к базе для отладки. Здесь нам достаточно знать, что такое есть: встретишь ключ profiles в чужом файле — это он.

Словарь урока

${ИМЯ:?текст}
Обязательная подстановка: без значения запуск прерывается с этим текстом.
compose.override.yaml
Файл отличий, который Compose накладывает сам. Для разработки; на сервере набор файлов задают явно.
COMPOSE_FILE
Переменная со списком файлов через двоеточие. Записывается в .env сервера, чтобы не набирать -f.

Что спросят на собеседовании

  • Как из одного описания получить разработку и сервер?
    Общее в compose.yaml, отличия разработки в compose.override.yaml, отличия сервера в compose.prod.yaml с явным перечислением файлов. Итог проверяют командой config.
  • Почему на сервере набор файлов задают явно?
    Чтобы случайно оказавшийся рядом override не подхватился сам: он может открыть порты, смонтировать код с диска и включить отладку.

Что дальше

Различия между окружениями описаны. Дальше — практика: развести стенд на разработку и сервер и доказать, что отличаются они ровно тем, чем задумано.

Проверь себя+170 XPдве попытки
1
Подстановка
Что даст запись ${APP_PORT:-8012}, если переменная не задана?
2
Файлы отличий
Что Compose делает с compose.override.yaml, лежащим рядом?
3
Правила слияния
В основном файле у сервиса опубликован порт. Можно ли убрать его файлом поверх?
4
Проверка итога
Как увидеть, что реально запустится на сервере?
ответь на все вопросы, чтобы проверить

Нашёл ошибку или непонятное место? Наведи на абзац — слева появится «+», нажми и напиши, что не так. Замечание увидит автор курса.Нашёл ошибку или непонятное место? Нажми «+» справа от заголовка раздела и напиши, что не так. Замечание увидит автор курса.