Provision
—— XP

Практика: стенд одним файлом

практика~40 минут+425 XP

Стенд сейчас держится на памяти: контейнер prod запущен длинной командой с флагами, и повторить её на другой машине можно только по паспорту образа. В этой практике ты напишешь свой первый compose.yaml и начнёшь с самого маленького файла, который Compose согласится запустить. Потом будешь добавлять по одной настройке и после каждой смотреть, что изменилось. Приложение — то самое, что ты собрал в разделе про Docker: Compose будет собирать его из твоего Dockerfile в ~/infra/app. База данных появится ближе к концу, когда приложение уже работает.

Шаг 1. Освободить порт

Контейнер prod из миссии прошлого раздела занимает порт 8012, который скоро понадобится. Удаляем его: флаг -f (force, «силой») останавливает и удаляет работающий контейнер одной командой.

ubuntu@stand:~$
docker rm -f prod

Реестр registry не трогаем.

Шаг 2. Пустой файл

Описание стенда будет лежать в репозитории ~/infra рядом с каталогом приложения. Создаём каталог и переходим в него: все команды Compose дальше выполняются отсюда, потому что Compose ищет файл в текущем каталоге.

ubuntu@stand:~$
mkdir -p ~/infra/stand
ubuntu@stand:~$
cd ~/infra/stand

Команда touch создаёт пустой файл. Сразу спросим Compose, что он в нём видит: docker compose config читает описание и печатает его так, как понял.

ubuntu@stand:~$
touch compose.yaml
ubuntu@stand:~$
docker compose config
ubuntu@stand:~$
empty compose file

Ответ честный: файл есть, описания в нём нет. Команду config ты будешь запускать после каждого шага — она ничего не запускает и показывает ошибку раньше, чем её увидит up.

Шаг 3. Имя проекта

Открой файл в редакторе и напиши одну строку.

nano ~/infra/stand/compose.yaml
name: provision

name — имя проекта. Из него Compose собирает имена всего, что создаёт: контейнеров, сети, томов. Без этой строки имя бралось бы из названия каталога, и переименование каталога тихо создало бы новый проект с пустыми томами — об этом был урок про устройство файла.

ubuntu@stand:~$
docker compose config
ubuntu@stand:~$
name: provision
services: {}

Файл уже правильный, но запускать нечего: services: {} — пустой список сервисов. Сервис в Compose — описание одного контейнера: из чего он запускается и с какими настройками.

Шаг 4. Первый сервис

Добавь под именем раздел services и в нём сервис app. Отступы — пробелами, по два на уровень: в YAML вложенность задаётся именно ими.

nano ~/infra/stand/compose.yaml
name: provision

services:
  app:
    build: ../app

У сервиса одна строка. build говорит: образа нет, собери его сам, а ../app — путь к каталогу с Dockerfile относительно этого файла. Две точки значат «каталог уровнем выше», то есть ~/infra. Это тот же контекст сборки, что точка в команде docker build ..

Есть и второй способ: строка image: localhost:5000/provision/app:1.0.0 взяла бы готовый образ из реестра. build удобен, пока ты сам меняешь код, image — на сервере, где образ уже собран конвейером. Сейчас нам нужен первый.

Поднимаем. Флаг -d (detached, «отсоединённый») запускает стек в фоне и возвращает приглашение, как у docker run -d.

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
[+] Building 41.3s (17/17) FINISHED
 ✔ Image provision-app      Built
 ✔ Network provision_default  Created
 ✔ Container provision-app-1  Started

Compose собрал образ provision-app, создал сеть проекта и запустил контейнер. Сеть ты не просил — Compose заводит её сам на каждый проект. Посмотрим состояние.

ubuntu@stand:~$
docker compose ps
ubuntu@stand:~$
NAME              IMAGE           COMMAND                  SERVICE   CREATED         STATUS                            PORTS
provision-app-1   provision-app   "gunicorn --bind 0.0…"   app       9 seconds ago   Up 9 seconds (health: starting)

health: starting — это HEALTHCHECK из твоего Dockerfile: Docker уже проверяет приложение, через десять секунд станет healthy. Колонка портов пустая.

Шаг 5. Приложение работает, но снаружи не видно

Что делает приложение, видно по его журналу: docker compose logs показывает вывод сервиса, флаг --tail 2 — две последние строки.

