Зачем в compose переменные
Compose-файл лежит в git и одинаков на всех серверах. То, что у каждого сервера своё или секретно, — каталог
данных, домен, пароли — живёт в .env рядом с ним, только на сервере; в git — .env.example с именами
(«Конфиги серверов в git»). Перед запуском compose берёт значения из .env и вставляет их на место ${…}
(«.env — для подстановки в compose, env_file — внутрь контейнера»).
Что будет, если строку в .env забыли
Новый сервер: репозиторий склонировали, .env заполнили по образцу, одну строку пропустили. В compose:
services:
db:
image: mariadb:${MARIADB_TAG:-11.8}
volumes:
- ${DATA_DIR}/db:/var/lib/mysql
Compose не останавливается. Он пишет одну строку предупреждения — The "DATA_DIR" variable is not set. Defaulting to a blank string. — и поднимает стек. Путь превратился в /db, каталог в корне диска: Docker
создаёт его сам («Несуществующий путь в томе»), база пишет туда, ошибок нет. Когда строку в .env допишут, стек
поднимется с пустым каталогом по правильному пути, а данные останутся в /db.
Как остановить compose с подсказкой
Ставим после имени переменной :? и текст:
- ${DATA_DIR:?DATA_DIR в .env — каталог данных стека, например /opt/app/data}/db:/var/lib/mysql
Теперь без DATA_DIR compose не создаёт ничего и печатает этот текст:
docker compose up -d
# error while interpolating services.db.volumes.[]: required variable DATA_DIR is missing a value: DATA_DIR в .env — каталог данных стека, например /opt/app/data
Текст после ? выглядит как комментарий — потому что так и есть. Compose покажет его, только когда
переменной нет, — тому, кто поднимает стек на новом сервере или через год. Поэтому пишем в нём, где задать переменную и как выглядит
значение. Пустая строка DATA_DIR= в .env останавливает так же.
Где :?, а где :-
:? ставим там, где без значения стек бессмыслен и угадать его нельзя: каталог данных, домен, имя образа,
пароль. Там, где значение по умолчанию подходит, пишем :-: ${MARIADB_TAG:-11.8} без переменной даёт
11.8. Значения прямо в compose, без ${…}, проверять не нужно — запись нужна, когда они уехали в .env.
Все формы подстановки
В своих файлах хватает двух форм, :? и :-. В готовых compose-файлах из README других проектов
встречаются все шесть — таблица, чтобы их читать. Двоеточие значит: пустое значение — то же, что его нет.
| Запись | Переменной нет | X= — пусто |
X=v |
|---|---|---|---|
${X:-d} |
d |
d |
v |
${X-d} |
d |
пусто | v |
${X:?текст} |
ошибка с текстом | ошибка с текстом | v |
${X?текст} |
ошибка с текстом | пусто | v |
${X:+a} |
пусто | пусто | a |
${X+a} |
пусто | a |
a |
:+ переворачивает логику: значение появляется, только когда переменная задана.
Подстановки вкладываются. Домен сервиса — из APP_HOST, без него — app. плюс общий домен стека; DOMAIN
compose проверяет, только когда APP_HOST не задан:
labels:
- "traefik.http.routers.app.rule=Host(`${APP_HOST:-app.${DOMAIN:?DOMAIN в .env — example.org}}`)"
В самом .env можно сослаться на переменную выше: IMAGE=${REGISTRY}/app. Значение в одинарных кавычках
compose не раскрывает — на этом держится перенос хэшей с $ в .env («Знак $»).
Если не работает
up -d падает: unable to get image ':latest', invalid reference format
- Причина
- В compose
image: ${IMAGE}:…без проверки, а переменной нет. Compose подставил пустую строку и отдал Docker образ без имени. То же даёт${IMAGE?…}без двоеточия, если в.envосталась пустая строкаIMAGE=. - Делаем
- Пишем
${IMAGE:?…}: compose остановится с подсказкой ещё до обращения к Docker.
В .env MARIADB_TAG=11.8, а docker compose config показывает другой тег
- Причина
- Переменная с тем же именем есть в окружении shell: из
~/.bashrc, из скрипта илиexportв этой сессии. Окружение главнее.env, даже пустое:MARIADB_TAG=в окружении даёт значение по умолчанию из:-. - Делаем
- Ищем её —
env | grep MARIADB_TAG, убираем —unset MARIADB_TAGи строку в файле, откуда она пришла.
Убрали переменную из .env — теперь падают ps, logs и даже down, а контейнеры работают
- Причина
- Подстановку compose делает во всём файле перед любой командой, и
:?останавливает каждую.docker compose lsпри этом работает: он файл не читает. - Делаем
- Возвращаем строку в
.env. Остановить стек без неё:docker compose -p <имя> down, имя — изdocker compose ls. С-pcompose находит контейнеры по меткам проекта.
Как проверить
Какие переменные ждёт compose-файл, показывает config --variables — даже когда .env ещё нет:
docker compose config --variables
NAME REQUIRED DEFAULT VALUE ALTERNATE VALUE
MARIADB_TAG false 11.8
DATA_DIR true
REQUIRED true — то, что обязано быть в .env. Что подставилось на деле, видно в итоговом файле:
docker compose config | grep source:
# source: /opt/app/data/db