basforge

Ищем по названиям, тексту и разборам «Если не работает».

    EN

    Обязательная переменная в compose: ${X:?подсказка}

    Если переменной нет в .env, compose подставляет пустую строку и поднимает стек дальше. Запись ${DATA_DIR:?подсказка} вместо ${DATA_DIR} останавливает его сразу и печатает подсказку: какую строку дописать в .env.

    Зачем в 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. С -p compose находит контейнеры по меткам проекта.

    Как проверить

    Какие переменные ждёт 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