ubuntu@stand:~$
docker compose logs app --tail 2
ubuntu@stand:~$
app-1  | [2026-10-11 15:48:19 +0000] [7] [INFO] Booting worker with pid: 7
app-1  | [2026-10-11 15:48:19 +0000] [8] [INFO] Booting worker with pid: 8

Gunicorn запустил два рабочих процесса и слушает порт 8000 внутри контейнера. А с самой машины приложение видно?

ubuntu@stand:~$
curl -sS localhost:8012/health
ubuntu@stand:~$
curl: (7) Failed to connect to localhost port 8012 after 0 ms: Couldn't connect to server

Флаг -s убирает индикатор загрузки, а -S при этом оставляет сообщения об ошибках. Ошибка 7 у curl значит «не удалось подключиться». Так и должно быть: порт мы не публиковали, и контейнер изолирован от машины. Это и есть минимальный рабочий стенд — один сервис, собранный из твоего Dockerfile. Дальше наращиваем.

Шаг 6. Порт

Добавь сервису app раздел ports — с тем же отступом, что у build.

compose.yaml, у сервиса app
    ports:
      - "127.0.0.1:8012:8000"

Дефис в YAML начинает элемент списка: портов может быть несколько. Запись та же, что у флага -p: адрес машины, порт машины, порт контейнера. Адрес 127.0.0.1 — петля: приложение видно только с самой машины, как было у prod. Без адреса порт открылся бы на всех интерфейсах, то есть для всей сети. Кавычки обязательны: YAML иначе может прочитать числа через двоеточие как время.

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

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Container provision-app-1  Recreated
ubuntu@stand:~$
curl -s localhost:8012/health
ubuntu@stand:~$
ok

Шаг 7. Переменные окружения и перезапуск

Приложение берёт своё имя из переменной окружения APP_NAME. Раздел environment — то же, что флаг -e. Заодно добавим политику перезапуска.

compose.yaml, у сервиса app
    environment:
      APP_NAME: stand
    restart: unless-stopped

Версию приложение тоже умеет брать из APP_VERSION, но её мы не задаём: версия живёт в коде и меняется вместе с ним, в разделе про CI/CD так и будет.

restart решает, что делать, когда контейнер остановился сам. Вариантов четыре: no — ничего, так по умолчанию; on-failure — поднять, только если программа завершилась с ошибкой; always — поднимать всегда, даже после ручной остановки, при перезапуске Docker; unless-stopped — поднимать всегда, кроме случая, когда ты остановил контейнер сам. Для сервиса стенда подходит последний: после перезагрузки машины стенд поднимется, а остановленный тобой — нет.

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Container provision-app-1  Recreated
ubuntu@stand:~$
curl -s localhost:8012/whoami
ubuntu@stand:~$
{"app":"stand","host":"9b6e9aa9888d","pid":8,"version":"1.0.0"}

Имя пришло из описания. Обрати внимание на host: он сменился, потому что контейнер пересоздан. Контейнеры в Compose одноразовые, и это нормально — ничего ценного внутри них не хранят.

Шаг 8. Значения в отдельном файле

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

compose.yaml, у сервиса app, строка имени
      APP_NAME: ${APP_NAME}

Посмотрим, что получилось, пока .env нет.

ubuntu@stand:~$
docker compose config app | grep APP_NAME
ubuntu@stand:~$
WARN[0000] The "APP_NAME" variable is not set. Defaulting to a blank string.
      APP_NAME: ""

После config можно назвать один сервис — так вывод короче. Переменной нет, и Compose подставил пустую строку, отделавшись предупреждением. Теперь создаём .env: строка вида ИМЯ=значение, без пробелов вокруг =.

nano ~/infra/stand/.env
APP_NAME=stand
ubuntu@stand:~$
docker compose config app | grep APP_NAME
ubuntu@stand:~$
      APP_NAME: stand

У подстановки есть варианты. ${APP_NAME:-stand} возьмёт stand, если переменной нет: так в .env пишут только то, что отличается. ${APP_NAME:?текст} наоборот прервёт запуск с этим текстом — так помечают обязательное. Подробно о них — в уроке про переменные и окружения, пока хватит простой формы.

Файл .env в репозиторий не кладут. Правило для него уже есть: ты завёл его в .gitignore репозитория в разделе про Git, и правило без слэша действует на любой глубине. Убедимся: git check-ignore -v печатает, какое правило сработало.

