re:re:actable
Урок 053 минуты чтения

Как передавать переменные окружения из Compose в приложение

На этой странице
Кратко

В Compose есть два разных механизма. Подстановка (interpolation): ${VAR} в YAML заменяется значением из shell или файла .env рядом с compose.yaml — это настройка самого файла. Передача в контейнер: поля environment и env_file создают переменные окружения процесса, которые приложение читает через process.env. Значение в .env само по себе в контейнер не попадает. Для frontend-переменных SPA (VITE_*) есть третий этап — сборка: они вшиваются в бандл и публичны. У Nuxt публичный runtimeConfig (NUXT_PUBLIC_*) читается при запуске сервера, поэтому его передают через environment.

Вопрос

Как Compose передаёт переменные окружения в контейнер и чем .env отличается от env_file?

Три уровня

.env рядом с compose.yaml ──подстановка──▶ ${VAR} в YAML
environment / env_file    ──────────────▶ process.env в контейнере
build.args                ──────────────▶ ARG при сборке (VITE_*)

Подстановка в YAML

# .env
TAG=1.4.0
DB_PASSWORD=dev-password
services:
  api:
    image: ghcr.io/team/api:${TAG:-latest}
    environment:
      DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
СинтаксисЗначение
${VAR}Значение или пустая строка
${VAR:-default}По умолчанию, если не задано или пусто
${VAR:?message}Ошибка с сообщением, если не задано
$$Литеральный $

Передача в контейнер

services:
  api:
    env_file:
      - .env.api              # все переменные файла попадут в контейнер
    environment:
      NODE_ENV: production    # приоритет выше, чем у env_file
      PORT: 3000
      LOG_LEVEL:              # без значения — взять из окружения shell

Приоритет (от высшего): docker compose run -e → environment → env_file → ENV в Dockerfile.

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

docker compose config                    # YAML после подстановки
docker compose exec api printenv | sort  # что реально видит процесс

Переменные применяются при создании контейнера. После изменения .env нужен docker compose up -d — Compose пересоздаст изменённые сервисы. restart контейнер не пересоздаёт и новые значения не подхватит.

Валидация на старте

import { z } from "zod";
 
const env = z
  .object({
    DATABASE_URL: z.string().url(),
    PORT: z.coerce.number().default(3000),
    JWT_SECRET: z.string().min(32),
  })
  .parse(process.env);

Приложение должно падать сразу с понятной ошибкой, если переменной нет, а не через час на первом запросе.

Frontend-переменные

services:
  web:
    build:
      context: ./web
      args:
        VITE_API_URL: /api         # попадёт в бандл при сборке

environment для собранного SPA бесполезен: код уже в браузере. Для Nuxt-сервера наоборот: NUXT_PUBLIC_API_BASE в environment подхватится при старте без пересборки. Всё, что передано в VITE_* или NUXT_PUBLIC_*, видно пользователю.

Секреты

environment удобен для конфигурации, но значения видны в docker inspect и могут попасть в логи. Для паролей в production используют Compose secrets, secret manager платформы или как минимум файл, который не попадает в git, — см. урок про секреты.

Частые ошибки

  • Ждать, что переменная из .env сама появится в контейнере.
  • Путать .env (подстановка) и env_file (передача).
  • Делать restart вместо up -d после изменения переменных.
  • Коммитить .env с реальными паролями вместо .env.example.
  • Класть секреты во frontend-переменные.

Что важно помнить

  • .env настраивает Compose, environment/env_file настраивают приложение.
  • docker compose config и printenv — два шага проверки.
  • Frontend-переменные — build-time и публичны.

Мини-шпаргалка

  • ${VAR:-default}, ${VAR:?error}.
  • environment > env_file > ENV.
  • Изменил переменные → docker compose up -d.
  • Проверка: config, exec printenv.
  • В git — .env.example.

Документация

Docker: Environment variables in Compose, Docker: Set environment variables, Docker: Interpolation.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам