Пошук уроків, статей та іншого контенту
Налаштуєте змінні середовища через compose.yaml, .env і підстановку значень для різних конфігурацій.
Змінні середовища дають змогу зберігати конфігурацію окремо від файлу compose.yaml. Це корисно, коли для різних середовищ потрібно змінювати:
порт, на якому доступний сервіс;
тег Docker-образу;
ім’я бази даних;
облікові дані;
режим роботи застосунку.
Замість редагування compose.yaml можна передати інші значення змінних.
У Docker Compose потрібно розрізняти два поняття:
Підстановка змінних під час обробки compose.yaml.
Передавання змінних усередину контейнера.
Це пов’язані, але не однакові операції.
compose.yamlУ YAML-файлі змінну записують у форматі ${VARIABLE}:
services:
web:
image: nginx:${NGINX_VERSION}
ports:
- "${APP_PORT}:80"Перед запуском Compose замінить ${NGINX_VERSION} і ${APP_PORT} їхніми значеннями.
Якщо значення не задане, Compose може показати попередження й підставити порожній рядок. Щоб зробити змінну обов’язковою, використовуйте синтаксис:
services:
web:
image: my-app:${APP_VERSION:?Задайте APP_VERSION}Якщо APP_VERSION не визначена, Compose завершить обробку з повідомленням про помилку.
Для необов’язкових змінних можна вказати значення за замовчуванням:
services:
web:
image: my-app:${APP_VERSION:-latest}Якщо APP_VERSION не задана або порожня, буде використано latest.
Основні варіанти синтаксису:
${VAR} — підставити значення змінної;
${VAR:-default} — використати default, якщо змінна не задана або порожня;
${VAR-default} — використати default, якщо змінна не задана;
${VAR:?message} — завершити роботу з помилкою, якщо змінна не задана або порожня;
${VAR?message} — завершити роботу з помилкою, якщо змінна не задана.
.envФайл .env зазвичай розміщують поруч із compose.yaml. Compose автоматично читає його та використовує значення для підстановки змінних.
Приклад .env:
APP_PORT=8080
APP_VERSION=1.25
APP_ENV=developmentФайл compose.yaml:
services:
web:
image: nginx:${APP_VERSION}
ports:
- "${APP_PORT}:80"
environment:
APP_ENV: ${APP_ENV}У цьому прикладі:
APP_VERSION визначає тег образу;
APP_PORT визначає порт хоста;
APP_ENV передається всередину контейнера.
Запуск:
docker compose upCompose прочитає .env, підставить значення у файл і створить контейнер.
Файл
.envне копіюється автоматично всередину контейнера. Він використовується Compose як джерело значень для підстановки.
Щоб змінна була доступна процесам усередині контейнера, її потрібно вказати в секції environment або env_file.
environmentЗначення можна записати безпосередньо:
services:
app:
image: node:22-alpine
environment:
NODE_ENV: production
LOG_LEVEL: infoАбо взяти їх із змінних, доступних Compose:
services:
app:
image: node:22-alpine
environment:
NODE_ENV: ${APP_ENV}
LOG_LEVEL: ${LOG_LEVEL:-info}У першому випадку NODE_ENV завжди матиме значення production. У другому його значення залежить від APP_ENV у .env, оболонці або іншому джерелі.
Те саме можна записати у вигляді списку:
services:
app:
environment:
- NODE_ENV=${APP_ENV}
- LOG_LEVEL=${LOG_LEVEL:-info}Для складніших конфігурацій формат ключ-значення зазвичай читати зручніше.
Такий запис:
services:
app:
environment:
- DEBUGозначає: взяти DEBUG із середовища, у якому запускається Compose, і передати її контейнеру.
Якщо DEBUG ніде не визначена, результат може бути неочікуваним. Для передбачуваної конфігурації краще явно використовувати ${DEBUG:-false} або вказати значення в .env.
env_fileСекція env_file передає набір змінних безпосередньо в контейнер:
services:
app:
image: node:22-alpine
env_file:
- app.envФайл app.env:
NODE_ENV=development
LOG_LEVEL=debugЦі змінні будуть доступні всередині контейнера, але не використовуються автоматично для підстановки в інших місцях compose.yaml.
Наприклад:
services:
app:
image: my-app:${APP_VERSION}
env_file:
- app.envЯкщо APP_VERSION міститься лише в app.env, це не гарантує, що Compose зможе використати її в ${APP_VERSION} для назви образу. Для підстановки потрібно, щоб змінна була доступна Compose, наприклад у .env, оболонці або через --env-file.
Створімо невеликий Compose-проєкт із конфігурацією через .env.
Файл .env:
APP_PORT=8080
NGINX_VERSION=1.27-alpine
APP_ENV=developmentФайл compose.yaml:
services:
web:
image: nginx:${NGINX_VERSION}
ports:
- "${APP_PORT}:80"
environment:
APP_ENV: ${APP_ENV:-development}Запустіть сервіс:
docker compose up -dПеревірте список контейнерів:
docker compose psКонтейнер буде доступний на порту 8080 хоста. Усередині контейнера змінна APP_ENV матиме значення development.
Переглянути остаточну конфігурацію після підстановки можна командою:
docker compose configЦе корисний спосіб перевірити, які саме значення Compose побачив до запуску контейнерів.
--env-fileЗамість зміни .env можна створити окремі файли для різних середовищ:
env.dev:
APP_PORT=8080
NGINX_VERSION=1.27-alpine
APP_ENV=developmentenv.prod:
APP_PORT=80
NGINX_VERSION=1.27-alpine
APP_ENV=productionОдин і той самий compose.yaml:
services:
web:
image: nginx:${NGINX_VERSION}
ports:
- "${APP_PORT}:80"
environment:
APP_ENV: ${APP_ENV:?Задайте APP_ENV}Запуск для розробки:
docker compose --env-file env.dev up -dЗапуск для production-конфігурації:
docker compose --env-file env.prod up -dУ результаті Compose використає один YAML-файл, але різні значення змінних.
Під час підстановки Compose може отримати значення з кількох джерел:
змінні, явно передані в командному рядку;
змінні поточного shell-середовища;
файл, переданий через --env-file;
.env у каталозі проєкту.
Наприклад, якщо в .env є:
APP_PORT=8080але перед запуском виконати:
APP_PORT=9000 docker compose configто для поточного запуску буде використано 9000.
Це дає змогу тимчасово перевизначити окреме значення без редагування файлів:
APP_PORT=9000 docker compose up -dНазви змінних чутливі до регістру: APP_PORT і app_port — різні змінні.
$Compose обробляє $ як початок підстановки змінної. Якщо символ $ має потрапити в контейнер без обробки Compose, використовуйте $$.
services:
app:
image: alpine:3.20
command: ["sh", "-c", "echo $$HOME"]У контейнер потрапить команда:
echo $HOMEТому оболонка всередині контейнера зможе обробити $HOME, а Compose не намагатиметься підставити змінну під час читання YAML-файлу.
Файл .env часто містить локальні налаштування, а іноді й секрети. Не додавайте такі файли до системи контролю версій, якщо вони містять паролі або токени.
Зазвичай до .gitignore додають:
.env
env.*.localДля командної роботи можна зберігати приклад без реальних значень, наприклад .env.example:
APP_PORT=8080
NGINX_VERSION=1.27-alpine
APP_ENV=developmentРозробник копіює його у власний .env і змінює значення за потреби:
cp .env.example .envЗмінні середовища зручні для конфігурації, але не слід вважати .env захищеним сховищем секретів. Його вміст може бути доступний користувачам і процесам, які мають доступ до файлів проєкту.
.env автоматично з’явиться в контейнері.env використовується для підстановки Compose. Щоб передати конкретні значення контейнеру, потрібно додати їх через environment або env_file.
env_file для підстановки в YAMLenv_file призначений для формування середовища контейнера. Для ${VARIABLE} у самому compose.yaml використовуйте .env, --env-file або змінні shell-середовища.
Такий запис:
services:
web:
image: nginx:${NGINX_VERSION}може призвести до некоректної назви образу, якщо NGINX_VERSION не задана. Для обов’язкової змінної використовуйте перевірку:
services:
web:
image: nginx:${NGINX_VERSION:?Задайте NGINX_VERSION}У записі:
ports:
- "${APP_PORT}:80"ліва частина — порт хоста, а права — порт усередині контейнера. Зміна APP_PORT змінює порт доступу з хоста, але не порт, на якому працює Nginx у контейнері.
Не комітьте .env із реальними паролями, ключами та токенами. Залишайте в репозиторії лише шаблон із тестовими або порожніми значеннями.
${VARIABLE} використовується для підстановки значень у compose.yaml.
.env поруч із compose.yaml є стандартним джерелом значень для підстановки.
--env-file дає змогу вибрати інший файл конфігурації.
Секція environment передає змінні всередину контейнера.
env_file передає контейнеру набір змінних, але не є універсальним джерелом для підстановки в YAML.
Використовуйте значення за замовчуванням для необов’язкових параметрів і перевірки ${VAR:?message} для обов’язкових.
Команда docker compose config допомагає перевірити результат підстановки.
Файли з реальними секретами не слід зберігати в репозиторії.