ubuntu@stand:~$
git -C ~/infra check-ignore -v stand/.env
ubuntu@stand:~$
.gitignore:2:.env	stand/.env

Строка 2 файла .gitignore, правило .env. Если команда ничего не напечатала, правила нет — допиши строку .env в ~/infra/.gitignore.

А коллеге оставим шаблон без значений: по нему видно, какие переменные нужны.

nano ~/infra/stand/.env.example
APP_NAME=
POSTGRES_PASSWORD=

Вторая строка — на следующий шаг. Применяем и проверяем имя.

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Container provision-app-1  Recreated
ubuntu@stand:~$
curl -s localhost:8012/whoami
ubuntu@stand:~$
{"app":"stand","host":"ed4d1442aa1f","pid":8,"version":"1.0.0"}

Имя то же, но теперь оно пришло из .env, а не из описания.

Шаг 9. Самая простая база

Приложению давно нужна база: адрес /items считает строки в таблице. Добавляем второй сервис — ниже app, с тем же отступом в два пробела.

compose.yaml, раздел services, после app
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: provision
      POSTGRES_DB: provision
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    restart: unless-stopped

Здесь image, а не build: свой Dockerfile для PostgreSQL не нужен, берём готовый официальный образ. Политика перезапуска та же, что у приложения. Три переменные образ читает при первом запуске: создать пользователя provision, базу provision и задать пароль. Пользователь и имя базы не секрет и написаны прямо, пароль — подстановкой. Допиши его в .env.

nano ~/infra/stand/.env
APP_NAME=stand
POSTGRES_PASSWORD=provision-local-pass

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

Шаг 10. Приложение находит базу

Приложение берёт адрес базы из переменной DATABASE_URL. Добавь её в environment сервиса app, а под ним — depends_on.

compose.yaml, у сервиса app
      DATABASE_URL: postgres://provision:${POSTGRES_PASSWORD}@db:5432/provision
    depends_on:
      - db

Строка подключения читается так: протокол postgres, пользователь и пароль, адрес, порт 5432, имя базы. Вместо адреса — db, имя сервиса: Compose сам связывает имена сервисов с их адресами в сети проекта. depends_on велит запускать app после db. Что именно он гарантирует, а что нет, — тема следующего урока.

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Container provision-db-1   Started
 ✔ Container provision-app-1  Recreated
ubuntu@stand:~$
docker compose exec app getent hosts db
ubuntu@stand:~$
192.168.32.2    db

getent hosts спрашивает адрес по имени — так же, как это делает программа. Имя db разрешилось. Спросим приложение о данных.

ubuntu@stand:~$
curl -si localhost:8012/items | head -1
ubuntu@stand:~$
HTTP/1.1 500 INTERNAL SERVER ERROR

Флаг -i добавляет к ответу заголовки, head -1 оставляет первую строку — в ней код ответа. Код 500 — ошибка внутри приложения. Её причину покажет журнал сервиса, --tail 3 оставит три последние строки.

ubuntu@stand:~$
docker compose logs app --tail 3
ubuntu@stand:~$
app-1  |     cur.execute("SELECT count(*) FROM visits")
app-1  | psycopg2.errors.UndefinedTable: relation "visits" does not exist

Приложение до базы достучалось, но в ней нет таблицы visits. База новая и пустая.

Шаг 11. Таблица в базе

Зайдём в клиент базы psql внутри контейнера. Флаг -U задаёт пользователя.

ubuntu@stand:~$
docker compose exec db psql -U provision

Приглашение сменится на provision=# — это уже psql. Набери две команды SQL и выйди.

внутри psql
provision=# CREATE TABLE visits (id serial PRIMARY KEY);
CREATE TABLE
provision=# INSERT INTO visits DEFAULT VALUES;
INSERT 0 1
provision=# \q

Первая создаёт таблицу visits с одной колонкой id. serial значит «номер строки ставит сама база, по порядку», PRIMARY KEY — «по этому номеру строки различаются». Вторая добавляет строку, не указывая значений. \q выходит из psql. Подробно про SQL — в разделе про базы данных, а руками это делается временно: в следующей практике таблицу создаст миграция.

ubuntu@stand:~$
curl -s localhost:8012/items
ubuntu@stand:~$
{"visits":1}

Цепочка работает: запрос пришёл в приложение, приложение по имени db дошло до базы и прочитало таблицу.

Шаг 12. Где живут данные

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

ubuntu@stand:~$
docker compose down
ubuntu@stand:~$
 ✔ Container provision-app-1  Removed
 ✔ Container provision-db-1   Removed
 ✔ Network provision_default  Removed
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Network provision_default  Created
 ✔ Container provision-db-1   Started
 ✔ Container provision-app-1  Started
ubuntu@stand:~$
curl -si localhost:8012/items | head -1
ubuntu@stand:~$
HTTP/1.1 500 INTERNAL SERVER ERROR

Таблицы снова нет. Данные базы лежали в контейнере, а down его удалил — новый контейнер начал с чистой базы. Лечится томом из раздела про Docker: каталог данных базы выносят из контейнера. Добавь сервису db раздел volumes, а в конец файла, без отступа, объявление тома.

compose.yaml, у сервиса db
    volumes:
      - pgdata:/var/lib/postgresql/data
compose.yaml, конец файла
volumes:
  pgdata:

Слева от двоеточия — имя тома, справа — каталог в контейнере, где PostgreSQL хранит данные. Пустое значение после pgdata: значит «с настройками по умолчанию». Вместо имени тома можно указать путь на машине, например ./data:/var/lib/postgresql/data, — это монтирование каталога, его удобно открыть руками, но права и владельца файлов придётся держать самому. Для базы обычно берут именованный том.

Применяем, снова создаём таблицу (шаг 11) и повторяем снос и подъём.

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Volume provision_pgdata  Created
ubuntu@stand:~$
docker compose down
ubuntu@stand:~$
 ✔ Container provision-app-1  Removed
 ✔ Container provision-db-1   Removed
 ✔ Network provision_default  Removed
ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Network provision_default  Created
 ✔ Container provision-db-1   Started
 ✔ Container provision-app-1  Started
ubuntu@stand:~$
curl -s localhost:8012/items
ubuntu@stand:~$
{"visits":1}

Контейнеры новые, строка на месте: она в томе provision_pgdata, а down без флага -v тома не трогает. С флагом -v удалились бы и они — вместе с данными.

У пароля базы теперь есть особенность. POSTGRES_PASSWORD действует только при первом запуске на пустом томе. Дальше пароль хранится внутри базы, в томе, и правка .env его не меняет: приложение придёт с новым паролем, а база будет ждать старый. Поменять пароль у живой базы можно командой SQL, а на учебном стенде проще удалить том.

Шаг 13. Своя сеть

Пока сервисы общаются через сеть provision_default, которую Compose создаёт сам. Её достаточно, но её не видно в описании: по файлу не скажешь, кто с кем может говорить. Объявим сеть явно. В конец файла, без отступа:

compose.yaml, конец файла
networks:
  stand:

И подключим к ней каждый сервис — у app и у db одинаково, с отступом как у environment.

compose.yaml, у сервиса app и у сервиса db
    networks:
      - stand

Сервис без раздела networks попадает в сеть default. Как только раздел есть, сервис подключается только к перечисленным сетям. Поэтому подключать надо каждый сервис: забытый останется в default и не найдёт соседей по имени.

ubuntu@stand:~$
docker compose up -d
ubuntu@stand:~$
 ✔ Network provision_stand  Created
 ✔ Container provision-db-1   Recreated
 ✔ Container provision-app-1  Recreated
ubuntu@stand:~$
curl -s localhost:8012/items
ubuntu@stand:~$
{"visits":1}

Старая сеть provision_default осталась: Compose удаляет только то, что есть в описании, а её там больше нет, — не уберёт её и docker compose down. Проверь список: grep оставит сети проекта.

ubuntu@stand:~$
docker network ls --format '{{.Name}}' | grep provision_
ubuntu@stand:~$
provision_default
provision_stand

Пустую сеть удаляем руками.

ubuntu@stand:~$
docker network rm provision_default
ubuntu@stand:~$
provision_default

Свои сети нужны, когда их больше одной. Например, прокси видит приложение, а базу — нет: прокси и приложение в одной сети, приложение и база — во второй. У сети бывает настройка internal: true — такая сеть не выпускает контейнеры в интернет. А external: true подключает сеть, созданную вне этого проекта, — так соседние стеки на одной машине ходят друг к другу.

Шаг 14. Что получилось

Сверь свой файл. Начало — имя и приложение:

~/infra/stand/compose.yaml, начало
name: provision

services:
  app:
    build: ../app
    ports:
      - "127.0.0.1:8012:8000"
    environment:
      APP_NAME: ${APP_NAME}
      DATABASE_URL: postgres://provision:${POSTGRES_PASSWORD}@db:5432/provision
    depends_on:
      - db
    networks:
      - stand
    restart: unless-stopped

Дальше — база, том и сеть:

~/infra/stand/compose.yaml, конец
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: provision
      POSTGRES_DB: provision
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - stand
    restart: unless-stopped

volumes:
  pgdata:

networks:
  stand:

Порядок разделов внутри сервиса Compose не важен, важны отступы. Чего здесь нет: проверки готовности базы, миграции вместо ручного SQL, отдельных настроек для сервера. Это следующие уроки раздела — сначала то, что работает, потом то, что делает его надёжнее.

Одна деталь про сборку. Поправишь код в ~/infra/app — docker compose up -d образ не пересоберёт, он соберёт его только если образа нет. Пересборку просят флагом --build.

ubuntu@stand:~$
docker compose up -d --build
ubuntu@stand:~$
 ✔ Image provision-app        Built
 ✔ Container provision-app-1  Recreated

Шаг 15. Зафиксировать

Описание стенда — в репозиторий. Убедимся, что .env туда не попадёт: флаг --short показывает изменения строкой на файл.

ubuntu@stand:~$
git -C ~/infra add stand
ubuntu@stand:~$
git -C ~/infra status --short
ubuntu@stand:~$
A  stand/.env.example
A  stand/compose.yaml

.env в списке нет — Git его игнорирует. Фиксируем.

ubuntu@stand:~$
git -C ~/infra commit -m "stand: compose.yaml"

Если что-то не работает

Ошибки здесь почти всегда видны в docker compose config или в журнале одного сервиса.

Симптом и причина
empty compose file
Файл пустой или сохранён не туда: проверь, что ты в ~/infra/stand.
port is already allocated
8012 ещё занят контейнером prod: docker rm -f prod.
The variable is not set. Defaulting to a blank string
Нет файла .env рядом с compose.yaml или переменная в нём названа иначе.
/items отвечает 503 database unavailable
Приложение не достучалось до базы: проверь DATABASE_URL в docker compose config app и docker compose logs db.
/items отвечает 500
База доступна, но в ней нет таблицы visits: шаг 11.
mapping values are not allowed here
Ошибка отступов в YAML: сервис или ключ сдвинут на пробел.

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

  • Чем build отличается от image в описании сервиса?
    build собирает образ из Dockerfile в указанном каталоге, image берёт готовый образ из реестра. build удобен при разработке, image — на сервере, куда образ привёз конвейер.
  • Удалит ли docker compose down данные базы?
    Нет, если данные в именованном томе: без флага -v тома остаются. Если тома нет, данные жили в контейнере и пропадут вместе с ним.
  • Зачем объявлять сети, если Compose создаёт сеть сам?
    Чтобы описание показывало, кто с кем связан, и чтобы разделить сервисы: например, прокси видит приложение, но не базу.
Практика 01+425 XP

Шаг за шагом вырастить описание стенда: приложение из своего Dockerfile и база в одной сети, пароль вне репозитория, данные в томе.

  • Приложение работает
  • Приложение собирается из своего Dockerfile
  • База работает
  • Приложение находит базу по имени сервиса
  • Приложение читает данные из базы
  • Данные в томе проекта
  • Своя сеть стенда
  • Пароля нет в описании
  • .env не попадёт в репозиторий
Команда сдачи — выполни на своей машине
команда
cd ~/infra/stand 2>/dev/null || echo NOSTAND; docker compose ps --format 'SVC={{.Service}} STATE={{.State}}'; echo "BUILD=$(docker compose config app | grep -c context)"; docker compose exec -T app getent hosts db; echo "ITEMS=$(curl -s localhost:8012/items)"; docker volume ls --format 'VOL={{.Name}}' | grep pgdata; docker network ls --format 'NET={{.Name}}' | grep provision_; echo "LEAK=$(grep -E 'POSTGRES_PASSWORD:|postgres://' compose.yaml | grep -vc '[$][{]')"; echo "IGNORED=$(git -C ~/infra check-ignore stand/.env)"

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